diff --git a/docs/_partials/specs/assert-view-options.mdx b/docs/_partials/specs/assert-view-options.mdx new file mode 100644 index 0000000..f309570 --- /dev/null +++ b/docs/_partials/specs/assert-view-options.mdx @@ -0,0 +1,96 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
**Опция****Тип****Описание**
ignoreElementsArray или String + Элементы (задаются как селекторы), которые будут проигнорированы при сравнении + скриншотов. Игнор реализуется с помощью закраски перечисленных элементов черным + цветом. В случае одного элемента параметр можно задавать как строку. +
toleranceNumberЧувствительность к разнице в цветам.
antialiasingToleranceNumberЧувствительность в антиалиасинге.
allowViewportOverflowBoolean + По умолчанию Testplane выдает ошибку, если элемент находится за пределами границ + вьюпорта. Этот параметр отключает проверку на границы, позволяя снимать скриншоты + элементов, не влезающих во вьюпорт. При этом на скриншоте будут видны только те + части элемента, которые влезли во вьюпорт. Однако если _compositeImage_ равен + _true_, то части элемента, которые оказались за _нижней_ границей вьюпорта, тоже + будут видны на скриншоте. Аналогично если _captureElementFromTop_ равен _true_, то + на скриншот попадут и те части элемента, которые оказались за пределами _верхней_ + границы вьюпорта. +
captureElementFromTopBoolean + Снимать скриншот элемента с самого верха. Если элемент находится за пределами + вьюпорта, то к нему будет выполнен подскролл. +
compositeImageBoolean + Если элемент не влазит во вьюпорт, то при включении этой опции поочередно будет + сделано несколько скриншотов разных частей элемента, после чего скриншоты будут + склеены в один, чтобы отобразить элемент полностью. +
screenshotDelayNumber + Задержка в миллисекундах перед снятием скриншота. Может пригодиться, когда на + странице есть элементы, использующие анимацию, или скроллбар, который исчезает не + сразу и попадает на результирующий скриншот. +
selectorToScrollString + Селектор, который нужно скроллировать. Может пригодиться, когда надо сделать + скриншот модального окна, которое не помещается на экране. Иначе без указания + селектора скролл будет применяться к объекту _window_, и скроллироваться будет + задний фон, оставляя попап-окно на месте. +
disableAnimationBoolean + Отключение анимаций и переходов при снятии скриншота. По умолчанию `true` начиная с + версии `8.0.0` +
ignoreDiffPixelCount`` `${number}%` `` или Number + Процент пикселей, которые нужно игнорировать при диффе. Удобно для игнорирования + очень маленьких диффов. По умолчанию `0`. Доступен начиная с версии `8.2.0` +
diff --git a/docs/commands/element/assertView.mdx b/docs/commands/element/assertView.mdx index 383cede..de6fb5f 100644 --- a/docs/commands/element/assertView.mdx +++ b/docs/commands/element/assertView.mdx @@ -1,4 +1,5 @@ import Admonition from "@theme/Admonition"; +import AssertViewOptions from "@site/docs/_partials/specs/assert-view-options.mdx"; # assertView @@ -42,108 +43,7 @@ await browser.$(selector).assertView(state, options); Задает настройки команды `assertView`: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
**Опция****Тип****Описание**
ignoreElementsArray или String - Элементы (задаются как селекторы), которые будут проигнорированы при сравнении - скриншотов. Игнор реализуется с помощью закраски перечисленных элементов черным - цветом. В случае одного элемента параметр можно задавать как строку. -
toleranceNumber - Чувствительность к разнице в цветам. Значение перетирает - [browsers.tolerance][browsers-tolerance]. -
antialiasingToleranceNumber - Чувствительность в антиалиасинге. Значение перетирает - [browsers.antialiasingTolerance][browsers-antialiasing-tolerance]. -
allowViewportOverflowBoolean - По умолчанию Testplane выдает ошибку, если элемент находится за пределами границ - вьюпорта. Этот параметр отключает проверку на границы, позволяя снимать скриншоты - элементов, не влезающих во вьюпорт. При этом на скриншоте будут видны только те - части элемента, которые влезли во вьюпорт. Однако если _compositeImage_ равен - _true_, то части элемента, которые оказались за _нижней_ границей вьюпорта, тоже - будут видны на скриншоте. Аналогично если _captureElementFromTop_ равен _true_, то - на скриншот попадут и те части элемента, которые оказались за пределами _верхней_ - границы вьюпорта. -
captureElementFromTopBoolean - Снимать скриншот элемента с самого верха. Если элемент находится за пределами - вьюпорта, то к нему будет выполнен подскролл. -
compositeImageBoolean - Если элемент не влазит во вьюпорт, то при включении этой опции поочередно будет - сделано несколько скриншотов разных частей элемента, после чего скриншоты будут - склеены в один, чтобы отобразить элемент полностью. -
screenshotDelayNumber - Задержка в миллисекундах перед снятием скриншота. Может пригодиться, когда на - странице есть элементы, использующие анимацию, или скроллбар, который исчезает не - сразу и попадает на результирующий скриншот. -
selectorToScrollString - Селектор, который нужно скроллировать. Может пригодиться, когда надо сделать - скриншот модального окна, которое не помещается на экране. Иначе без указания - селектора скролл будет применяться к объекту _window_, и скроллироваться будет - задний фон, оставляя попап-окно на месте. -
disableAnimationBoolean - Отключение анимаций и переходов при снятии скриншота. По умолчанию `true` начиная с - версии `8.0.0` -
ignoreDiffPixelCount`` `${number}%` `` или Number - Процент пикселей, которые нужно игнорировать при диффе. Удобно для игнорирования - очень маленьких диффов. По умолчанию `0`. Доступен начиная с версии `8.2.0` -
+ ## Примеры использования {#examples} diff --git a/docs/config/_partials/examples/_browsers-basic-format.mdx b/docs/config/_partials/examples/_browsers-basic-format.mdx new file mode 100644 index 0000000..66481c8 --- /dev/null +++ b/docs/config/_partials/examples/_browsers-basic-format.mdx @@ -0,0 +1,15 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + browsers: { + "": { + desiredCapabilities: { + browserName: "", + // ... + }, + // ... + }, + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_browsers-desired-capabilities.mdx b/docs/config/_partials/examples/_browsers-desired-capabilities.mdx new file mode 100644 index 0000000..34ab60f --- /dev/null +++ b/docs/config/_partials/examples/_browsers-desired-capabilities.mdx @@ -0,0 +1,17 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + browsers: { + chrome: { + desiredCapabilities: { + browserName: "chrome", + browserVersion: "125.0", + "goog:chromeOptions": { + args: ["--hide-scrollbars", "--headless=new"], + }, + }, + }, + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_browsers-example.mdx b/docs/config/_partials/examples/_browsers-example.mdx new file mode 100644 index 0000000..063be4f --- /dev/null +++ b/docs/config/_partials/examples/_browsers-example.mdx @@ -0,0 +1,16 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + sessionsPerBrowser: 10, + browsers: { + chrome: { + /* ... */ + }, + firefox: { + // ... + sessionsPerBrowser: 5, + }, + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_browsers-session-env-flags.mdx b/docs/config/_partials/examples/_browsers-session-env-flags.mdx new file mode 100644 index 0000000..0d64a4f --- /dev/null +++ b/docs/config/_partials/examples/_browsers-session-env-flags.mdx @@ -0,0 +1,14 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + browsers: { + "chrome-phone": { + // ... + sessionEnvFlags: { + isMobile: true, + }, + }, + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_config-example.mdx b/docs/config/_partials/examples/_config-example.mdx new file mode 100644 index 0000000..cfec5da --- /dev/null +++ b/docs/config/_partials/examples/_config-example.mdx @@ -0,0 +1,32 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + retry: process.env.IS_CI ? 5 : 0, + + httpTimeout: 60_000, + sessionsPerBrowser: 5, + testsPerSession: 20, + + browsers: { + chrome: { + desiredCapabilities: { + browserName: "chrome", + automationProtocol: "devtools", + headless: true, + }, + }, + }, + sets: { + desktop: { + files: ["testplane-tests/**/*.testplane.(t|j)s"], + browsers: ["chrome"], + }, + }, + plugins: { + "html-reporter/testplane": { + enabled: true, + }, + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_dev-server-example.mdx b/docs/config/_partials/examples/_dev-server-example.mdx new file mode 100644 index 0000000..867c091 --- /dev/null +++ b/docs/config/_partials/examples/_dev-server-example.mdx @@ -0,0 +1,20 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +const SERVER_PORT = 3000; + +export default { + // ... + devServer: { + command: "npm run server:dev", + env: { PORT: SERVER_PORT }, + readinessProbe: { + url: `http://localhost:${SERVER_PORT}/health`, + timeouts: { + // optional + waitServerTimeout: 60_000, // default value + }, + }, + }, +}; +``` diff --git a/docs/config/_partials/examples/_last-failed-example.mdx b/docs/config/_partials/examples/_last-failed-example.mdx new file mode 100644 index 0000000..a3424a9 --- /dev/null +++ b/docs/config/_partials/examples/_last-failed-example.mdx @@ -0,0 +1,12 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + // ... + lastFailed: { + only: false, + input: [".testplane/failed.json"], + output: ".testplane/failed.json", + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_minimal-config.mdx b/docs/config/_partials/examples/_minimal-config.mdx new file mode 100644 index 0000000..20ea1af --- /dev/null +++ b/docs/config/_partials/examples/_minimal-config.mdx @@ -0,0 +1,13 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + browsers: { + chrome: { + desiredCapabilities: { + browserName: "chrome", + }, + }, + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_plugins-example.mdx b/docs/config/_partials/examples/_plugins-example.mdx new file mode 100644 index 0000000..76f0134 --- /dev/null +++ b/docs/config/_partials/examples/_plugins-example.mdx @@ -0,0 +1,26 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + // ... + plugins: { + "my-cool-plugin": { + param: "some-value", + }, + }, +} satisfies ConfigInput; +``` + +```typescript title="testplane-my-cool-plugin/index.ts" +exports = function (testplane, opts) { + testplane.on(testplane.events.RUNNER_START, function (runner) { + console.info(opts.param); // some-value + + return setUp(testplane.config, opts.param); + }); + + testplane.on(testplane.events.RUNNER_END, function () { + return tearDown(); + }); +}; +``` diff --git a/docs/config/_partials/examples/_plugins-register-workers.mdx b/docs/config/_partials/examples/_plugins-register-workers.mdx new file mode 100644 index 0000000..efde60d --- /dev/null +++ b/docs/config/_partials/examples/_plugins-register-workers.mdx @@ -0,0 +1,27 @@ +```typescript title="my-plugin.ts" +let workers; + +exports = testplane => { + testplane.on(testplane.events.RUNNER_START, async runner => { + const workerFilepath = require.resolve("./worker"); + const exportedMethods = ["foo"]; + workers = runner.registerWorkers(workerFilepath, exportedMethods); + + // outputs `FOO_RUNNER_START` + console.log(await workers.foo("RUNNER_START")); + }); + + testplane.on(testplane.events.RUNNER_END, async () => { + // outputs `FOO_RUNNER_END` + console.log(await workers.foo("RUNNER_END")); + }); +}; +``` + +```typescript title="worker.ts" +exports = { + foo: async function (event) { + return "FOO_" + event; + }, +}; +``` diff --git a/docs/config/_partials/examples/_prepare-browser-add-browser-command.mdx b/docs/config/_partials/examples/_prepare-browser-add-browser-command.mdx new file mode 100644 index 0000000..4fb72ce --- /dev/null +++ b/docs/config/_partials/examples/_prepare-browser-add-browser-command.mdx @@ -0,0 +1,25 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; +import querystring from "querystring"; + +function toStoryKind(value) { + /* here goes some code */ +} +function toStoryId(value) { + /* here goes some code */ +} + +export default { + // ... + prepareBrowser: function (browser) { + browser.addCommand("openScenario", function openScenario(rawComponent, rawStory, params) { + const component = toStoryKind(rawComponent); + const story = toStoryId(rawStory); + const queryParams = querystring.stringify(params); + const url = `/storybook/iframe.html?id=components-${component}-testplane--${story}&${queryParams}`; + + return this.url(url); + }); + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_prepare-browser-add-element-command.mdx b/docs/config/_partials/examples/_prepare-browser-add-element-command.mdx new file mode 100644 index 0000000..cec3544 --- /dev/null +++ b/docs/config/_partials/examples/_prepare-browser-add-element-command.mdx @@ -0,0 +1,24 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + // ... + prepareBrowser: function (browser) { + browser.addCommand( + "getCoords", + async function () { + const { x, y } = await this.getLocation(); + const { width, height } = await this.getSize(); + + return { + left: x, + top: y, + right: x + width, + bottom: y + height, + }; + }, + true, // true = element command, false = browser command + ); + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_prepare-browser-add-multiple-commands.mdx b/docs/config/_partials/examples/_prepare-browser-add-multiple-commands.mdx new file mode 100644 index 0000000..7e24b1a --- /dev/null +++ b/docs/config/_partials/examples/_prepare-browser-add-multiple-commands.mdx @@ -0,0 +1,27 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; +import path from "path"; +import glob from "fast-glob"; + +export default { + // ... + prepareBrowser: function (browser) { + const files = glob.sync(["tests/testplane/commands/*.(js|ts)", "!**/*.d.ts"]); + + files.forEach(file => { + const module = require(path.resolve(process.cwd(), file)); + const name = path.basename(file, path.extname(file)); + + browser.addCommand(name, typeof module === "object" ? module[name] : module); + }); + }, +}; +``` + +```typescript title="tests/testplane/commands/myCheckCookie.js" +export default async function (cookieName) { + const cookies = await this.getCookies(cookieName); + + assert.isTrue(cookies[0], `cookie named ${cookieName} is not set`); +} +``` diff --git a/docs/config/_partials/examples/_prepare-browser-overwrite-command.mdx b/docs/config/_partials/examples/_prepare-browser-overwrite-command.mdx new file mode 100644 index 0000000..8c310d0 --- /dev/null +++ b/docs/config/_partials/examples/_prepare-browser-overwrite-command.mdx @@ -0,0 +1,22 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + // ... + prepareBrowser: function (browser) { + browser.overwriteCommand("url", function (origUrlFunction, uri, query) { + if (!query) { + return origUrlFunction(uri); + } + + const parsedUrl = new URL(uri); + + for (const [key, value] of Object.entries(query)) { + parsedUrl.searchParams.set(key, value); + } + + return origUrlFunction(parsedUrl.href); + }); + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_prepare-environment.mdx b/docs/config/_partials/examples/_prepare-environment.mdx new file mode 100644 index 0000000..f19002c --- /dev/null +++ b/docs/config/_partials/examples/_prepare-environment.mdx @@ -0,0 +1,11 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; +import { pick } from "lodash"; + +export default { + // ... + prepareEnvironment: function () { + this.sets = pick(this.sets, ["touch-phone"]); + }, +}; +``` diff --git a/docs/config/_partials/examples/_sets-basic-format.mdx b/docs/config/_partials/examples/_sets-basic-format.mdx new file mode 100644 index 0000000..08959cd --- /dev/null +++ b/docs/config/_partials/examples/_sets-basic-format.mdx @@ -0,0 +1,16 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + browsers: { + /* ... */ + }, + sets: { + "": { + files: ["path-1", "some/folder/**/*.some-ext"], + ignoreFiles: ["ignorePath-1", "some/ignore/folder/**/"], + browsers: ["browser-1", "browser-2"], + }, + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_sets-example.mdx b/docs/config/_partials/examples/_sets-example.mdx new file mode 100644 index 0000000..9ac7c6c --- /dev/null +++ b/docs/config/_partials/examples/_sets-example.mdx @@ -0,0 +1,27 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + browsers: { + chrome: { + /*...*/ + }, + firefox: { + /*...*/ + }, + iphone: { + /*...*/ + }, + }, + sets: { + common: { + files: "tests/common/*.testplane.ts", + }, + desktop: { + files: ["tests/desktop/*.testplane.ts", "tests/common/*.testplane.ts"], + ignoreFiles: ["**/screens/**"], + browsers: ["chrome", "firefox"], + }, + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_system-example.mdx b/docs/config/_partials/examples/_system-example.mdx new file mode 100644 index 0000000..3fdfeb7 --- /dev/null +++ b/docs/config/_partials/examples/_system-example.mdx @@ -0,0 +1,21 @@ +```typescript title="testplane.config.ts" +import type { ConfigInput } from "testplane"; + +export default { + // ... + system: { + debug: false, + mochaOpts: { + timeout: 60000, + }, + ctx: { + /* ... */ + }, + patternsOnReject: [/timeout/i, /timedout/i, /timed out/i], + workers: 1, + testsPerWorker: Infinity, + parallelLimit: 15, + fileExtensions: [".js", ".ts"], + }, +} satisfies ConfigInput; +``` diff --git a/docs/config/_partials/examples/_system-test-run-env.mdx b/docs/config/_partials/examples/_system-test-run-env.mdx new file mode 100644 index 0000000..d24f30a --- /dev/null +++ b/docs/config/_partials/examples/_system-test-run-env.mdx @@ -0,0 +1,49 @@ +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + + + + ```typescript title="testplane.config.ts" + import type { ConfigInput } from "testplane"; + + export default { + // ... + system: { + testRunEnv: ['browser', { viteConfig: './vite.config.ts' }] + }, + } + ``` + + + + ```typescript title="testplane.config.ts" + import type { ConfigInput } from "testplane"; + import viteConfig from './vite.config.ts'; + + export default { + // ... + system: { + testRunEnv: ['browser', { viteConfig }] + }, + } + ``` + + + + ```typescript title="testplane.config.ts" + import type { ConfigInput } from "testplane"; + + export default { + // ... + system: { + testRunEnv: ['browser', { + viteConfig: (configEnv) => ({ + // ... + }), + }], + }, + } + ``` + + + diff --git a/docs/config/browsers.mdx b/docs/config/browsers.mdx index d537f3d..27d792b 100644 --- a/docs/config/browsers.mdx +++ b/docs/config/browsers.mdx @@ -1,4 +1,9 @@ import Admonition from "@theme/Admonition"; +import BrowsersBasicFormat from "@site/docs/config/_partials/examples/_browsers-basic-format.mdx"; +import BrowsersExample from "@site/docs/config/_partials/examples/_browsers-example.mdx"; +import DesiredCapabilitiesExample from "@site/docs/config/_partials/examples/_browsers-desired-capabilities.mdx"; +import SessionEnvFlags from "@site/docs/config/_partials/examples/_browsers-session-env-flags.mdx"; +import AssertViewOptions from "@site/docs/_partials/specs/assert-view-options.mdx"; # browsers @@ -10,102 +15,140 @@ import Admonition from "@theme/Admonition"; Данный раздел имеет следующий формат: -```javascript -module.exports = { - browsers: { - : { -