Skip to main content

externaldescribe

Callable

  • describe(title: string, callback: () => void): void
  • describe(callback: () => void): void
  • describe(title: string, details: TestDetails, callback: () => void): void

  • Declares a group of test scenarios.

    Example

    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

    Parameters

    • externaltitle: string
    • externalcallback: () => void

      Returns void

    Index

    Properties

    Methods

    Properties

    externalserial

    serial: { only: any }

    NOTE See test.describe.configure([options]) for the preferred way of configuring the execution mode.

    Declares a group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together.

    NOTE Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently.

    • test.describe.serial(title, callback)
    • test.describe.serial(title)
    • test.describe.serial(title, details, callback)

    Usage

    test.describe.serial('group', () => {
      test('runs first', async ({ page }) => {});
      test('runs second', async ({ page }) => {});
    });

    You can also omit the title.

    test.describe.serial(() => {
      // ...
    });

    Type declaration

      • (title: string, callback: () => void): void
      • (callback: () => void): void
      • (title: string, details: TestDetails, callback: () => void): void
    • only: function
      • only(title: string, callback: () => void): void
      • only(callback: () => void): void
      • only(title: string, details: TestDetails, callback: () => void): void

      • NOTE See test.describe.configure([options]) for the preferred way of configuring the execution mode.

        Declares a focused group of tests that should always be run serially. If one of the tests fails, all subsequent tests are skipped. All tests in a group are retried together. If there are some focused tests or suites, all of them will be run but nothing else.

        NOTE Using serial is not recommended. It is usually better to make your tests isolated, so they can be run independently.

        • test.describe.serial.only(title, callback)
        • test.describe.serial.only(title)
        • test.describe.serial.only(title, details, callback)

        Usage

        test.describe.serial.only('group', () => {
          test('runs first', async ({ page }) => {
          });
          test('runs second', async ({ page }) => {
          });
        });

        You can also omit the title.

        test.describe.serial.only(() => {
          // ...
        });

        Parameters

        Returns void

    externalparallel

    parallel: { only: any }

    NOTE See test.describe.configure([options]) for the preferred way of configuring the execution mode.

    Declares a group of tests that could be run in parallel. By default, tests in a single test file run one after another, but using test.describe.parallel([title, details, callback]) allows them to run in parallel.

    • test.describe.parallel(title, callback)
    • test.describe.parallel(callback)
    • test.describe.parallel(title, details, callback)

    Usage

    test.describe.parallel('group', () => {
      test('runs in parallel 1', async ({ page }) => {});
      test('runs in parallel 2', async ({ page }) => {});
    });

    Note that parallel tests are executed in separate processes and cannot share any state or global variables. Each of the parallel tests executes all relevant hooks.

    You can also omit the title.

    test.describe.parallel(() => {
      // ...
    });

    Type declaration

      • (title: string, callback: () => void): void
      • (callback: () => void): void
      • (title: string, details: TestDetails, callback: () => void): void
    • only: function
      • only(title: string, callback: () => void): void
      • only(callback: () => void): void
      • only(title: string, details: TestDetails, callback: () => void): void

      • NOTE See test.describe.configure([options]) for the preferred way of configuring the execution mode.

        Declares a focused group of tests that could be run in parallel. This is similar to test.describe.parallel([title, details, callback]), but focuses the group. If there are some focused tests or suites, all of them will be run but nothing else.

        • test.describe.parallel.only(title, callback)
        • test.describe.parallel.only(callback)
        • test.describe.parallel.only(title, details, callback)

        Usage

        test.describe.parallel.only('group', () => {
          test('runs in parallel 1', async ({ page }) => {});
          test('runs in parallel 2', async ({ page }) => {});
        });

        You can also omit the title.

        test.describe.parallel.only(() => {
          // ...
        });

        Parameters

        Returns void

    externalconfigure

    configure: (options: { mode?: default | parallel | serial; retries?: number; timeout?: number }) => void

    Configures the enclosing scope. Can be executed either on the top level or inside a describe. Configuration applies to the entire scope, regardless of whether it run before or after the test declaration.

    Learn more about the execution modes here.

    Usage

    • Running tests in parallel. 
      // Run all the tests in the file concurrently using parallel workers.
      test.describe.configure({ mode: 'parallel' });
      test('runs in parallel 1', async ({ page }) => {});
      test('runs in parallel 2', async ({ page }) => {});
    • Running tests serially, retrying from the start. NOTE Running serially is not recommended. It is usually better to make your tests isolated, so they can be run independently. 
      // Annotate tests as inter-dependent.
      test.describe.configure({ mode: 'serial' });
      test('runs first', async ({ page }) => {});
      test('runs second', async ({ page }) => {});
    • Configuring retries and timeout for each test. 
      // Each test in the file will be retried twice and have a timeout of 20 seconds.
      test.describe.configure({ retries: 2, timeout: 20_000 });
      test('runs first', async ({ page }) => {});
      test('runs second', async ({ page }) => {});
    • Run multiple describes in parallel, but tests inside each describe in order. 
      test.describe.configure({ mode: 'parallel' });

      test.describe('A, runs in parallel with B', () => {
        test.describe.configure({ mode: 'default' });
        test('in order A1', async ({ page }) => {});
        test('in order A2', async ({ page }) => {});
      });

      test.describe('B, runs in parallel with A', () => {
        test.describe.configure({ mode: 'default' });
        test('in order B1', async ({ page }) => {});
        test('in order B2', async ({ page }) => {});
      });

    Type declaration

      • (options: { mode?: default | parallel | serial; retries?: number; timeout?: number }): void

      • Parameters

        • externaloptions: { mode?: default | parallel | serial; retries?: number; timeout?: number }
          • externaloptionalmode: default | parallel | serial
          • externaloptionalretries: number
          • externaloptionaltimeout: number

        Returns void

    Methods

    externalonly

    • only(title: string, callback: () => void): void
    • only(callback: () => void): void
    • only(title: string, details: TestDetails, callback: () => void): void

    • Declares a focused group of tests. If there are some focused tests or suites, all of them will be run but nothing else.

      • test.describe.only(title, callback)
      • test.describe.only(callback)
      • test.describe.only(title, details, callback)

      Usage

      test.describe.only('focused group', () => {
        test('in the focused group', async ({ page }) => {
          // This test will run
        });
      });
      test('not in the focused group', async ({ page }) => {
        // This test will not run
      });

      You can also omit the title.

      test.describe.only(() => {
        // ...
      });

      Parameters

      Returns void

    externalskip

    • skip(title: string, callback: () => void): void
    • skip(callback: () => void): void
    • skip(title: string, details: TestDetails, callback: () => void): void

    • Declares a skipped test group, similarly to test.describe([title, details, callback]). Tests in the skipped group are never run.

      • test.describe.skip(title, callback)
      • test.describe.skip(title)
      • test.describe.skip(title, details, callback)

      Usage

      test.describe.skip('skipped group', () => {
        test('example', async ({ page }) => {
          // This test will not run
        });
      });

      You can also omit the title.

      test.describe.skip(() => {
        // ...
      });

      Parameters

      • externaltitle: string

        Group title.

      • externalcallback: () => void

        A callback that is run immediately when calling test.describe.skip(title[, details, callback]). Any tests added in this callback will belong to the group, and will not be run.

        Returns void

      externalfixme

      • fixme(title: string, callback: () => void): void
      • fixme(callback: () => void): void
      • fixme(title: string, details: TestDetails, callback: () => void): void

      • Declares a test group similarly to test.describe([title, details, callback]). Tests in this group are marked as "fixme" and will not be executed.

        • test.describe.fixme(title, callback)
        • test.describe.fixme(callback)
        • test.describe.fixme(title, details, callback)

        Usage

        test.describe.fixme('broken tests that should be fixed', () => {
          test('example', async ({ page }) => {
            // This test will not run
          });
        });

        You can also omit the title.

        test.describe.fixme(() => {
          // ...
        });

        Parameters

        • externaltitle: string

          Group title.

        • externalcallback: () => void

          A callback that is run immediately when calling test.describe.fixme([title, details, callback]). Any tests added in this callback will belong to the group, and will not be run.

          Returns void

        Page Options