@serenity-js/playwright-test 3.36.2 → 3.37.1

package/src/api/serenity-fixtures.ts

@@ -1,4 +1,6 @@
 import type {
+    Ability,
+    Actor,
     Cast,
     ClassDescription,
     Duration,
@@ -6,8 +8,9 @@ import type {
     StageCrewMember,
     StageCrewMemberBuilder
 } from '@serenity-js/core';
-import type { Actor } from '@serenity-js/core';
 import type { ExtraBrowserContextOptions } from '@serenity-js/playwright';
+import type { AxiosRequestConfigDefaults } from '@serenity-js/rest';
+import { type AxiosInstance } from 'axios';
 
 /**
  * Serenity/JS-specific [Playwright Test fixtures](https://playwright.dev/docs/test-fixtures)
@@ -241,31 +244,92 @@ export interface SerenityFixtures {
      */
     extraContextOptions: Partial<ExtraBrowserContextOptions>;
 
+    /**
+     * Extra abilities given to the actors on top of the default ones provided by the [`actors`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/#actors) fixture.
+     *
+     * #### Extra abilities for all actors
+     *
+     * To give the same set of extra abilities to all the actors, make your `extraAbilities` fixture
+     * return an array of [`Ability`](https://serenity-js.org/api/core/class/Ability/) objects.
+     *
+     * ```typescript
+     * import { type Ability } from '@serenity-js/core';
+     * import { describe, it, test } from '@serenity-js/playwright-test';
+     * import { MyAbility } from './MyAbility';
+     *
+     * describe(`My feature`, () => {
+     *
+     *     test.use({
+     *         extraAbilities: [ new MyAbility() ]
+     *     });
+     *
+     *     it(`...`, async({ actor }) => {
+     *       // ...
+     *     });
+     * });
+     * ```
+     *
+     * #### Extra abilities for selected actors
+     *
+     * To give extra abilities only to selected actors, make your `extraAbilities` fixture return a `(actorName: string) => Ability[]` function that maps
+     * the actor name to an array of [`Ability`](https://serenity-js.org/api/core/class/Ability/) objects.
+     *
+     * ```typescript
+     * import { describe, it, test } from '@serenity-js/playwright-test';
+     * import { MyAbility } from './MyAbility';
+     *
+     * describe(`My feature`, () => {
+     *
+     *     test.use({
+     *         extraAbilities: async ({ }, use) => {
+     *             await use((actorName: string) => {
+     *                 // Alice gets the extra abilities, but others don't
+     *                 return actorName === 'Alice'
+     *                     ? [ new MyAbility() ]
+     *                     : [];
+     *             })
+     *         }
+     *     });
+     *
+     *     it(`...`, async({ actor }) => {
+     *       // ...
+     *     });
+     * });
+     * ```
+     */
+    extraAbilities: ((actorName: string) => Ability[]) | Ability[];
+
     /**
      * A cast of Serenity/JS actors to be used instead of the default cast
      * when instantiating [`actor`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/#actor)
      * and invoking [`actorCalled`](https://serenity-js.org/api/playwright-test/interface/SerenityWorkerFixtures/#actorCalled).
      *
      * :::info Did you know?
-     * When you use `@serenity-js/playwright-test` [test APIs](https://serenity-js.org/api/playwright-test/function/it/), Serenity/JS already provides a default cast of actors for you.
-     * Each one of the default actors receives [abilities](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWebWithPlaywright`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/) and [`TakeNotes.usingAnEmptyNotepad`](https://serenity-js.org/api/core/class/TakeNotes/#usingAnEmptyNotepad).
-     *
-     * The default abilities should be sufficient in most web testing scenarios. However, you might want to override this default configuration
-     * when you need your actors to [interact with REST APIs](https://serenity-js.org/api/rest/class/CallAnApi/),
-     * [manage local servers](https://serenity-js.org/api/local-server/class/ManageALocalServer/),
-     * start with a notepad that has some [initial state](https://serenity-js.org/api/core/class/TakeNotes/#using),
-     * or receive [custom abilities](https://serenity-js.org/api/core/class/Ability/).
-     * :::
+     * Serenity/JS [test APIs](https://serenity-js.org/api/playwright-test/function/it/) offer fixtures that set up the default cast of actors for you,
+     * which should be sufficient in most web and HTTP API testing scenarios.
+     *
+     * Each one of the default actors receives the following [abilities](https://serenity-js.org/api/core/class/Ability/):
+     * - [`BrowseTheWebWithPlaywright`](https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright/), connected to Playwright [`page`](https://playwright.dev/docs/test-fixtures) fixture
+     * - [`TakeNotes`](https://serenity-js.org/api/core/class/TakeNotes/#usingAnEmptyNotepad)
+     * - [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/), pointing at the [`baseURL`](https://playwright.dev/docs/test-use-options#basic-options)
+     *   and using any `proxy` settings in your Playwright config file.
      *
+     * The easiest way to give your actors additional abilities is to use the [`extraAbilities`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/#extraAbilities) fixture.
+     * :::
      *
      * #### Overriding the default cast of Serenity/JS actors
      *
      * ```typescript
-     * import { Cast, TakeNotes } from '@serenity-js/core'
      * import { Ensure, equals } from '@serenity-js/assertions'
+     * import { Cast, TakeNotes } from '@serenity-js/core'
      * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
+     * import { CallAnApi } from '@serenity-js/rest'
      * import { describe, it, test } from '@serenity-js/playwright-test'
      *
+     * interface MyNotes {
+     *   username: string;
+     * }
+     *
      * describe(`Recording items`, () => {
      *
      *     test.use({
@@ -273,17 +337,24 @@ export interface SerenityFixtures {
      *             defaultNavigationTimeout: 30_000,
      *         },
      *
-     *         defaultActorName: 'Serena',
-     *         actors: async ({ browser, contextOptions, extraContextOptions }, use) => {
-     *             const cast = Cast.where(actor =>
-     *                 actor.whoCan(
-     *                     BrowseTheWebWithPlaywright.using(browser, contextOptions, extraContextOptions),
-     *                     TakeNotes.usingAnEmptyNotepad(),
+     *         actors: async ({ axios, extraAbilities, extraContextOptions, extraHTTPHeaders, page }, use) => {
+     *             const cast = Cast.where(actor => {
+     *                 const abilities = Array.isArray(extraAbilities)
+     *                     ? extraAbilities
+     *                     : extraAbilities(actor.name);
+     *
+     *                 return actor.whoCan(
+     *                     BrowseTheWebWithPlaywright.usingPage(page, extraContextOptions),
+     *                     TakeNotes.using<MyNotes>(Notepad.with({
+     *                       username: 'example.username'
+     *                     }),
+     *                     CallAnApi.using(axios),
+     *                     ...abilities,
      *                 )
-     *             )
+     *             })
      *
      *             // Make sure to pass your custom cast to Playwright `use` callback
-     *             await use(cast)
+     *             await use(cast);
      *         },
      *     })
      *
@@ -302,7 +373,7 @@ export interface SerenityFixtures {
      *         })
      *     })
      * })
-     *
+     * ```
      *
      * #### Learn more
      * - Declaring a Serenity/JS [test scenario](https://serenity-js.org/api/playwright-test/function/it/)
@@ -322,6 +393,18 @@ export interface SerenityFixtures {
      * - Declaring a Serenity/JS [test scenario](https://serenity-js.org/api/playwright-test/function/it/)
      */
     actor: Actor;
+
+    /**
+     * An instance of the Axios HTTP client, or default Axios request configurations,
+     * to be used by the [`CallAnApi`](https://serenity-js.org/api/rest/class/CallAnApi/) ability,
+     * provided to the actors via the [`actors`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/#actors) fixture.
+     *
+     * By default, Serenity/JS configures Axios to use the following settings from your Playwright configuration file:
+     * - [`baseURL`](https://playwright.dev/docs/api/class-testoptions#test-options-base-url)
+     * - [`proxy`](https://playwright.dev/docs/api/class-testoptions#test-options-proxy)
+     * - [`extraHTTPHeaders`](https://playwright.dev/docs/api/class-testoptions#test-options-extra-http-headers)
+     */
+    axios: AxiosInstance | AxiosRequestConfigDefaults;
 }
 
 /**
@@ -370,7 +453,9 @@ export interface SerenityWorkerFixtures {
     serenity: Serenity;
 
     /**
-     * Uses the provided [cast](https://serenity-js.org/api/core/class/Cast/) of [`actors`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/#actors) to instantiate an [`Actor`](https://serenity-js.org/api/core/class/Actor/) called `name`
+     * Uses the provided [cast](https://serenity-js.org/api/core/class/Cast/) of
+     * [`actors`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/#actors) to instantiate
+     * an [`Actor`](https://serenity-js.org/api/core/class/Actor/) called `name`
      * and inject it into a [test scenario](https://serenity-js.org/api/playwright-test/function/it/).
      *
      * Retrieves an existing actor if one has already been instantiated.

package/src/api/test-api.ts

@@ -13,7 +13,7 @@ import type {
     TestType,
     WorkerInfo,
 } from '@playwright/test';
-import { test as playwrightBaseTest } from '@playwright/test';
+import { mergeTests, test as playwrightBaseTest } from '@playwright/test';
 import type { DiffFormatter } from '@serenity-js/core';
 import { AnsiDiffFormatter, Cast, Clock, Duration, Serenity, TakeNotes } from '@serenity-js/core';
 import { SceneFinishes, SceneTagged } from '@serenity-js/core/lib/events';
@@ -68,20 +68,32 @@ export const fixtures: Fixtures<SerenityFixtures & SerenityInternalFixtures, Ser
         { option: true },
     ],
 
+    axios: async ({ baseURL, extraHTTPHeaders, proxy }, use) => {
+        await use({
+            baseURL: baseURL,
+            headers: extraHTTPHeaders,
+            proxy: proxy && proxy?.server
+                ? asProxyConfig(proxy)
+                : undefined,
+        })
+    },
+
     actors: [
         // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-        async ({ extraContextOptions, baseURL, extraHTTPHeaders, page, proxy }, use): Promise<void> => {
-            await use(Cast.where(actor => actor.whoCan(
-                BrowseTheWebWithPlaywright.usingPage(page, extraContextOptions),
-                TakeNotes.usingAnEmptyNotepad(),
-                CallAnApi.using({
-                    baseURL: baseURL,
-                    headers: extraHTTPHeaders,
-                    proxy: proxy && proxy?.server
-                        ? asProxyConfig(proxy)
-                        : undefined,
-                }),
-            )));
+        async ({ axios, extraAbilities, extraContextOptions, page }, use): Promise<void> => {
+            await use(Cast.where(actor => {
+
+                const abilities = Array.isArray(extraAbilities)
+                    ? extraAbilities
+                    : extraAbilities(actor.name);
+
+                return actor.whoCan(
+                    BrowseTheWebWithPlaywright.usingPage(page, extraContextOptions),
+                    TakeNotes.usingAnEmptyNotepad(),
+                    CallAnApi.using(axios),
+                    ...abilities,
+                );
+            }));
         },
         { option: true },
     ],
@@ -109,7 +121,7 @@ export const fixtures: Fixtures<SerenityFixtures & SerenityInternalFixtures, Ser
 
     sceneIdFactoryInternal: [
         // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types,no-empty-pattern
-        async ({ }, use) => {
+        async ({}, use) => {
             await use(new PlaywrightTestSceneIdFactory());
         },
         { scope: 'worker', box: true },
@@ -132,7 +144,7 @@ export const fixtures: Fixtures<SerenityFixtures & SerenityInternalFixtures, Ser
 
     eventStreamWriterInternal: [
         // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types,no-empty-pattern
-        async ({ }, use, workerInfo) => {
+        async ({}, use, workerInfo) => {
 
             const serenityOutputDirectory = path.join(workerInfo.project.outputDir, 'serenity');
 
@@ -225,12 +237,18 @@ export const fixtures: Fixtures<SerenityFixtures & SerenityInternalFixtures, Ser
         { auto: true, box: true, }
     ],
 
+    extraAbilities: [
+        [],
+        { option: true },
+    ],
+
     actorCalled: [
         // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
         async ({ serenity }, use) => {
 
             const actorCalled = (name: string) => {
                 const actor = serenity.theActorCalled(name);
+
                 return actor.whoCan(new PerformActivitiesAsPlaywrightSteps(actor, serenity, it));
             };
 
@@ -247,7 +265,7 @@ export const fixtures: Fixtures<SerenityFixtures & SerenityInternalFixtures, Ser
 /**
  * Serenity/JS BDD-style test API created by [`useBase`](https://serenity-js.org/api/playwright-test/function/useBase/).
  */
-export type TestApi<TestArgs extends Record<string, any>, WorkerArgs extends Record<string, any>> =
+export type TestApi<TestArgs extends object, WorkerArgs extends object> =
     Pick<TestType<TestArgs, WorkerArgs>, 'describe' | 'beforeAll' | 'beforeEach' | 'afterEach' | 'afterAll' | 'expect'> &
     {
         /**
@@ -274,7 +292,7 @@ export type TestApi<TestArgs extends Record<string, any>, WorkerArgs extends Rec
          *
          * Shorthand for [`useBase`](https://serenity-js.org/api/playwright-test/function/useBase/)
          */
-        useFixtures: <T extends Record<string, any>, W extends Record<string, any> = object>(
+        useFixtures: <T extends object, W extends object = object>(
             customFixtures: Fixtures<T, W, TestArgs, WorkerArgs>
         ) => TestApi<TestArgs & T, WorkerArgs & W>,
 
@@ -282,7 +300,7 @@ export type TestApi<TestArgs extends Record<string, any>, WorkerArgs extends Rec
         test: TestType<TestArgs, WorkerArgs>,
     }
 
-function createTestApi<BaseTestFixtures extends (PlaywrightTestArgs & PlaywrightTestOptions), BaseWorkerFixtures extends (PlaywrightWorkerArgs & PlaywrightWorkerOptions)>(baseTest: TestType<BaseTestFixtures, BaseWorkerFixtures>): TestApi<BaseTestFixtures, BaseWorkerFixtures> {
+function createTestApi<BaseTestFixtures extends object, BaseWorkerFixtures extends object>(baseTest: TestType<BaseTestFixtures, BaseWorkerFixtures>): TestApi<BaseTestFixtures, BaseWorkerFixtures> {
     return {
         useFixtures<T extends Record<string, any>, W extends Record<string, any> = object>(customFixtures: Fixtures<T, W, BaseTestFixtures, BaseWorkerFixtures>): TestApi<BaseTestFixtures & T, BaseWorkerFixtures & W> {
             return createTestApi(baseTest.extend(customFixtures));
@@ -426,6 +444,9 @@ export const expect: Expect = api.expect;
 
 export const useFixtures = api.useFixtures;
 
+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).
  *
@@ -562,15 +583,45 @@ export const useFixtures = api.useFixtures;
  * })
  * ```
  *
- * @param baseTest
+ * ## 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 function useBase<
-    BaseTestFixtures extends (PlaywrightTestArgs & PlaywrightTestOptions),
-    BaseWorkerFixtures extends (PlaywrightWorkerArgs & PlaywrightWorkerOptions)
-> (baseTest: TestType<BaseTestFixtures, BaseWorkerFixtures>): TestApi<BaseTestFixtures & SerenityFixtures, BaseWorkerFixtures & SerenityWorkerFixtures> {
-    return createTestApi<BaseTestFixtures, BaseWorkerFixtures>(baseTest).useFixtures(
-        fixtures as Fixtures<SerenityFixtures, SerenityWorkerFixtures, BaseTestFixtures, BaseWorkerFixtures>
-    );
+export function useBase<List extends any[]>(...baseTests: List): TestApi<MergedT<List> & SerenityFixtures, MergedW<List> & SerenityWorkerFixtures> {
+    return createTestApi<MergedT<List>, MergedW<List>>(mergeTests(...baseTests))
+        .useFixtures(fixtures as Fixtures<SerenityFixtures, SerenityWorkerFixtures, MergedT<List>, MergedW<List>>);
 }
 
 /**
@@ -602,13 +653,14 @@ function asProxyConfig(proxy: PlaywrightTestOptions['proxy']): {
     auth?: { username: string, password: string }
     bypass?: string;
 } {
+    const proxyServer = proxy.server.trim();
 
     // Playwright defaults to http when proxy.server does not define the protocol
     // See https://playwright.dev/docs/api/class-testoptions#test-options-proxy
-    const hasProtocol = /[\dA-Za-z]+:\/\//.test(proxy.server);
+    const hasProtocol = /^[\dA-Za-z]+:\/\//.test(proxyServer);
     const proxyUrl = hasProtocol
-        ? new URL(proxy.server)
-        : new URL(`http://${ proxy.server }`);
+        ? new URL(proxyServer)
+        : new URL(`http://${ proxyServer }`);
 
     const host = proxyUrl.hostname;
     const port = proxyUrl.port