0
# Configuration Management
1

2
Shared configuration interfaces and default values for browser management, navigation options, and test execution control.
3

4
## Capabilities
5

6
### Common Configuration Interface
7

8
Base configuration options shared across all test types for consistent browser management and navigation.
9

10
```typescript { .api }
11
interface CommonConfig {
12
  /** URL to the Storybook instance (default: 'http://localhost:6006') */
13
  storybookUrl: string;
14
  /** Path to Chrome executable (overrides SB_CHROMIUM_PATH env var) */
15
  chromeExecutablePath?: string;
16
  /** Function to provide page navigation options */
17
  getGotoOptions: (options: Options) => DirectNavigationOptions | undefined;
18
  /** Function to customize page before navigation */
19
  customizePage: (page: Page) => Promise<void>;
20
  /** Function to provide custom browser instance */
21
  getCustomBrowser?: () => Promise<Browser>;
22
  /** Puppeteer browser launch options */
23
  browserLaunchOptions: LaunchOptions;
24
  /** Browser setup timeout in milliseconds (default: 15000) */
25
  setupTimeout: number;
26
  /** Individual test timeout in milliseconds (default: 15000) */
27
  testTimeout: number;
28
}
29

30
interface Options {
31
  context: Context;
32
  url: string;
33
}
34

35
interface Context {
36
  kind: string;
37
  story: string;
38
  parameters: { [key: string]: any };
39
}
40
```
41

42
### Navigation Configuration
43

44
Control page navigation behavior and timing for reliable test execution.
45

46
```typescript { .api }
47
interface DirectNavigationOptions {
48
  /** HTTP referer header value */
49
  referer?: string;
50
  /** Navigation timeout in milliseconds */
51
  timeout?: number;
52
  /** Conditions to wait for before considering navigation complete */
53
  waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
54
}
55

56
type PuppeteerLifeCycleEvent = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
57

58
/**
59
 * Function type for providing navigation options
60
 * @param options - Test context and URL information
61
 * @returns Navigation options for page.goto()
62
 */
63
type GetGotoOptions = (options: Options) => DirectNavigationOptions | undefined;
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
// Wait for network idle before proceeding
70
const getGotoOptions = ({ context, url }) => ({
71
  waitUntil: 'networkidle0',
72
  timeout: 30000
73
});
74

75
// Different wait strategies per story type  
76
const getGotoOptions = ({ context }) => {
77
  if (context.kind.includes('Loading')) {
78
    return { waitUntil: 'networkidle2' };
79
  }
80
  return { waitUntil: 'domcontentloaded' };
81
};
82

83
// Custom referer for authentication
84
const getGotoOptions = () => ({
85
  referer: 'https://authenticated-domain.com',
86
  waitUntil: 'load'
87
});
88
```
89

90
### Browser Launch Configuration
91

92
Configure Puppeteer browser instance with custom launch options and executable paths.
93

94
```typescript { .api }
95
/**
96
 * Puppeteer browser launch options interface
97
 */
98
interface LaunchOptions {
99
  /** Browser executable path */
100
  executablePath?: string;
101
  /** Ignore HTTPS certificate errors */
102
  ignoreHTTPSErrors?: boolean;
103
  /** Run browser in headless mode */
104
  headless?: boolean | 'new';
105
  /** Browser launch arguments */
106
  args?: string[];
107
  /** Ignore default arguments */
108
  ignoreDefaultArgs?: boolean | string[];
109
  /** Default viewport settings */
110
  defaultViewport?: Viewport | null;
111
  /** Slow down operations by specified milliseconds */
112
  slowMo?: number;
113
  /** Timeout for browser launch */
114
  timeout?: number;
115
}
116

117
interface Viewport {
118
  width: number;
119
  height: number;
120
  deviceScaleFactor?: number;
121
  isMobile?: boolean;
122
  hasTouch?: boolean;
123
  isLandscape?: boolean;
124
}
125
```
126

127
**Usage Examples:**
128

129
```typescript
130
// SSL testing configuration
131
const browserLaunchOptions = {
132
  ignoreHTTPSErrors: true,
133
  args: ['--ignore-certificate-errors']
134
};
135

136
// Mobile testing viewport
137
const browserLaunchOptions = {
138
  defaultViewport: {
139
    width: 375,
140
    height: 667,
141
    deviceScaleFactor: 2,
142
    isMobile: true,
143
    hasTouch: true
144
  }
145
};
146

147
// Debug mode configuration
148
const browserLaunchOptions = {
149
  headless: false,
150
  slowMo: 250,
151
  devtools: true
152
};
153
```
154

155
### Page Customization
156

157
Customize page settings before navigation to stories.
158

159
```typescript { .api }
160
/**
161
 * Function type for page customization
162
 * @param page - Puppeteer page instance to customize
163
 * @returns Promise for async customization operations
164
 */
165
type CustomizePage = (page: Page) => Promise<void>;
166
```
167

168
**Usage Examples:**
169

170
```typescript
171
// Device emulation
172
const customizePage = async (page) => {
173
  const iPhone = require('puppeteer/DeviceDescriptors')['iPhone 6'];
174
  await page.emulate(iPhone);
175
};
176

177
// Custom user agent and viewport
178
const customizePage = async (page) => {
179
  await page.setUserAgent('Custom Test Agent 1.0');
180
  await page.setViewport({ width: 1920, height: 1080 });
181
  
182
  // Disable images for faster loading
183
  await page.setRequestInterception(true);
184
  page.on('request', (req) => {
185
    if(req.resourceType() == 'image'){
186
      req.abort();
187
    } else {
188
      req.continue();
189
    }
190
  });
191
};
192

193
// Authentication setup
194
const customizePage = async (page) => {
195
  // Set authentication cookies
196
  await page.setCookie({
197
    name: 'auth-token',
198
    value: 'test-token-123',
199
    domain: 'localhost'
200
  });
201
  
202
  // Add custom headers
203
  await page.setExtraHTTPHeaders({
204
    'Authorization': 'Bearer test-token'
205
  });
206
};
207
```
208

209
### Custom Browser Provider
210

211
Provide your own browser instance for advanced scenarios like remote browsers or browser pools.
212

213
```typescript { .api }
214
/**
215
 * Function type for providing custom browser instance
216
 * @returns Promise resolving to Puppeteer Browser instance
217
 */
218
type GetCustomBrowser = () => Promise<Browser>;
219
```
220

221
**Usage Examples:**
222

223
```typescript
224
// Connect to remote browser
225
const getCustomBrowser = () => {
226
  return puppeteer.connect({ 
227
    browserWSEndpoint: 'ws://remote-browser:9222' 
228
  });
229
};
230

231
// Use existing browser instance
232
let sharedBrowser;
233
const getCustomBrowser = async () => {
234
  if (!sharedBrowser) {
235
    sharedBrowser = await puppeteer.launch({
236
      headless: false,
237
      args: ['--no-sandbox']
238
    });
239
  }
240
  return sharedBrowser;
241
};
242

243
// Docker container browser
244
const getCustomBrowser = () => {
245
  return puppeteer.connect({
246
    browserURL: 'http://chrome-container:9222'
247
  });
248
};
249
```
250

251
### Default Configuration Values
252

253
Pre-configured default values for all common configuration options.
254

255
```typescript { .api }
256
const defaultCommonConfig: CommonConfig = {
257
  storybookUrl: 'http://localhost:6006',
258
  chromeExecutablePath: process.env.SB_CHROMIUM_PATH,
259
  getGotoOptions: () => undefined,
260
  customizePage: () => Promise.resolve(),
261
  getCustomBrowser: undefined,
262
  browserLaunchOptions: {},
263
  setupTimeout: 15000,
264
  testTimeout: 15000,
265
};
266

267
// Note: When no custom browser is provided, the addon automatically includes
268
// security arguments for Linux systems: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage']
269
```
270

271
### Timeout Configuration
272

273
Control timing for different phases of test execution.
274

275
```typescript { .api }
276
interface TimeoutConfig {
277
  /** Browser initialization timeout (default: 15000ms) */
278
  setupTimeout: number;
279
  /** Individual test execution timeout (default: 15000ms) */
280
  testTimeout: number;
281
}
282
```
283

284
**Usage Examples:**
285

286
```typescript
287
// Extended timeouts for slow environments
288
const timeoutConfig = {
289
  setupTimeout: 30000,  // 30 seconds for browser launch
290
  testTimeout: 25000    // 25 seconds per test
291
};
292

293
// Quick timeouts for fast CI
294
const timeoutConfig = {
295
  setupTimeout: 10000,  // 10 seconds
296
  testTimeout: 8000     // 8 seconds per test
297
};
298
```
299

300
### Environment Variable Support
301

302
Automatic integration with environment variables for common configuration needs.
303

304
```typescript { .api }
305
interface EnvironmentVariables {
306
  /** Chrome executable path from environment */
307
  SB_CHROMIUM_PATH?: string;
308
}
309

310
// Usage in configuration
311
const chromeExecutablePath = process.env.SB_CHROMIUM_PATH || '/usr/bin/google-chrome';
312
```
313

314