From 36f16449afac4a56b7eb4483eedca92cf7d45e53 Mon Sep 17 00:00:00 2001 From: Roman Kuznetsov Date: Thu, 5 Dec 2024 14:25:44 +0300 Subject: [PATCH] docs: migrate docs --- README.md | 160 +----------------------------------------------------- 1 file changed, 3 insertions(+), 157 deletions(-) diff --git a/README.md b/README.md index aeb81db..6f01a88 100644 --- a/README.md +++ b/README.md @@ -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> | {} | 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 | [] | 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 = { - 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> = { - 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//` 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/)