Skip to content

Commit 568a627

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

File tree

10 files changed

+997
-0
lines changed

10 files changed

+997
-0
lines changed

‎blog/storybook-testing.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Скриншотное тестирование со 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‎

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

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
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+
59+
[looks-same]: [https://github.com/gemini-testing/looks-same]
60+
[browser-command]: https://testplane.io/docs/v8/commands/browser/assertView/
61+
[element-command]: https://testplane.io/docs/v8/commands/element/assertView/

0 commit comments

Comments
 (0)