0
# Extension Runners
1

2
Browser automation system for running extensions in development mode with support for Firefox desktop, Firefox Android, and Chromium browsers. Provides hot reloading, profile management, and cross-platform testing capabilities.
3

4
## Capabilities
5

6
### Run Function
7

8
Launch extensions in browsers with comprehensive configuration options for development and testing.
9

10
```javascript { .api }
11
/**
12
 * Run an extension in one or more browsers
13
 * @param params - Run configuration parameters
14
 * @param options - Optional dependencies and settings
15
 * @returns Promise that resolves when runner is stopped
16
 */
17
function run(params: RunParams, options?: RunOptions): Promise<void>;
18

19
interface RunParams {
20
  /** Source directory containing the extension */
21
  sourceDir: string;
22
  /** Directory for build artifacts */
23
  artifactsDir: string;
24
  /** Target browsers to run ['firefox-desktop', 'firefox-android', 'chromium'] */
25
  target?: string[];
26
  /** Path or alias to Firefox binary (firefox, beta, nightly, deved) */
27
  firefox?: string;
28
  /** Firefox profile path or name to use */
29
  firefoxProfile?: string;
30
  /** Create profile if it doesn't exist */
31
  profileCreateIfMissing?: boolean;
32
  /** Keep profile changes after exit */
33
  keepProfileChanges?: boolean;
34
  /** Path to Chromium binary */
35
  chromiumBinary?: string;
36
  /** Path to custom Chromium profile */
37
  chromiumProfile?: string;
38
  /** Enable automatic extension reloading on file changes */
39
  reload?: boolean;
40
  /** Specific files to watch for reloading */
41
  watchFile?: string[];
42
  /** Paths to ignore when watching for changes */
43
  watchIgnored?: string[];
44
  /** Pre-install extension into profile before startup */
45
  preInstall?: boolean;
46
  /** Custom Firefox preferences */
47
  pref?: string[];
48
  /** URLs to open at startup */
49
  startUrl?: string[];
50
  /** Open DevTools for the extension */
51
  devtools?: boolean;
52
  /** Open Browser Console */
53
  browserConsole?: boolean;
54
  /** Additional CLI arguments for browser */
55
  args?: string[];
56
  /** Disable user input features */
57
  noInput?: boolean;
58
  /** Files to ignore during operations */
59
  ignoreFiles?: string[];
60
  /** Enable verbose logging */
61
  verbose?: boolean;
62
}
63

64
interface RunOptions {
65
  /** Custom build function */
66
  build?: Function;
67
  /** Desktop notification handler */
68
  desktopNotifications?: Function;
69
  /** Firefox app utilities */
70
  firefoxApp?: any;
71
  /** Firefox remote debugging client */
72
  firefoxClient?: Function;
73
  /** Manifest validator */
74
  getValidatedManifest?: Function;
75
  /** Extension runner factory */
76
  createExtensionRunner?: Function;
77
  /** Multi-extension runner class */
78
  MultiExtensionRunner?: any;
79
  /** Reload strategy implementation */
80
  reloadStrategy?: any;
81
}
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
import { cmd } from "web-ext";
88

89
// Basic Firefox run
90
await cmd.run({
91
  sourceDir: './my-extension',
92
  target: ['firefox-desktop']
93
});
94

95
// Run with custom Firefox and profile
96
await cmd.run({
97
  sourceDir: './extension',
98
  target: ['firefox-desktop'],
99
  firefox: 'firefox-nightly',
100
  firefoxProfile: './test-profile',
101
  startUrl: ['https://example.com'],
102
  devtools: true
103
});
104

105
// Run on multiple browsers
106
await cmd.run({
107
  sourceDir: './extension',
108
  target: ['firefox-desktop', 'chromium'],
109
  chromiumBinary: 'google-chrome',
110
  reload: true,
111
  verbose: true
112
});
113

114
// Firefox Android development
115
await cmd.run({
116
  sourceDir: './extension',
117
  target: ['firefox-android'],
118
  adbDevice: 'emulator-5554',
119
  firefoxApk: 'org.mozilla.fenix'
120
});
121
```
122

123
### Extension Runner Factory
124

125
Create browser-specific extension runners with unified interface.
126

127
```javascript { .api }
128
/**
129
 * Create an extension runner for specified target browser
130
 * @param params - Runner creation parameters
131
 * @returns Promise resolving to extension runner instance
132
 */
133
function createExtensionRunner(params: ExtensionRunnerParams): Promise<ExtensionRunner>;
134

135
interface ExtensionRunnerParams {
136
  /** Target browser type */
137
  target: 'firefox-desktop' | 'firefox-android' | 'chromium';
138
  /** Extension source directory */
139
  sourceDir: string;
140
  /** Build artifacts directory */
141
  artifactsDir: string;
142
  /** Desktop notification handler */
143
  desktopNotifications: Function;
144
  /** Browser-specific options */
145
  [key: string]: any;
146
}
147

148
interface ExtensionRunner {
149
  /** Get name of the runner */
150
  getName(): string;
151
  /** Check if runner supports reloading */
152
  reloadAllowed(): boolean;
153
  /** Start the browser with extension */
154
  run(): Promise<any>;
155
  /** Reload the extension */
156
  reloadExtension(): Promise<void>;
157
  /** Exit the runner */
158
  exit(): Promise<void>;
159
}
160
```
161

162
### Multi-Extension Runner
163

164
Manage multiple browser targets simultaneously.
165

166
```javascript { .api }
167
class MultiExtensionRunner {
168
  constructor(params: MultiRunnerParams);
169
  /** Start all configured runners */
170
  run(): Promise<void>;
171
  /** Reload extensions in all runners */
172
  reloadAllExtensions(): Promise<void>;
173
  /** Exit all runners */
174
  exit(): Promise<void>;
175
}
176

177
interface MultiRunnerParams {
178
  /** Array of extension runners */
179
  runners: ExtensionRunner[];
180
  /** Desktop notification handler */
181
  desktopNotifications: Function;
182
  /** Should exit process on completion */
183
  shouldExitProgram: boolean;
184
}
185
```
186

187
### Firefox Desktop Runner
188

189
Specialized runner for Firefox desktop with profile management and debugging support.
190

191
```javascript { .api }
192
interface FirefoxDesktopRunner extends ExtensionRunner {
193
  /** Firefox-specific configuration */
194
  firefox: string;
195
  firefoxProfile?: string;
196
  keepProfileChanges: boolean;
197
  profileCreateIfMissing: boolean;
198
  args: string[];
199
  pref: object;
200
  startUrl: string[];
201
  devtools: boolean;
202
  browserConsole: boolean;
203
}
204
```
205

206
### Firefox Android Runner
207

208
Specialized runner for Firefox on Android devices via ADB.
209

210
```javascript { .api }
211
interface FirefoxAndroidRunner extends ExtensionRunner {
212
  /** ADB binary path */
213
  adbBin?: string;
214
  /** ADB host connection */
215
  adbHost?: string;
216
  /** ADB port */
217
  adbPort?: string;
218
  /** Target Android device ID */
219
  adbDevice?: string;
220
  /** ADB discovery timeout in milliseconds */
221
  adbDiscoveryTimeout?: number;
222
  /** Remove old artifacts from device */
223
  adbRemoveOldArtifacts?: boolean;
224
  /** Firefox APK package name */
225
  firefoxApk?: string;
226
  /** Firefox APK component name */
227
  firefoxApkComponent?: string;
228
}
229
```
230

231
### Chromium Runner
232

233
Specialized runner for Chromium-based browsers.
234

235
```javascript { .api }
236
interface ChromiumRunner extends ExtensionRunner {
237
  /** Chromium binary path */
238
  chromiumBinary?: string;
239
  /** Custom Chromium profile path */
240
  chromiumProfile?: string;
241
  /** Additional launch arguments */
242
  args: string[];
243
  /** URLs to open at startup */
244
  startUrl: string[];
245
}
246
```
247

248
### Reload Strategy
249

250
Hot reloading system for development workflow.
251

252
```javascript { .api }
253
interface ReloadStrategy {
254
  /** Reload extension when files change */
255
  reloadExtension(runners: ExtensionRunner[]): Promise<void>;
256
  /** Watch for file changes */
257
  watchForChanges(params: WatchParams): Promise<void>;
258
}
259

260
interface WatchParams {
261
  sourceDir: string;
262
  watchFile?: string[];
263
  watchIgnored?: string[];
264
  onFileChanged: () => void;
265
}
266

267
/** Default reload strategy instance */
268
const defaultReloadStrategy: ReloadStrategy;
269
```
270

271
**Usage Example:**
272

273
```javascript
274
import { defaultReloadStrategy } from "web-ext";
275

276
// Custom reload handling
277
await defaultReloadStrategy.watchForChanges({
278
  sourceDir: './extension',
279
  watchFile: ['manifest.json', 'content.js'],
280
  watchIgnored: ['**/*.log'],
281
  onFileChanged: async () => {
282
    console.log('Extension files changed, reloading...');
283
    await defaultReloadStrategy.reloadExtension(runners);
284
  }
285
});
286
```
287

288
## Android Development Parameters
289

290
Extended parameters for Firefox Android development:
291

292
```javascript { .api }
293
interface AndroidParams {
294
  /** Path to adb binary */
295
  adbBin?: string;
296
  /** ADB host to connect to */
297
  adbHost?: string;
298
  /** ADB port number */
299
  adbPort?: string;
300
  /** Android device identifier */
301
  adbDevice?: string;
302
  /** Timeout for device discovery in milliseconds */
303
  adbDiscoveryTimeout?: number;
304
  /** Remove old artifacts from device */
305
  adbRemoveOldArtifacts?: boolean;
306
  /** Firefox APK package (e.g., org.mozilla.fenix) */
307
  firefoxApk?: string;
308
  /** Firefox APK component (defaults to <firefoxApk>/.App) */
309
  firefoxApkComponent?: string;
310
}
311
```
312

313
## Error Handling
314

315
Extension runners handle various error scenarios:
316

317
- **Browser not found**: Validates browser binary paths and provides helpful error messages
318
- **Profile errors**: Handles profile creation, permission issues, and corruption
319
- **Connection failures**: Manages remote debugging connection problems
320
- **ADB issues**: Android device connection and communication errors
321
- **Extension load failures**: Reports extension installation and loading problems
322
- **Hot reload errors**: Handles file watching and reload mechanism failures