Skip to content

Commit 1427430

Browse files
sipayRTsipayRT
committed
docs(storybook): add documentation about storybook
1 parent b41127a commit 1427430

File tree

11 files changed

+1009
-0
lines changed

11 files changed

+1009
-0
lines changed

‎blog/storybook-testing.mdx

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Screenshot testing with Storybook
3+
slug: screenshot-testing-with-storybook
4+
hide_table_of_contents: false
5+
date: 2024-09-26T13:00
6+
---
7+
8+
Now, for automatic visual testing of your components, you only need Storybook with your components and the `@testplane/storybook` plugin. There’s no need to write any tests anymore.
9+
10+
<!-- truncate -->
11+
12+
[Storybook][storybook] is a tool for developing user interfaces based on components. It allows developers to independently visualize components in various states in an isolated environment, separate from other components.
13+
This "showroom" is perfect for screenshot testing your components, as this isolated environment makes such tests significantly more stable and faster compared to e2e testing.
14+
15+
With the [@testplane/storybook][testplane-storybook] plugin, you can automatically verify changes to your components using screenshot testing without writing a single line of test code.
16+
You just need to describe your component in `Storybook` and Testplane will automatically generate all necessary tests upon execution, run them in the required browsers and provide a visual report for updating screenshots.
17+
Additionally, if a [play function][play-function] has been declared for the components, Testplane will execute it before the test begins to set the component to the desired state.
18+
19+
However, if these capabilities are not enough, you can directly describe a Testplane test in the story file, which will be executed as an additional test for the component.
20+
21+
How to use it?
22+
23+
Learn more about this in our documentation [Screenshot testing with Storybook][vt-story].
24+
Also you can try it yourself in our [example project][example] on GitHub with customized screenshot testing.
25+
26+
[storybook]: https://storybook.js.org
27+
[testplane-storybook]: https://github.com/gemini-testing/testplane-storybook
28+
[play-function]: https://storybook.js.org/docs/writing-stories/play-function
29+
[vt-story]: ../../docs/v8/visual-testing/with-storybook
30+
[example]: https://github.com/gemini-testing/testplane/examples/storybook-autoscreenshots

‎docs/plugins/testplane-storybook.mdx

+202
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
import Admonition from "@theme/Admonition";
2+
3+
# @testplane/storybook
4+
5+
## Overview {#overview}
6+
7+
Use the [@testplane/storybook][testplane-storybook] plugin to automatically check the changes in your Storybook components with screenshot testing without a single line of test code.
8+
9+
This plugin adds:
10+
11+
- automatic screenshot tests for storybook stories;
12+
- an ability to write Testplane tests for storybook stories right inside of the stories.
13+
14+
## Installation {#install}
15+
16+
```bash
17+
npm install @testplane/storybook --save-dev
18+
```
19+
20+
## Setup {#setup}
21+
22+
<Admonition type="info">Storybook 6.4+ is required to use this plugin.</Admonition>
23+
24+
### Storybook
25+
26+
If you use `storybook@6`, you will need to enable [buildStoriesJson][build-stories] feature in your `storybook` config:
27+
28+
```typescript tytle=".storybook/main.js"
29+
export default {
30+
// ...
31+
features: {
32+
// ...
33+
buildStoriesJson: true,
34+
},
35+
};
36+
```
37+
38+
You don't need to do this with storybook@7 or storybook@8.
39+
40+
### Testplane
41+
42+
Add `@testplane/storybook` plugin into your Testplane config:
43+
44+
```typescript title=".testplane.conf.ts"
45+
export default {
46+
plugins: {
47+
"@testplane/storybook": {},
48+
49+
// other Testplane plugins...
50+
},
51+
52+
// other Testplane settings...
53+
};
54+
```
55+
56+
With this minimal config, you will be able to run `npx testplane --storybook` to autotest each storybook story with [Testplane assertView][assert-view] command. Testplane will open each story, wait for play function to finish (if defined), and then call `assertView` command. These tests would be generated in runtime.
57+
58+
### Description of configuration parameters {#setup_description}
59+
60+
<table>
61+
<thead>
62+
<tr>
63+
<td>**Parameter**</td>
64+
<td>**Type**</td>
65+
<td>**Default**</td>
66+
<td>**Description**</td>
67+
</tr>
68+
</thead>
69+
<tbody>
70+
<tr>
71+
<td>enabled</td>
72+
<td>`Boolean`</td>
73+
<td>true</td>
74+
<td>Enable / disable plugin.</td>
75+
</tr>
76+
<tr>
77+
<td>storybookConfigDir</td>
78+
<td>`String`</td>
79+
<td>".storybook"</td>
80+
<td>Path to the storybook configuration directory.</td>
81+
</tr>
82+
<tr>
83+
<td>autoScreenshots</td>
84+
<td>`Boolean`</td>
85+
<td>true</td>
86+
<td>Enable / disable auto-screenshot tests</td>
87+
</tr>
88+
<tr>
89+
<td>localport</td>
90+
<td>`Number`</td>
91+
<td>6006</td>
92+
<td>Port to launch storybook dev server on.</td>
93+
</tr>
94+
<tr>
95+
<td>remoteStorybookUrl</td>
96+
<td>`String`</td>
97+
<td>""</td>
98+
<td>URL of the remote Storybook. If specified, local storybook dev sever would not be launched.</td>
99+
</tr>
100+
<tr>
101+
<td>browserIds</td>
102+
<td>`Array<String | RegExp>`</td>
103+
<td>[]</td>
104+
<td>Array of `browserId` to run storybook tests on. By default, all of browsers, specified in Testplane config would be used</td>
105+
</tr>
106+
</tbody>
107+
</table>
108+
109+
<Admonition type="info">
110+
Storybook tests performance greatly depends on [Testplane testsPerSession][testsPerSession]
111+
parameter, as these tests speeds up on reusing existing sessions, so setting values around 20+
112+
is preferred. These tests ignore [Testplane isolation][isolation]. It would be turned off
113+
unconditionally.
114+
</Admonition>
115+
116+
## Advanced usage
117+
118+
If you have `ts-node` in your project, you can write your Testplane tests right inside of storybook story files:
119+
120+
<Admonition type="info">
121+
Storybook story files must have `.js` or `.ts` extension for this to work. Formats `jsx/tsx` are
122+
not supported yet.
123+
</Admonition>
124+
125+
```typescript title="stories/Primary.stories.ts"
126+
import type { StoryObj } from "@storybook/react";
127+
import type { WithTestplane } from "@testplane/storybook";
128+
129+
export const Primary: WithTestplane<StoryObj> = {
130+
args: {
131+
primary: true,
132+
label: "Button",
133+
},
134+
testplane: {
135+
"my test": async ({ browser, expect }) => {
136+
const element = await browser.$(".storybook-button");
137+
138+
await expect(element).toHaveText("Button");
139+
},
140+
},
141+
};
142+
```
143+
144+
You can also specify extra options in story default config:
145+
146+
```typescript
147+
import type { WithTestplane } from "@testplane/storybook";
148+
import type { Meta, StoryObj } from "@storybook/react";
149+
150+
const meta: WithTestplane<Meta<typeof Button>> = {
151+
title: "Example/Button",
152+
component: Button,
153+
testplane: {
154+
skip: false, // if true, skips all Testplane tests from this story file
155+
autoscreenshotSelector: ".my-selector", // Custom selector to auto-screenshot elements
156+
browserIds: ["chrome"], // Testplane browsers to run tests from this story file
157+
assertViewOpts: {
158+
// override default assertView options for tests from this file
159+
ignoreDiffPixelCount: 5,
160+
},
161+
},
162+
};
163+
164+
export default meta;
165+
```
166+
167+
If you decide to create separate config for storybook auto-tests (which is suggested), you need to specify config path via CLI option. For example:
168+
169+
```bash
170+
npx testplane --storybook -c .testplane.storybook.conf.ts
171+
```
172+
173+
This allows you to store references next to your story files:
174+
175+
```typescript title=".testplane.conf.ts"
176+
import path from "path";
177+
import { getStoryFile } from "@testplane/storybook";
178+
179+
export default {
180+
screenshotsDir: test => {
181+
const relativeStoryFilePath = getStoryFile(test);
182+
const relativeStoryFileDirPath = path.dirname(relativeStoryFilePath);
183+
184+
return path.join(relativeStoryFileDirPath, "screens", test.id, test.browserId);
185+
},
186+
// other Testplane settings...
187+
};
188+
```
189+
190+
In this example, screenshot references would be stored in `screens/<testId>/<browserId>` folder, next to each of your story files.
191+
192+
## Useful links {#useful_links}
193+
194+
- [@testplane/storybook plugin sources][testplane-storybook]
195+
- [assertView command][assert-view]
196+
197+
[assert-view]: ../commands/browser/assertView.mdx
198+
[build-stories]: https://storybook.js.org/docs/6.4/configure/overview#feature-flags
199+
[isolation]: ../config/browsers.mdx#isolation
200+
[testplane-storybook]: https://github.com/gemini-testing/testplane-storybook
201+
[testplane]: https://github.com/gemini-testing/testplane
202+
[testsPerSession]: ../config/browsers.mdx#tests_per_session

‎docs/visual-testing/visual-testing-intro.mdx

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Visual testing
2+
3+
Visual testing is implemented in testplane, with which the user can check the visual changes of an individual component, a viewport or the entire page.
4+
We recommend using the [html-reporter][html-reporter] plugin, which provides a user-friendly UI for analyzing tests, saving/updating modified images and running tests.
5+
6+
[//]: # "![Html-report](_images/html-reporter.overview.png)"
7+
8+
### Screenshot Comparison Features {#features}
9+
10+
For screenshot checks, Testplane provides the `assertView` command, which allows you to take a screenshot of a specific element or the entire viewport.
11+
When the assertView command is invoked, it searches for the required element on the page with automatic waiting. By default, animations will be disabled on the page before taking a screenshot to eliminate potential instability in the test due to the changing state of the element.
12+
After taking a screenshot, the resulting image will be compared with the reference image. If the reference image does not exist yet, then it must be saved using the html reporter UI or the `--update-refs` CLI option.
13+
To compare images, we use our own library [looks-same][looks-same], which differs from competitors in high performance and accuracy of comparison.
14+
15+
The following settings are taken into account during comparison:
16+
17+
- the blinking cursor in text inputs is ignored by default;
18+
- elements specified in the comparison options are ignored in the image;
19+
- comparison accuracy settings (acceptable deviations) are considered;
20+
- anti-aliasing (the most common diffs in screenshots) accuracy settings for fonts are considered.
21+
22+
### Usage {#usage}
23+
24+
```typescript
25+
await browser.assertView(state, options);
26+
await browser.assertView(state, selector, options);
27+
await element.assertView(state, options);
28+
```
29+
30+
The `assertView` command is available both in the browser context and in the context of the found element. The set of arguments is different in these cases:
31+
32+
```typescript
33+
it("check search view", async ({ browser }) => {
34+
// ...
35+
36+
// screenshot of the current browser viewport
37+
await browser.assertView("viewport-screen");
38+
39+
// screenshot of a specific element on the page (call from the browser context)
40+
await browser.assertView("any-state-name", ".DocSearch", opts);
41+
42+
const searchInput = await browser.$(".DocSearch");
43+
await searchInput.click();
44+
45+
// taking screenshot of a previously found item (from the element context)
46+
await searchInput.assertView("any-state-name");
47+
});
48+
```
49+
50+
Read more about the capabilities of the `assertView' command in the relevant sections.
51+
52+
### Useful links {#useful_links}
53+
54+
- [browser.assertView command][browser-command]
55+
- [element.assertView command][element-command]
56+
57+
[html-reporter]: ../../html-reporter/html-reporter-setup
58+
[looks-same]: https://github.com/gemini-testing/looks-same
59+
[browser-command]: https://testplane.io/docs/v8/commands/browser/assertView/
60+
[element-command]: https://testplane.io/docs/v8/commands/element/assertView/

0 commit comments

Comments
 (0)