@serenity-js/playwright-test 3.41.1 → 3.42.0

package/esm/api/test-api.d.ts

@@ -0,0 +1,387 @@
+import type { Expect, Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestInfo, TestType } from '@playwright/test';
+import type { DiffFormatter } from '@serenity-js/core';
+import { PlaywrightTestSceneIdFactory } from '../reporter/PlaywrightTestSceneIdFactory.js';
+import type { SerenityFixtures, SerenityWorkerFixtures } from './serenity-fixtures.js';
+import { WorkerEventStreamWriter } from './WorkerEventStreamWriter.js';
+interface SerenityInternalFixtures {
+    configureScenarioInternal: void;
+}
+interface SerenityInternalWorkerFixtures {
+    configureWorkerInternal: void;
+    sceneIdFactoryInternal: PlaywrightTestSceneIdFactory;
+    diffFormatterInternal: DiffFormatter;
+    eventStreamWriterInternal: WorkerEventStreamWriter;
+}
+export declare const fixtures: Fixtures<SerenityFixtures & SerenityInternalFixtures, SerenityWorkerFixtures & SerenityInternalWorkerFixtures, PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+/**
+ * Serenity/JS BDD-style test API created by [`useBase`](https://serenity-js.org/api/playwright-test/function/useBase/).
+ */
+export type TestApi<TestArgs extends object, WorkerArgs extends object> = Pick<TestType<TestArgs, WorkerArgs>, 'describe' | 'beforeAll' | 'beforeEach' | 'afterEach' | 'afterAll' | 'expect'> & {
+    /**
+     * Creates a Serenity/JS BDD-style test API around the default Playwright [base test](https://playwright.dev/docs/test-fixtures)
+     * and using custom test fixtures.
+     *
+     * ```typescript
+     * import { useFixtures } from '@serenity-js/playwright-test'
+     * import { Log } from '@serenity-js/core'
+     *
+     * const { describe, it } = useFixtures<{ message: string }>({
+     *   message: 'Hello world!'
+     * })
+     *
+     * describe('Serenity/JS useFixtures', () => {
+     *
+     *   it('enables injecting custom test fixtures into test scenarios', async ({ actor, message }) => {
+     *     await actor.attemptsTo(
+     *       Log.the(message),
+     *     )
+     *   })
+     * })
+     * ```
+     *
+     * Shorthand for [`useBase`](https://serenity-js.org/api/playwright-test/function/useBase/)
+     */
+    useFixtures: <T extends object, W extends object = object>(customFixtures: Fixtures<T, W, TestArgs, WorkerArgs>) => TestApi<TestArgs & T, WorkerArgs & W>;
+    it: TestType<TestArgs, WorkerArgs>;
+    test: TestType<TestArgs, WorkerArgs>;
+};
+/**
+ * Declares a single test scenario.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { describe, it } from '@serenity-js/playwright-test'
+ *
+ * describe(`Todo List App`, () => {
+ *
+ *   it(`should allow me to add a todo item`, async ({ actor }) => {
+ *     await actor.attemptsTo(
+ *       startWithAnEmptyList(),
+ *
+ *       recordItem('Buy some milk'),
+ *
+ *       Ensure.that(itemNames(), equals([
+ *         'Buy some milk',
+ *       ])),
+ *     )
+ *   })
+ *
+ *   it('supports multiple actors using separate browsers', async ({ actorCalled }) => {
+ *     await actorCalled('Alice').attemptsTo(
+ *       startWithAListContaining(
+ *         'Feed the cat'
+ *       ),
+ *     )
+ *
+ *     await actorCalled('Bob').attemptsTo(
+ *       startWithAListContaining(
+ *         'Walk the dog'
+ *       ),
+ *     )
+ *
+ *     await actorCalled('Alice').attemptsTo(
+ *       Ensure.that(itemNames(), equals([
+ *         'Feed the cat'
+ *       ])),
+ *     )
+ *
+ *     await actorCalled('Bob').attemptsTo(
+ *       Ensure.that(itemNames(), equals([
+ *         'Walk the dog'
+ *       ])),
+ *     )
+ *   })
+ * })
+ * ```
+ *
+ * ## Learn more
+ * - [Grouping test scenarios](https://serenity-js.org/api/playwright-test/function/describe/)
+ * - [`SerenityFixtures`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/)
+ * - [Playwright Test `test` function](https://playwright.dev/docs/api/class-test#test-call)
+ * - [Serenity/JS + Playwright Test project template](https://github.com/serenity-js/serenity-js-playwright-test-template/)
+ */
+export declare const it: TestType<PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures>;
+/**
+ * Declares a single test scenario. Alias for [`it`](https://serenity-js.org/api/playwright-test/function/it/).
+ */
+export declare const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures>;
+/**
+ * Declares a group of test scenarios.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { describe, it, test } from '@serenity-js/playwright-test'
+ * import { Photographer, TakePhotosOfFailures, Value } from '@serenity-js/web'
+ *
+ * describe(`Todo List App`, () => {
+ *
+ *   test.use({
+ *     defaultActorName: 'Serena',
+ *     crew: [
+ *       Photographer.whoWill(TakePhotosOfFailures),
+ *     ],
+ *   })
+ *
+ *   it(`should allow me to add a todo item`, async ({ actor }) => {
+ *     await actor.attemptsTo(
+ *       startWithAnEmptyList(),
+ *
+ *       recordItem('Buy some milk'),
+ *
+ *       Ensure.that(itemNames(), equals([
+ *         'Buy some milk',
+ *       ])),
+ *     )
+ *   })
+ *
+ *   it('should clear text input field when an item is added', async ({ actor }) => {
+ *     await actor.attemptsTo(
+ *       startWithAnEmptyList(),
+ *
+ *       recordItem('Buy some milk'),
+ *
+ *       Ensure.that(Value.of(newTodoInput()), equals('')),
+ *     )
+ *   })
+ * })
+ * ```
+ *
+ * ## Learn more
+ * - Declaring a Serenity/JS [test scenario](https://serenity-js.org/api/playwright-test/function/it/)
+ * - [Playwright Test `describe` function](https://playwright.dev/docs/api/class-test#test-describe-1)
+ * - [Serenity/JS + Playwright Test project template](https://github.com/serenity-js/serenity-js-playwright-test-template/)
+ */
+export declare const describe: {
+    (title: string, callback: () => void): void;
+    (callback: () => void): void;
+    (title: string, details: import("@playwright/test").TestDetails, callback: () => void): void;
+    only(title: string, callback: () => void): void;
+    only(callback: () => void): void;
+    only(title: string, details: import("@playwright/test").TestDetails, callback: () => void): void;
+    skip(title: string, callback: () => void): void;
+    skip(callback: () => void): void;
+    skip(title: string, details: import("@playwright/test").TestDetails, callback: () => void): void;
+    fixme(title: string, callback: () => void): void;
+    fixme(callback: () => void): void;
+    fixme(title: string, details: import("@playwright/test").TestDetails, callback: () => void): void;
+    serial: {
+        (title: string, callback: () => void): void;
+        (callback: () => void): void;
+        (title: string, details: import("@playwright/test").TestDetails, callback: () => void): void;
+        only(title: string, callback: () => void): void;
+        only(callback: () => void): void;
+        only(title: string, details: import("@playwright/test").TestDetails, callback: () => void): void;
+    };
+    parallel: {
+        (title: string, callback: () => void): void;
+        (callback: () => void): void;
+        (title: string, details: import("@playwright/test").TestDetails, callback: () => void): void;
+        only(title: string, callback: () => void): void;
+        only(callback: () => void): void;
+        only(title: string, details: import("@playwright/test").TestDetails, callback: () => void): void;
+    };
+    configure: (options: {
+        mode?: "default" | "parallel" | "serial";
+        retries?: number;
+        timeout?: number;
+    }) => void;
+};
+export declare const beforeAll: {
+    (inner: (args: PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures, testInfo: TestInfo) => Promise<any> | any): void;
+    (title: string, inner: (args: PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures, testInfo: TestInfo) => Promise<any> | any): void;
+};
+export declare const beforeEach: {
+    (inner: (args: PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures, testInfo: TestInfo) => Promise<any> | any): void;
+    (title: string, inner: (args: PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures, testInfo: TestInfo) => Promise<any> | any): void;
+};
+export declare const afterEach: {
+    (inner: (args: PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures, testInfo: TestInfo) => Promise<any> | any): void;
+    (title: string, inner: (args: PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures, testInfo: TestInfo) => Promise<any> | any): void;
+};
+export declare const afterAll: {
+    (inner: (args: PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures, testInfo: TestInfo) => Promise<any> | any): void;
+    (title: string, inner: (args: PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures, testInfo: TestInfo) => Promise<any> | any): void;
+};
+export declare const expect: Expect;
+export declare const useFixtures: <T extends object, W extends object = object>(customFixtures: Fixtures<T, W, PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures>) => TestApi<PlaywrightTestArgs & PlaywrightTestOptions & SerenityFixtures & T, PlaywrightWorkerArgs & PlaywrightWorkerOptions & SerenityWorkerFixtures & W>;
+type MergedT<List> = List extends [TestType<infer T, any>, ...(infer Rest)] ? T & MergedT<Rest> : object;
+type MergedW<List> = List extends [TestType<any, infer W>, ...(infer Rest)] ? W & MergedW<Rest> : object;
+/**
+ * Creates a Serenity/JS BDD-style test API around the given Playwright [base test](https://playwright.dev/docs/test-fixtures).
+ *
+ * ## Using default configuration
+ *
+ * When your test scenario doesn't require [custom test fixtures](https://playwright.dev/docs/test-fixtures),
+ * and you're happy with the default [base test](https://playwright.dev/docs/api/class-test#test-call) offered by Playwright,
+ * you can import test API functions such as [`describe`](https://serenity-js.org/api/playwright-test/function/describe/) and [`it`](https://serenity-js.org/api/playwright-test/function/describe/) directly from `@serenity-js/playwright-test`.
+ *
+ * ```typescript
+ * import { describe, it, test } from '@serenity-js/playwright-test'
+ * import { Log } from '@serenity-js/core'
+ *
+ * // override default fixtures if needed
+ * test.use({
+ *   defaultActorName: 'Alice'
+ * })
+ *
+ * describe('Serenity/JS default test API', () => {
+ *
+ *   it('enables easy access to actors and standard Playwright fixtures', async ({ actor, browserName }) => {
+ *     await actor.attemptsTo(
+ *       Log.the(browserName),
+ *     )
+ *   })
+ * })
+ * ```
+ *
+ * In the above example, importing test API functions directly from `@serenity-js/playwright-test` is the equivalent of the following setup:
+ *
+ * ```typescript
+ * import { test as playwrightBaseTest } from '@playwright/test'
+ * import { useBase } from '@serenity-js/playwright-test'
+ *
+ * const { describe, it, test, beforeEach, afterEach } = useBase(playwrightBaseTest)
+ * ```
+ *
+ * ## Using custom fixtures
+ *
+ * When your test scenario requires [custom test fixtures](https://playwright.dev/docs/test-fixtures),
+ * but you're still happy with the default [base test](https://playwright.dev/docs/api/class-test#test-call) offered by Playwright,
+ * you can create fixture-aware test API functions such as [`describe`](https://serenity-js.org/api/playwright-test/function/describe/) and [`it`](https://serenity-js.org/api/playwright-test/function/describe/)
+ * by calling [`useFixtures`](https://serenity-js.org/api/playwright-test/function/useFixtures/).
+ *
+ * For example, you can create a test scenario using a static `message` fixture as follows:
+ *
+ * ```typescript
+ * import { useFixtures } from '@serenity-js/playwright-test'
+ * import { Log } from '@serenity-js/core'
+ *
+ * const { describe, it } = useFixtures<{ message: string }>({
+ *   message: 'Hello world!'
+ * })
+ *
+ * describe('Serenity/JS useFixtures', () => {
+ *
+ *   it('enables injecting custom test fixtures into test scenarios', async ({ actor, message }) => {
+ *     await actor.attemptsTo(
+ *       Log.the(message),
+ *     )
+ *   })
+ * })
+ * ```
+ *
+ * The value of your test fixtures can be either static or dynamic and based on the value of other fixtures.
+ *
+ * To create a dynamic test fixture use the [function syntax](https://playwright.dev/docs/test-fixtures):
+ *
+ * ```typescript
+ * import { Log } from '@serenity-js/core'
+ * import { useFixtures } from '@serenity-js/playwright-test'
+ *
+ * const { describe, it } = useFixtures<{ message: string }>({
+ *   message: async ({ actor }, use) => {
+ *     await use(`Hello, ${ actor.name }`);
+ *   }
+ * })
+ *
+ * describe('Serenity/JS useFixtures', () => {
+ *
+ *   it('enables injecting custom test fixtures into test scenarios', async ({ actor, message }) => {
+ *     await actor.attemptsTo(
+ *       Log.the(message),
+ *     )
+ *   })
+ * })
+ * ```
+ *
+ * In the above example, creating test API functions via `useFixtures` is the equivalent of the following setup:
+ *
+ * ```typescript
+ * import { test as playwrightBaseTest } from '@playwright/test'
+ * import { useBase } from '@serenity-js/playwright-test'
+ *
+ * const { describe, it, test, beforeEach, afterEach } = useBase(playwrightBaseTest)
+ *   .useFixtures<{ message: string }>({
+ *     message: async ({ actor }, use) => {
+ *       await use(`Hello, ${ actor.name }`);
+ *     }
+ *   })
+ * ```
+ *
+ * ## Using custom base test
+ *
+ * In cases where you need to use a non-default base test, for example when doing [UI component testing](https://playwright.dev/docs/test-components),
+ * you can create Serenity/JS test API functions around your preferred base test.
+ *
+ * ```tsx
+ * import { test as componentTest } from '@playwright/experimental-ct-react'
+ * import { Ensure, contain } from '@serenity-js/assertions'
+ * import { useBase } from '@serenity-js/playwright-test'
+ * import { Enter, PageElement, CssClasses } from '@serenity-js/web'
+ *
+ * import EmailInput from './EmailInput';
+ *
+ * const { it, describe } = useBase(componentTest).useFixtures<{ emailAddress: string }>({
+ *   emailAddress: ({ actor }, use) => {
+ *     use(`${ actor.name }@example.org`)
+ *   }
+ * })
+ *
+ * describe('EmailInput', () => {
+ *
+ *   it('allows valid email addresses', async ({ actor, mount, emailAddress }) => {
+ *     const nativeComponent = await mount(<EmailInput/>);
+ *
+ *     const component = PageElement.from(nativeComponent);
+ *
+ *     await actor.attemptsTo(
+ *       Enter.theValue(emailAddress).into(component),
+ *       Ensure.that(CssClasses.of(component), contain('valid')),
+ *     )
+ *   })
+ * })
+ * ```
+ *
+ * ## Merging multiple base tests
+ *
+ * To merge fixtures from multiple files or modules, pass them to `useBase`.
+ *
+ * ```tsx
+ * import { test as componentTest } from '@playwright/experimental-ct-react'
+ * import { test as a11yTest } from 'my-a11y-test-utils';
+ * import { Ensure, contain } from '@serenity-js/assertions'
+ * import { useBase } from '@serenity-js/playwright-test'
+ * import { Enter, PageElement, CssClasses } from '@serenity-js/web'
+ *
+ * import EmailInput from './EmailInput';
+ *
+ * const { it, describe } = useBase(componentTest, a11yTest).useFixtures<{ emailAddress: string }>({
+ *   emailAddress: ({ actor }, use) => {
+ *     use(`${ actor.name }@example.org`)
+ *   }
+ * })
+ *
+ * describe('EmailInput', () => {
+ *
+ *   it('allows valid email addresses', async ({ actor, mount, emailAddress }) => {
+ *     const nativeComponent = await mount(<EmailInput/>);
+ *
+ *     const component = PageElement.from(nativeComponent);
+ *
+ *     await actor.attemptsTo(
+ *       Enter.theValue(emailAddress).into(component),
+ *       Ensure.that(CssClasses.of(component), contain('valid')),
+ *     )
+ *   })
+ * })
+ * ```
+ *
+ * @param baseTests
+ */
+export declare function useBase<List extends any[]>(...baseTests: List): TestApi<MergedT<List> & SerenityFixtures, MergedW<List> & SerenityWorkerFixtures>;
+export {};
+//# sourceMappingURL=test-api.d.ts.map

package/esm/api/test-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-api.d.ts","sourceRoot":"","sources":["../../src/api/test-api.ts"],"names":[],"mappings":"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"}