Skip to content

Commit

Permalink
Merge pull request #31 from gemini-testing/TRIVIAL.docs.migrate
Browse files Browse the repository at this point in the history 
docs: migrate docs
  • Loading branch information
@KuznetsovRoman
KuznetsovRoman authored Dec 11, 2024
2 parents e992ef4 + 36f1644 commit 986b2bb
Showing 1 changed file with 3 additions and 157 deletions.
160 changes: 3 additions & 157 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,160 +4,6 @@ A Testplane plugin that makes it easy to write [Testplane](https://github.com/ge
- Adds automatic screenshot tests for storybook stories;
- Adds an ability to write Testplane tests for storybook stories right inside of the stories.

## Installation

```bash
npm install @testplane/storybook --save-dev
```

## Usage

> ⚠️ Storybook 6.4+ is required to use this plugin.
### Storybook

If you use storybook@6, you will need to enable [buildStoriesJson](https://storybook.js.org/docs/6.4/configure/overview#feature-flags) feature in your `storybook` config:

```ts
// .storybook/main.js
export default {
// ...
features: {
// ...
buildStoriesJson: true
}
}
```

You don't need to do this with storybook@7 or storybook@8.

### Testplane

Add `@testplane/storybook` plugin into your Testplane config:

```ts
// .testplane.conf.ts
export default {
plugins: {
'@testplane/storybook': {},

// other Testplane plugins...
},

// other Testplane settings...
}
```

With this minimal config, you will be able to run `npx testplane --storybook` to autotest each storybook story with [Testplane assertView](https://github.com/gemini-testing/testplane#assertview) 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.

Full plugin config:

| **Parameter** | **Type** | **Default value** | **Description** |
| ---------------------------------- | --------------------------------------- | ---------------------- | --------------------------------------------------------------------------- |
| enabled | Boolean | true | Enable / disable the plugin |
| storybookConfigDir | String | ".storybook" | Path to the storybook configuration directory |
| autoScreenshots | Boolean | true | Enable / disable auto-screenshot tests |
| autoScreenshotStorybookGlobals | Record<string, Record<string, unknown>> | {} | Run multiple auto-screenshot tests with different [storybook globals](https://storybook.js.org/docs/7/essentials/toolbars-and-globals#globals). Only works with storybook >= 8 |
| localport | Number | 6006 | Port to launch storybook dev server on |
| remoteStorybookUrl | String | "" | URL of the remote Storybook. If specified, local storybook dev sever would not be launched |
| browserIds | Array<String \| RegExp> | [] | Array of `browserId` to run storybook tests on. By default, all of browsers, specified in Testplane config would be used |

> ⚠️ *Storybook tests performance greatly depends on [Testplane testsPerSession](https://github.com/gemini-testing/testplane#testspersession) parameter, as these tests speeds up on reusing existing sessions, so setting values around 20+ is preferred*
> ⚠️ *These tests ignore [Testplane isolation](https://github.com/gemini-testing/testplane#isolation). It would be turned off unconditionally*
#### autoScreenshotStorybookGlobals

For example, with `autoScreenshotStorybookGlobals` set to:

```json
{
"default": {},
"light theme": {
"theme": "light"
},
"dark theme": {
"theme": "dark"
}
}
```

3 autoscreenshot tests will be generated for each story, each test having its corresponding storybook globals value:
- `... Autoscreenshot default`
- `... Autoscreenshot light theme`
- `... Autoscreenshot dark theme`

## Advanced usage

If you have `ts-node` in your project, you can write your Testplane tests right inside of storybook story files:

```ts
import type { StoryObj } from "@storybook/react";
import type { WithTestplane } from "@testplane/storybook"

export const Primary: WithTestplane<StoryObj> = {
args: {
primary: true,
label: "Button",
},
testplane: {
"my test": async ({browser, expect}) => {
const element = await browser.$(".storybook-button");

await expect(element).toHaveText("Button");
}
}
};
```

You can also specify extra options in story default config:

```ts
import type { WithTestplane } from "@testplane/storybook"
import type { Meta, StoryObj } from "@storybook/react";

const meta: WithTestplane<Meta<typeof Button>> = {
title: "Example/Button",
component: Button,
testplane: {
skip: false, // if true, skips all Testplane tests from this story file
autoscreenshotSelector: ".my-selector", // Custom selector to auto-screenshot elements
browserIds: ["chrome"], // Testplane browsers to run tests from this story file
autoScreenshotStorybookGlobals: { // overlay plugin config's autoScreenshotStorybookGlobals options
"es locale": { locale: "es" },
"fr locale": { locale: "fr" }
},
assertViewOpts: { // override default assertView options for tests from this file
ignoreDiffPixelCount: 5
}
}
};

export default meta;
```

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:

```bash
npx testplane --storybook -c .testplane.storybook.conf.ts
```

This allows you to store references next to your story files:

```ts
// .testplane.conf.ts
import path from "path";
import { getStoryFile } from "@testplane/storybook";

export default {
screenshotsDir: (test) => {
const relativeStoryFilePath = getStoryFile(test);
const relativeStoryFileDirPath = path.dirname(relativeStoryFilePath);

return path.join(relativeStoryFileDirPath, "screens", test.id, test.browserId);
},
// other Testplane settings...
}
```

In this example, screenshot references would be stored in `screens/<testId>/<browserId>` folder, next to each of your story files.
See full documentation in various languages:
* [English](https://testplane.io/docs/v8/plugins/testplane-storybook/)
* [Русский](https://testplane.io/ru/docs/v8/plugins/testplane-storybook/)

0 comments on commit 986b2bb

Please sign in to comment.