0
# Puppeteer Test Execution
1

2
Enables arbitrary Puppeteer tests defined in story parameters, providing full browser automation capabilities for interactive testing scenarios.
3

4
## Capabilities
5

6
### Puppeteer Test Function
7

8
Creates a test function that executes custom Puppeteer code against Storybook stories with full browser automation support.
9

10
```typescript { .api }
11
/**
12
 * Creates a test function for running arbitrary Puppeteer tests against Storybook stories
13
 * @param customConfig - Optional configuration to override defaults
14
 * @returns Test function with lifecycle hooks for StoryShots integration
15
 */
16
function puppeteerTest(customConfig?: Partial<PuppeteerTestConfig>): TestFunction;
17

18
interface PuppeteerTestConfig extends CommonConfig {
19
  /** Test implementation function with optional filtering capability */
20
  testBody: ((page: Page, options: Options) => void | Promise<void>) & {
21
    filter?: (options: Options) => boolean;
22
  };
23
}
24

25
interface TestFunction {
26
  /** Main test execution function */
27
  (context: { kind: string; framework: string; name: string; id: string }): Promise<void>;
28
  /** Setup function for browser initialization */
29
  beforeAll: (() => Promise<void>) & { timeout: number };
30
  /** Cleanup function for browser shutdown */
31
  afterAll: () => Promise<void>;
32
  /** Test execution timeout in milliseconds */
33
  timeout: number;
34
}
35

36
interface Options {
37
  context: Context;
38
  url: string;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import initStoryshots from '@storybook/addon-storyshots';
46
import { puppeteerTest } from '@storybook/addon-storyshots-puppeteer';
47

48
// Basic custom test execution
49
initStoryshots({ 
50
  suite: 'Puppeteer storyshots', 
51
  test: puppeteerTest() 
52
});
53

54
// With custom Storybook URL
55
initStoryshots({
56
  suite: 'Custom URL tests',
57
  test: puppeteerTest({ 
58
    storybookUrl: 'http://my-storybook.com:9010' 
59
  })
60
});
61

62
// With custom browser launch options
63
initStoryshots({
64
  suite: 'SSL tests',
65
  test: puppeteerTest({
66
    storybookUrl: 'https://localhost:6006',
67
    browserLaunchOptions: {
68
      ignoreHTTPSErrors: true
69
    }
70
  })
71
});
72
```
73

74
### Story Parameter Integration
75

76
Test functions are defined in story parameters using the `puppeteerTest` key.
77

78
```typescript { .api }
79
// Story parameter structure for test definitions
80
interface StoryParameters {
81
  puppeteerTest?: (page: Page, options: Options) => void | Promise<void>;
82
}
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
// In your story file
89
export const InteractiveButton = () => <Button>Click me</Button>;
90

91
InteractiveButton.parameters = {
92
  async puppeteerTest(page) {
93
    const button = await page.$('button');
94
    await button.click();
95
    
96
    // Custom assertions
97
    const result = await page.$eval('.result', el => el.textContent);
98
    expect(result).toBe('Button clicked');
99
  },
100
};
101

102
// Complex interaction test
103
export const FormSubmission = () => <ContactForm />;
104

105
FormSubmission.parameters = {
106
  async puppeteerTest(page) {
107
    // Fill form fields
108
    await page.type('#name', 'John Doe');
109
    await page.type('#email', 'john@example.com');
110
    await page.select('#country', 'US');
111
    
112
    // Submit form
113
    await page.click('#submit');
114
    await page.waitForSelector('.success-message');
115
    
116
    // Verify submission
117
    const message = await page.$eval('.success-message', el => el.textContent);
118
    expect(message).toContain('Thank you');
119
  },
120
};
121
```
122

123
### Default Test Body Implementation
124

125
The default test body reads test functions from story parameters and provides automatic filtering.
126

127
```typescript { .api }
128
/**
129
 * Default test implementation that reads from story parameters
130
 * @param page - Puppeteer page instance
131
 * @param options - Test context and URL information
132
 * @returns Promise resolving when test completes
133
 */
134
function defaultTestBody(page: Page, options: Options): Promise<void> | null;
135

136
// Default filter function checks for puppeteerTest parameter existence
137
defaultTestBody.filter: (options: Options) => boolean;
138
```
139

140
### Browser Lifecycle Management
141

142
The test function manages browser lifecycle automatically with configurable timeouts and cleanup handling.
143

144
```typescript { .api }
145
interface BrowserLifecycle {
146
  /** Browser setup with configurable timeout */
147
  beforeAll: (() => Promise<void>) & { timeout: number };
148
  /** Browser cleanup with graceful shutdown */
149
  afterAll: () => Promise<void>;
150
  /** Process signal handling for cleanup */
151
  processExitHandler: () => Promise<void>;
152
}
153
```
154

155
**Key Features:**
156

157
- Automatic Chrome/Chromium browser launch with security arguments
158
- Custom browser instance support via `getCustomBrowser`
159
- Graceful cleanup on process termination (SIGINT handling)  
160
- Configurable setup and test timeouts
161
- Error handling for missing browser instances
162
- React Native framework detection and skip logic