Serenity/JS

https://serenity-js.org/api/
Admin
Serenity/JS is a modular, full-stack acceptance testing framework built on Node.js that provides...
Tokens:206,132
Snippets:2,336
Trust Score:8.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install @serenity-js/local-server

Source: https://serenity-js.org/api/local-server

Install the required packages via npm.

```bash
npm install --save-dev @serenity-js/core @serenity-js/local-server
```

--------------------------------

### Install Serenity/JS Web dependencies

Source: https://serenity-js.org/api/web

Install the core and web packages via npm.

```bash
npm install --save-dev @serenity-js/core @serenity-js/web
```

--------------------------------

### Install Serenity/JS Assertions

Source: https://serenity-js.org/api/assertions

Use npm to install the core and assertions packages.

```bash
npm install --save-dev @serenity-js/core @serenity-js/assertions
```

--------------------------------

### Install Mocha adapter

Source: https://serenity-js.org/api/protractor

Install the adapter to use Serenity/JS Protractor with Mocha.

```bash
npm install --save-dev @serenity-js/mocha
```

--------------------------------

### StartLocalServer.onRandomPort

Source: https://serenity-js.org/api/local-server/class/StartLocalServer

Starts a local test server on a random available port.

```APIDOC
## StartLocalServer.onRandomPort()

### Description
Starts a local test server on a random available port.

### Returns
- **Interaction** - An interaction object to be performed by an actor.
```

--------------------------------

### Example HTML widget

Source: https://serenity-js.org/api/web/class/CssClasses

The HTML structure used for the following examples.

```html
<ul id="shopping-list" class="active favourite">  
  <li class="bought">Coffee<li>  
  <li class="buy">Honey<li>  
  <li class="buy">Chocolate<li>  
</ul>  
```

--------------------------------

### ManageALocalServer.listen

Source: https://serenity-js.org/api/local-server/class/ManageALocalServer

Starts the server on the first free port within the specified range.

```APIDOC
## ManageALocalServer.listen

### Description
Starts the server on the first free port between preferredPort and highestPort, inclusive.

### Parameters
- **preferredPort** (number) - Optional - Lower bound of the preferred port range (default: 8000).
- **highestPort** (number) - Optional - Upper bound of the preferred port range (default: 65535).

### Returns
- **Promise<void>**
```

--------------------------------

### Initialize a new WebdriverIO project

Source: https://serenity-js.org/api/webdriverio

Run this command in your terminal to start the WebdriverIO project wizard.

```bash
npm init wdio ./my-project
```

--------------------------------

### Install Serenity/JS Core

Source: https://serenity-js.org/api/core

Install the core package as a development dependency in your project.

```bash
npm install --save-dev @serenity-js/core
```

--------------------------------

### Install Jasmine adapter

Source: https://serenity-js.org/api/protractor

Install the adapter to use Serenity/JS Protractor with Jasmine.

```bash
npm install --save-dev @serenity-js/jasmine
```

--------------------------------

### Install Serenity/JS Console Reporter

Source: https://serenity-js.org/api/console-reporter

Install the core and console reporter packages as development dependencies.

```bash
npm install --save-dev @serenity-js/core @serenity-js/console-reporter
```

--------------------------------

### Equivalent setup for custom fixtures

Source: https://serenity-js.org/api/playwright-test/function/useBase

Shows how to chain useFixtures onto the useBase configuration.

```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 }`);  
    }  
  })  
```

--------------------------------

### Equivalent setup for default test API

Source: https://serenity-js.org/api/playwright-test/function/useBase

Demonstrates the underlying useBase call equivalent to importing directly from the package.

```typescript
import { test as playwrightBaseTest } from '@playwright/test'  
import { useBase } from '@serenity-js/playwright-test'  
  
const { describe, it, test, beforeEach, afterEach } = useBase(playwrightBaseTest)  
```

--------------------------------

### Install Serenity/JS reporting modules

Source: https://serenity-js.org/api/playwright-test

Install the necessary npm packages to enable Console and HTML reporting.

```bash
npm install --save-dev @serenity-js/console-reporter @serenity-js/html-reporter
```

--------------------------------

### Example HTML widget

Source: https://serenity-js.org/api/web/class/DoubleClick

An example HTML structure representing a user profile widget that triggers an editor on double-click.

```html
<!--  
    The editor shows up when the user double-clicks  
    on one of the properties of their profile  
    and lets them change the value of that property.  
-->  
<div id="user-profile">  
    <ul>  
        <li id="display-name" ondblclick="edit(this)">User12345</li>  
        <li id="email-address" ondblclick="edit(this)">tester@example.org</li>  
    </ul>  
    <form id="editor" class="hidden">  
        <input type="text" value="" />  
    </form>  
</div>
```

--------------------------------

### Install Serenity/JS HTML Reporter

Source: https://serenity-js.org/api/html-reporter

Install the reporter along with core and web dependencies to enable full reporting features including screenshot capture.

```bash
npm install --save-dev @serenity-js/core @serenity-js/web @serenity-js/html-reporter
```

--------------------------------

### HTML Select Widget Example

Source: https://serenity-js.org/api/web/class/Select

Example of a standard HTML select element used for testing.

```html
<select data-test='countries'>  
  <option value='UK'>United Kingdom</option>  
  <option value='PL'>Poland</option>  
  <option value='US'>United States</option>  
</select>
```

--------------------------------

### StartLocalServer.onRandomPortBetween

Source: https://serenity-js.org/api/local-server/class/StartLocalServer

Instructs the actor to start a local test server on a random port within a specified range.

```APIDOC
## StartLocalServer.onRandomPortBetween(lowestPort, highestPort)

### Description
Instructs the Actor to start a local test server on a random port between lowestPort and highestPort, inclusive.

### Parameters
- **lowestPort** (Answerable<number>) - Required - Lower bound of the preferred port range.
- **highestPort** (Answerable<number>) - Required - Upper bound of the preferred port range.

### Returns
- **Interaction** - An interaction object to be performed by an actor.
```

--------------------------------

### Install Serenity/JS Playwright dependencies

Source: https://serenity-js.org/api/playwright

Run this command to install the necessary Serenity/JS packages for Playwright.

```bash
npm install --save-dev @serenity-js/assertions @serenity-js/console-reporter @serenity-js/core @serenity-js/html-reporter @serenity-js/web @serenity-js/playwright
```

--------------------------------

### Install Serenity/JS REST dependencies

Source: https://serenity-js.org/api/rest

Use npm to install the required core, rest, and assertion packages along with axios.

```bash
npm install --save-dev @serenity-js/core @serenity-js/rest @serenity-js/assertions axios
```

--------------------------------

### Serve Report Locally

Source: https://serenity-js.org/api/html-reporter

Start a local server to view the generated Serenity/JS report.

```bash
npx @serenity-js/html-reporter serve --dir ./reports/serenity-js --open  
```

--------------------------------

### StartLocalServer.onPort

Source: https://serenity-js.org/api/local-server/class/StartLocalServer

Instructs the actor to start a local test server on a preferred port, or a random one if the preferred port is unavailable.

```APIDOC
## StartLocalServer.onPort(preferredPort)

### Description
Instructs the Actor to start a local test server on a preferredPort, or a random one if that's not available.

### Parameters
- **preferredPort** (Answerable<number>) - Required - The preferred port number.

### Returns
- **Interaction** - An interaction object to be performed by an actor.
```

--------------------------------

### HTML widget structure

Source: https://serenity-js.org/api/web/class/ComputedStyle

Example HTML structure for a shopping list used in subsequent examples.

```html
<ul id="shopping-list" style="display: block">  
  <li style="display: block">Coffee<li>  
  <li style="display: none">Honey<li>  
  <li style="display: block">Chocolate<li>  
</ul>  
```

--------------------------------

### Install Serenity BDD reporter

Source: https://serenity-js.org/api/serenity-bdd

Use npm to install the core Serenity/JS package and the Serenity BDD reporter as development dependencies.

```bash
npm install --save-dev @serenity-js/core @serenity-js/serenity-bdd
```

--------------------------------

### Install Serenity/JS Jasmine dependencies

Source: https://serenity-js.org/api/jasmine

Install the core framework, console reporter, and Jasmine integration package via npm.

```bash
npm install --save-dev @serenity-js/core @serenity-js/console-reporter @serenity-js/jasmine
```

--------------------------------

### Install Serenity/JS Mocha dependencies

Source: https://serenity-js.org/api/mocha

Install the core Serenity/JS packages and the Mocha adapter via npm.

```bash
npm install --save-dev @serenity-js/core @serenity-js/console-reporter @serenity-js/mocha
```

--------------------------------

### Manage a raw Node.js server

Source: https://serenity-js.org/api/local-server/class/ManageALocalServer

Demonstrates how to use ManageALocalServer to start a local HTTP listener, perform a request, and shut down the server.

```typescript
import { actorCalled } from '@serenity-js/core'  
import { CallAnApi, GetRequest, Send } from '@serenity-js/rest'  
import { ManageALocalServer, LocalTestServer, StartLocalServer, StopLocalServer } from '@serenity-js/local-server'  
import { Ensure, equals } from '@serenity-js/assertions'  
  
import * as axios from 'axios'  
import * as http from 'http'  
  
const server = http.createServer(function (request, response) {  
  response.setHeader('Connection', 'close');  
  response.end('Hello!');  
})  
  
await actorCalled('Apisit')  
  .whoCan(  
    ManageALocalServer.runningAHttpListener(server),  
    CallAnApi.using(axios.create()),  
  )  
  .attemptsTo(  
    StartLocalServer.onRandomPort(),  
    Send.a(GetRequest.to(LocalServer.url())),  
    Ensure.that(LastResponse.status(), equals(200)),  
    Ensure.that(LastResponse.body<string>(), equals('Hello!')),  
    StopLocalServer.ifRunning(),  
  )  
```

--------------------------------

### Example HTML widget

Source: https://serenity-js.org/api/web/class/Clear

A simple HTML form input used for demonstration purposes.

```html
<form>  
  <input type="text" name="example" id="example" />  
</form>  
```

--------------------------------

### Configure test execution modes and settings

Source: https://serenity-js.org/api/playwright-test/function/describe

Examples demonstrating how to set parallel, default, or serial modes, as well as configuring retries and timeouts for test suites.

```typescript
// 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 }) => {});
```

```typescript
// Tests in this file run in order. Retries, if any, run independently.  
test.describe.configure({ mode: 'default' });  
test('runs first', async ({ page }) => {});  
test('runs second', async ({ page }) => {});
```

```typescript
// Annotate tests as inter-dependent.  
test.describe.configure({ mode: 'serial' });  
test('runs first', async ({ page }) => {});  
test('runs second', async ({ page }) => {});
```

```typescript
// 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 }) => {});
```

```typescript
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 }) => {});  
});
```

--------------------------------

### Integrating WebdriverIO with Serenity/JS

Source: https://serenity-js.org/api/webdriverio/interface/WithSerenityConfig

Example of a wdio.conf.ts file configured with Serenity/JS settings.

```typescript
// wdio.conf.ts  
import { WithSerenityConfig } from '@serenity-js/webdriverio'  
  
export const config: WebdriverIO.Config & WithSerenityConfig = {  
  
  framework: '@serenity-js/webdriverio',  
  
  serenity: {  
    runner: 'cucumber',  
    // runner: 'mocha',  
    // runner: 'jasmine',  
  
    crew: [  
      // Optional, print test execution results to standard output  
      '@serenity-js/console-reporter',  
  
      // Optional, produce Serenity BDD reports  
      // and living documentation (HTML)  
      '@serenity-js/serenity-bdd',  
      [ '@serenity-js/core:ArtifactArchiver', {  
          outputDirectory: 'target/site/serenity'  
      } ],  
  
      // Optional, automatically capture screenshots  
      // upon interaction failure  
      [ '@serenity-js/web:Photographer', {  
          strategy: 'TakePhotosOfFailures'  
          // strategy: 'TakePhotosOfInteractions'  
      } ],  
    ]  
  },  
  
  // Configure your Cucumber runner  
  cucumberOpts: {  
    // see Cucumber configuration options below  
  },  
  
  // ... or Jasmine runner  
  jasmineOpts: {  
    // see Jasmine configuration options below  
  },  
  
  // ... or Mocha runner  
  mochaOpts: {  
     // see Mocha configuration options below  
  },  
  
  runner: 'local',  
  
  specs: [  
    './features/*.feature',  
  
    // or for Mocha/Jasmine  
    // './*.spec.ts'  
  ],  
  
  // Any other WebdriverIO configuration  
}  
```

--------------------------------

### using

Source: https://serenity-js.org/api/core/class/TakeNotes

Static method to initialize a TakeNotes ability with a specific notepad instance.

```APIDOC
## static using<N>(notepad: Notepad<N>)

### Description
Initializes an Ability to TakeNotes using a Notepad with initial state.

### Parameters
- **notepad** (Notepad<N>) - Required - The notepad instance to initialize with.

### Returns
- **TakeNotes<N>** - A new instance of TakeNotes.
```

--------------------------------

### Define configuration parameters

Source: https://serenity-js.org/api/protractor-adapter/interface/Config

Example of defining an arbitrary params object that can be accessed via browser.params in tests.

```javascript
params: { login: { user: 'Jane', password: '1234' } }
```

--------------------------------

### Instantiate a Notepad with initial state

Source: https://serenity-js.org/api/core/class/Notepad

Shows how to create a Notepad with pre-defined data and access it using the notes question adapter.

```typescript
import { actorCalled, Notepad, notes, TakeNotes } from '@serenity-js/core'  
import { Ensure, equals } from '@serenity-js/assertions'  
  
interface MyNotes {  
  personalDetails: {  
    firstName: string;  
    lastName: string;  
  }  
}  
  
actorCalled('Leonard')  
  .whoCan(  
    TakeNotes.using(  
      Notepad.with<MyNotes>({
        personalDetails: {  
          firstName: 'Leonard',  
          lastName: 'McLaud',  
        }  
      })  
    )  
  )  
  .attemptsTo(  
    Ensure.that(  
      notes<MyNotes>().get('personalDetails').firstName,  
      equals('Leonard')  
    ),  
  )  
```

--------------------------------

### initialise()

Source: https://serenity-js.org/api/playwright/class/SelfLaunchingPlaywrightBrowsingSessionWithElectron

Launches the Electron application using configured launch options. This method is idempotent.

```APIDOC
### initialise()

Launches the Electron application. Calling this multiple times will only launch the application once.

#### Returns
- Promise<void>
```

--------------------------------

### Navigate to a URL

Source: https://serenity-js.org/api/web/class/Navigate

Examples of navigating to relative paths and absolute URLs using the Navigate.to method.

```typescript
import { actorCalled } from '@serenity-js/core'  
import { Navigate } from '@serenity-js/web'  
  
await actorCalled('Hannu')  
  .attemptsTo(  
    Navigate.to('/search'),  
  )  
```

```typescript
import { actorCalled } from '@serenity-js/core'  
import { Navigate } from '@serenity-js/web'  
  
await actorCalled('Hannu')  
  .whoCan(BrowseTheWeb.using(browser))  
  .attemptsTo(  
    Navigate.to('https://mycompany.org/login'),  
  )  
```

--------------------------------

### Notepad.with<N>(notes: N)

Source: https://serenity-js.org/api/core/class/Notepad

Instantiates a new Notepad with an initial state.

```APIDOC
## Notepad.with<N>(notes: N)

### Description
Instantiates a new Notepad with an initial state.

### Parameters
- **N** (Record<any, any>) - Type parameter for the notes structure.
- **notes** (N) - The initial notes to store.

### Returns
- **Notepad<N>** - A new Notepad instance initialized with the provided notes.
```

--------------------------------

### Install Cucumber.js adapter

Source: https://serenity-js.org/api/protractor

Install the adapter to use Serenity/JS Protractor with Cucumber.js.

```bash
npm install --save-dev @serenity-js/cucumber
```

--------------------------------

### Example HTML widget for right-click

Source: https://serenity-js.org/api/web/class/RightClick

A sample HTML structure featuring an input field that triggers a custom context menu on a right-click event.

```html
<form>  
  <input type="text" id="field"  
    oncontextmenu="showMenu(); return false;" />  
  
  <div id="context-menu" style="display:none">  
    Custom context menu  
  </div>  
</form>  
  
<script>  
  function showMenu() {  
    document.getElementById("context-menu").style.display = 'block';  
  }  
</script>  
```

--------------------------------

### Example HTML widget for modal dialog

Source: https://serenity-js.org/api/web/class/ModalDialog

A sample HTML button and script that triggers a confirmation dialog to demonstrate modal interaction.

```html
<button id="trigger" onclick="trigger()">Trigger Alert</button>  
<p id="result"></p>  
  
<script>  
  function trigger() {  
    document.getElementById("result").innerHTML = (  
      function () {  
        return confirm('Continue?')  
          ? 'accepted'  
          : 'dismissed';  
      }  
    )();  
  }  
</script>
```

--------------------------------

### init(cid, config, specs, capabilities, reporter)

Source: https://serenity-js.org/api/webdriverio-8-adapter/class/WebdriverIOFrameworkAdapterFactory

Initializes the WebdriverIO framework adapter with the provided configuration and environment details.

```APIDOC
## init

### Description
Initializes the WebdriverIO framework adapter.

### Parameters
- **cid** (string) - Required - The capability ID.
- **config** (WebdriverIOConfig) - Required - The WebdriverIO configuration object.
- **specs** (string[]) - Required - An array of specification file paths.
- **capabilities** (RemoteCapability) - Required - The remote capability configuration.
- **reporter** (EventEmitter<DefaultEventMap> & ProvidesWriteStream & InitialisesReporters) - Required - The reporter instance.

### Returns
- **Promise<WebdriverIOFrameworkAdapter>** - A promise that resolves to the initialized WebdriverIOFrameworkAdapter.
```

--------------------------------

### Install Serenity/JS Protractor dependencies

Source: https://serenity-js.org/api/protractor

Install the core Serenity/JS and Protractor integration packages.

```bash
npm install --save-dev @serenity-js/core @serenity-js/protractor
```

--------------------------------

### Install TypeScript dependencies

Source: https://serenity-js.org/api/mocha

Install necessary packages for running TypeScript tests with Mocha.

```bash
npm install --save-dev typescript ts-node
```

--------------------------------

### initialise

Source: https://serenity-js.org/api/playwright/class/BrowseTheWebWithPlaywright

Initializes the ability.

```APIDOC
### initialise()

Initializes the ability. Returns a Promise that resolves when initialization is complete.
```

--------------------------------

### SystemContextView Usage

Source: https://serenity-js.org/api/html-reporter-serenity/class/SystemContextView

Example of using SystemContextView methods within an integration test to verify environment details.

```APIDOC
## Usage in an integration test

```typescript
await actor.attemptsTo(
  systemContextView.open(),
  Ensure.that(systemContextView.nodeVersion(), includes('22')),
  Ensure.that(systemContextView.testRunner(), includes('Playwright')),
  Ensure.that(systemContextView.operatingSystem(), includes('Linux')),
);
```
```

--------------------------------

### open()

Source: https://serenity-js.org/api/html-reporter-serenity/class/SystemContextView

Navigates to the System Context view via the sidebar navigation.

```APIDOC
### open()

Returns a `Task` to perform the navigation.

#### Example
```typescript
await actor.attemptsTo(
  systemContextView.open(),
);
```
```

--------------------------------

### Install Serenity/JS Cucumber dependencies

Source: https://serenity-js.org/api/cucumber

Run this command to install the necessary packages for Cucumber integration.

```bash
npm install --save-dev @serenity-js/cucumber @serenity-js/core
```

--------------------------------

### constructor

Source: https://serenity-js.org/api/web/class/PhotoTakingStrategy

Creates a new instance of the PhotoTakingStrategy.

```APIDOC
## constructor

### Description
Creates a new instance of the PhotoTakingStrategy.

### Signature
`new PhotoTakingStrategy(): PhotoTakingStrategy`

### Returns
- **PhotoTakingStrategy** - A new instance of the strategy.
```

--------------------------------

### HTML Multiple Select Widget Example

Source: https://serenity-js.org/api/web/class/Select

Example of an HTML select element with the multiple attribute.

```html
<select multiple data-test='countries'>  
  <option value='UK'>United Kingdom</option>  
  <option value='PL'>Poland</option>  
  <option value='US'>United States</option>  
</select>
```

--------------------------------

### open()

Source: https://serenity-js.org/api/html-reporter-serenity/class/ScenariosView

Navigates to the Test Scenarios view.

```APIDOC
## open()

### Description
Navigates to the Test Scenarios view via the sidebar navigation.

### Returns
- **Task** - A Serenity/JS Task to be performed by an actor.
```

--------------------------------

### open(): Task

Source: https://serenity-js.org/api/html-reporter-serenity/class/ConsistencyView

Navigates to the Consistency view via the sidebar navigation.

```APIDOC
## open()

### Description
Navigates to the Consistency view via the sidebar navigation.

### Returns
- **Task** - A Serenity/JS Task to be performed by an actor.
```

--------------------------------

### open()

Source: https://serenity-js.org/api/html-reporter-serenity/class/ScenarioDetailView

Navigates to the Scenario Detail view via the sidebar navigation.

```APIDOC
### open()

Navigates to the Scenario Detail view via the sidebar navigation.

#### Returns
- **Task**

#### Example
```typescript
await actor.attemptsTo(  
  scenarioDetailView.open(),  
);
```
```

--------------------------------

### init

Source: https://serenity-js.org/api/webdriverio-8

Initializes the WebdriverIO framework adapter with the provided configuration, specifications, and capabilities.

```APIDOC
## init(cid, config, specs, capabilities, reporter)

### Description
Initializes the WebdriverIO framework adapter, setting up the environment for test execution within Serenity/JS.

### Parameters
- **cid** (string) - Required - The connection ID.
- **config** (WebdriverIOConfig) - Required - The WebdriverIO configuration object.
- **specs** (string[]) - Required - An array of specification file paths.
- **capabilities** (RemoteCapability) - Required - The browser capabilities for the session.
- **reporter** (EventEmitter) - Required - The reporter instance for handling test events.

### Returns
- **Promise<{ hasTests: () => boolean; run: () => Promise<number> }>** - A promise that resolves to an object containing methods to check for tests and execute the test suite.
```

--------------------------------

### Send a GET request

Source: https://serenity-js.org/api/rest/class/Send

Performs a GET request to a specific endpoint and verifies the response status code.

```typescript
import { actorCalled } from '@serenity-js/core'  
import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'  
import { Ensure, equals } from '@serenity-js/assertions'  
  
await actorCalled('Apisitt')  
  .whoCan(CallAnApi.at('https://api.example.org/'))  
  .attemptsTo(  
    Send.a(GetRequest.to('/books/0-688-00230-7')),  
    Ensure.that(LastResponse.status(), equals(200)),  
  )
```

--------------------------------

### Install Serenity/JS modules

Source: https://serenity-js.org/api/webdriverio-8

Install the required Serenity/JS packages via NPM for an existing WebdriverIO 8 project.

```bash
npm install --save-dev @serenity-js/core @serenity-js/web @serenity-js/webdriverio-8 @serenity-js/assertions @serenity-js/rest @serenity-js/console-reporter @serenity-js/html-reporter
```

--------------------------------

### Setting and Chaining Notes with NotepadAdapter

Source: https://serenity-js.org/api/core/class/NotepadAdapter

Demonstrates how to configure an actor with an empty notepad and chain multiple set operations to record values.

```typescript
 import { actorCalled, notes, TakeNotes } from '@serenity-js/core'  
 import { Ensure, equals } from '@serenity-js/assertions'  
  
 interface MyNotes {  
     stringNote: string;  
     numberNote: number;  
 }  
  
await actorCalled('Alice')  
  .whoCan(TakeNotes.usingAnEmptyNotepad<MyNotes>());  
  .attemptsTo(  
  
    notes<MyNotes>()  
      .set('stringNote', 'example')  
      .set('numberNote', Promise.resolve(42))  
      .set('stringNote', 'another example'),  
  
    Ensure.equal(notes().toJSON(), {  
      firstNote: 'another example',  
      secondNote: 42,  
    })  
)
```

--------------------------------

### Initialize WebdriverIO Framework Adapter

Source: https://serenity-js.org/api/webdriverio-8

The init function configures the adapter with the provided WebdriverIO settings and returns a promise containing test execution methods.

```typescript
init(cid: string, config: WebdriverIOConfig, specs: string[], capabilities: RemoteCapability, reporter: EventEmitter<DefaultEventMap> & ProvidesWriteStream & InitialisesReporters): Promise<{ hasTests: () => boolean; run: () => Promise<number> }>
```

--------------------------------

### Display CLI Help

Source: https://serenity-js.org/api/html-reporter

View available commands and options for the Serenity/JS HTML Reporter.

```bash
npx @serenity-js/html-reporter --help  
```

--------------------------------

### default(config?: SerenityBDDReporterConfig)

Source: https://serenity-js.org/api/serenity-bdd/function/default

Initializes the SerenityBDDReporter with the provided configuration, returning a builder for the reporter.

```APIDOC
## default(config?: SerenityBDDReporterConfig)

### Description
Initializes the SerenityBDDReporter. This function is used to configure and create a builder for the SerenityBDD reporter instance.

### Parameters
- **config** (SerenityBDDReporterConfig) - Optional - Configuration object for the SerenityBDD reporter. Defaults to an empty object.

### Returns
- **StageCrewMemberBuilder<SerenityBDDReporter>** - A builder instance for the SerenityBDD reporter.
```

--------------------------------

### Verify GET request response with LastResponse

Source: https://serenity-js.org/api/rest/class/LastResponse

Demonstrates using LastResponse to validate the status code, headers, and body of a GET request.

```typescript
import { actorCalled } from '@serenity-js/core'  
import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'  
import { Ensure, equals } from '@serenity-js/assertions'  
  
interface Book {  
    title: string;  
    author: string;  
}  
  
await actorCalled('Apisitt')  
  .whoCan(CallAnApi.at('https://api.example.org/'))  
  .attemptsTo(  
    Send.a(GetRequest.to('/books/0-688-00230-7')),  
    Ensure.that(LastResponse.status(), equals(200)),  
    Ensure.that(LastResponse.header('Content-Type'), equals('application/json')),  
    Ensure.that(LastResponse.body<Book>(), equals({  
        title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',  
        author: 'Robert M. Pirsig',  
    })),  
  )  
```

--------------------------------

### Serve the HTML Report

Source: https://serenity-js.org/api/html-reporter

Run the serve command via npx to view the generated report locally.

```bash
npx @serenity-js/html-reporter serve --dir ./reports/serenity-js --open
```

--------------------------------

### SystemContextView Constructor

Source: https://serenity-js.org/api/html-reporter-serenity/class/SystemContextView

Initializes a new instance of the SystemContextView class.

```APIDOC
## constructor(rootElement, navigation?)

### Description
Creates a new SystemContextView instance.

### Parameters
- **rootElement** (PageElement<NET> | QuestionAdapter<PageElement<NET>>) - Required - The root element for the context view.
- **navigation** (Navigation) - Optional - The navigation instance.
```

--------------------------------

### Verify response to a GET request

Source: https://serenity-js.org/api/rest/class/GetRequest

Demonstrates how an actor sends a GET request to a specific endpoint and verifies the response status and body content.

```typescript
 import { actorCalled } from '@serenity-js/core'  
 import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'  
 import { Ensure, equals } from '@serenity-js/assertions'  
  
 interface Book {  
     title: string;  
     author: string;  
 }  
  
 await actorCalled('Apisitt')  
   .whoCan(CallAnApi.at('https://api.example.org/'))  
   .attemptsTo(  
     Send.a(GetRequest.to('/books/0-688-00230-7')),  
     Ensure.that(LastResponse.status(), equals(200)),  
     Ensure.that(LastResponse.body<Book>(), equals({  
         title: 'Zen and the Art of Motorcycle Maintenance: An Inquiry into Values',  
         author: 'Robert M. Pirsig',  
     })),  
   )  
```

--------------------------------

### name

Source: https://serenity-js.org/api/protractor/class/ProtractorPage

Gets the page name.

```APIDOC
## name()

### Description
Gets the page name.

### Returns
- **Promise<string>**
```

--------------------------------

### title

Source: https://serenity-js.org/api/protractor/class/ProtractorPage

Gets the page title.

```APIDOC
## title()

### Description
Gets the page title.

### Returns
- **Promise<string>**
```

--------------------------------

### viewportSize

Source: https://serenity-js.org/api/protractor/class/ProtractorPage

Gets the current viewport size.

```APIDOC
## viewportSize()

### Description
Gets the current viewport size.

### Returns
- **Promise<{ width: number; height: number }>**
```

--------------------------------

### Populate Notepad with initial state

Source: https://serenity-js.org/api/core/class/TakeNotes

Initialize an actor with a predefined set of notes using the Notepad.with method.

```typescript
import { actorCalled, Log, Note, Notepad, TakeNotes } from '@serenity-js/core'  
  
interface MyNotes {  
  firstName: string;  
  lastName: string;  
}  
  
await actorCalled('Leonard')  
  .whoCan(  
    TakeNotes.using(Notepad.with<MyNotes>({
      firstName: 'Leonard',  
      lastName: 'McLaud',  
    }))  
  )  
  .attemptsTo(  
    notes<MyNotes>().set('lastName', 'Shelby'),  
    Log.the(notes().get('firstName')),  
    // emits 'Leonard'  
  
    Log.the(notes().get('lastName')),  
    // emits 'Shelby'  
  )  
```

--------------------------------

### url

Source: https://serenity-js.org/api/protractor/class/ProtractorPage

Gets the current page URL.

```APIDOC
## url()

### Description
Gets the current page URL.

### Returns
- **Promise<URL>**
```

--------------------------------

### get()

Source: https://serenity-js.org/api/cucumber-adapter/interface/SerenityFormatterOutput

Retrieves the OutputDescriptor for the formatter output.

```APIDOC
## get()

### Description
Retrieves the OutputDescriptor associated with the formatter output.

### Returns
- **OutputDescriptor** - The descriptor object for the output.
```

--------------------------------

### usingAnEmptyNotepad

Source: https://serenity-js.org/api/core/class/TakeNotes

Static method to initialize a TakeNotes ability with an empty notepad.

```APIDOC
## static usingAnEmptyNotepad<N>()

### Description
Initializes an Ability to TakeNotes with Notepad.empty.

### Returns
- **TakeNotes<N>** - A new instance of TakeNotes initialized with an empty notepad.
```

--------------------------------

### new MochaAdapter(config: MochaConfig, loader: ModuleLoader)

Source: https://serenity-js.org/api/mocha-adapter/class/MochaAdapter

Constructs a new instance of the MochaAdapter.

```APIDOC
## constructor

### Description
Creates a new MochaAdapter instance.

### Parameters
- **config** (MochaConfig) - Required - Configuration for the Mocha runner.
- **loader** (ModuleLoader) - Required - The module loader instance.

### Returns
- **MochaAdapter** - A new instance of the adapter.
```

--------------------------------

### get()

Source: https://serenity-js.org/api/cucumber-adapter/class/TempFileOutput

Retrieves the output descriptor for the temporary file.

```APIDOC
## get()

### Description
Returns the OutputDescriptor associated with the current temporary file output.

### Returns
- **OutputDescriptor** - The descriptor object containing details about the output.
```

--------------------------------

### SystemContextView Instantiation

Source: https://serenity-js.org/api/html-reporter-serenity/class/SystemContextView

How to instantiate the SystemContextView class using a PageElement and Navigation object.

```APIDOC
## Instantiation

```typescript
import { SystemContextView, Navigation } from '@serenity-js/html-reporter/serenity';
import { By, PageElement } from '@serenity-js/web';

const systemContextView = new SystemContextView(
  PageElement.located(By.css('[data-testid="system-context"]')).describedAs('system context view'),
  new Navigation(),
);
```
```

--------------------------------

### onTestBegin

Source: https://serenity-js.org/api/playwright-test/class/default

Lifecycle method called when a specific test starts.

```APIDOC
## onTestBegin(test: TestCase, result: TestResult)

### Description
Invoked when a specific test case begins execution.

### Parameters
- **test** (TestCase) - Required - The test case being started.
- **result** (TestResult) - Required - The initial test result object.
```

--------------------------------

### TakeNotes.usingAnEmptyNotepad()

Source: https://serenity-js.org/api/core/class/TakeNotes

Initializes an actor with an empty notepad to store and retrieve information during test execution.

```APIDOC
## TakeNotes.usingAnEmptyNotepad<T>()

### Description
Creates an Ability that allows an Actor to remember information. The optional generic type T can be used to define the structure of the notes.

### Usage
```typescript
import { actorCalled, TakeNotes } from '@serenity-js/core';

await actorCalled('ActorName')
  .whoCan(TakeNotes.usingAnEmptyNotepad<MyNotes>());
```

### Methods
- **notes().set(key, value)**: Stores a value in the notepad.
- **notes().get(key)**: Retrieves a value from the notepad.
- **notes().has(key)**: Checks if a note exists.
```

--------------------------------

### GetRequest.to(url)

Source: https://serenity-js.org/api/rest/class/GetRequest

Creates a GET request to the specified URL path.

```APIDOC
## GetRequest.to(url)

### Description
Creates an instance of a GET request to be sent to the specified resource path.

### Usage
```typescript
Send.a(GetRequest.to('/path/to/resource'))
```

### Parameters
- **url** (string) - Required - The path or URL to which the GET request should be sent.
```

--------------------------------

### Instantiate SystemContextView

Source: https://serenity-js.org/api/html-reporter-serenity/class/SystemContextView

Initialize the SystemContextView by providing a PageElement locator and a Navigation instance.

```typescript
import { SystemContextView, Navigation } from '@serenity-js/html-reporter/serenity';  
import { By, PageElement } from '@serenity-js/web';  
  
const systemContextView = new SystemContextView(  
  PageElement.located(By.css('[data-testid="system-context"]')).describedAs('system context view'),  
  new Navigation(),  
);
```

--------------------------------

### Quick Start Assertion

Source: https://serenity-js.org/api/assertions

Perform a basic assertion using Ensure.that.

```typescript
import { actorCalled } from '@serenity-js/core';
import { Ensure, equals } from '@serenity-js/assertions';

await actorCalled('Alice').attemptsTo(
    Ensure.that(2 + 2, equals(4))
)
```

--------------------------------

### open()

Source: https://serenity-js.org/api/html-reporter-serenity/class/CapabilitiesView

Navigates to the Capabilities view via the sidebar navigation.

```APIDOC
## open()

### Description
Navigates to the Capabilities view via the sidebar navigation.

### Returns
- **Task**
```

--------------------------------

### Get scenario count

Source: https://serenity-js.org/api/html-reporter-serenity/class/TimelineView

Retrieve the number of currently visible timeline rows.

```typescript
Ensure.that(timelineView.scenarioCount(), equals(42))
```

--------------------------------

### Get filter bar label

Source: https://serenity-js.org/api/html-reporter-serenity/class/FilterBar

Retrieves the heading text of the filter bar.

```typescript
await actor.attemptsTo(  
  Ensure.that(filterBar.label(), equals('FILTER BY OUTCOME')),  
);
```

--------------------------------

### onBegin

Source: https://serenity-js.org/api/playwright-test/class/default

Lifecycle method called when the test run begins.

```APIDOC
## onBegin(config: FullConfig, suite: Suite)

### Description
Invoked when the Playwright test run starts.

### Parameters
- **config** (FullConfig) - Required - The full Playwright configuration.
- **suite** (Suite) - Required - The root test suite.
```

--------------------------------

### Get selected sort value

Source: https://serenity-js.org/api/html-reporter-serenity/class/FilterBar

Retrieves the current value of the sort dropdown.

```typescript
await actor.attemptsTo(  
  Ensure.that(filterBar.selectedSort(), equals('name')),  
);
```

--------------------------------

### constructor

Source: https://serenity-js.org/api/playwright-test/class/default

Initializes a new instance of the SerenityReporterForPlaywrightTest.

```APIDOC
## constructor(config: SerenityReporterForPlaywrightTestConfig)

### Description
Creates a new instance of the reporter using the provided configuration.

### Parameters
- **config** (SerenityReporterForPlaywrightTestConfig) - Required - The configuration object for the reporter.
```

--------------------------------

### Get the size of the Notepad

Source: https://serenity-js.org/api/core/class/NotepadAdapter

Returns the current count of notes stored in the notepad.

```typescript
import { actorCalled, notes } from '@serenity-js/core'  
import { isTrue } from '@serenity-js/assertions'  
  
interface MyNotes {  
  myNote: string;  
}  
  
await actorCalled('Alice')  
  .whoCan(TakeNotes.using(Notepad.empty<MyNotes>()))  
  .attemptsTo(  
    Log.the(notes<MyNotes>().size()),   // emits 0  
    notes<MyNotes>().set('myNote', 'example value'),  
    Log.the(notes<MyNotes>().size()),   // emits 1  
  )  
```

--------------------------------

### default(config?: ConsoleReporterConfig)

Source: https://serenity-js.org/api/console-reporter/function/default

Initializes a new ConsoleReporter instance with the provided configuration.

```APIDOC
## default(config?: ConsoleReporterConfig)

### Description
Configures and returns a builder for the ConsoleReporter, which is responsible for reporting test execution progress to the console.

### Parameters
- **config** (ConsoleReporterConfig) - Optional - Configuration object for the reporter.

### Returns
- **StageCrewMemberBuilder<ConsoleReporter>** - A builder instance to register the reporter with the Serenity/JS stage.
```

--------------------------------

### url()

Source: https://serenity-js.org/api/local-server/class/LocalServer

Retrieves the URL of the local server started using the StartLocalServer interaction.

```APIDOC
## Method: url()

### Description
Retrieves the URL of the local server started using the `StartLocalServer` interaction.

### Returns
- **QuestionAdapter<string>** - An adapter containing the server URL.
```

--------------------------------

### the(options: DescriptionFormattingOptions)

Source: https://serenity-js.org/api/core/function/the

Creates a MetaQuestionAdapter by transforming a template literal, allowing for formatted descriptions of activities with optional trimming.

```APIDOC
## the(options: DescriptionFormattingOptions)

### Description
Creates a single-line description of an Activity by transforming a template literal into a MetaQuestionAdapter. This is used to provide human-readable descriptions for tasks and interactions.

### Signature
`the(options: DescriptionFormattingOptions): <Supported_Context_Type>(templates: TemplateStringsArray, ...placeholders: (MetaQuestion<Supported_Context_Type, any> | any)[]) => MetaQuestionAdapter<Supported_Context_Type, string>`

### Parameters
- **options** (DescriptionFormattingOptions) - Optional - Configuration object to trim the descriptions of template parameters.

### Example
```typescript
import { actorCalled, Task, the } from '@serenity-js/core';

const dial = (phoneNumber: Answerable<string>) => 
 Task.where(the({ maxLength: 10 }) `#actor dials ${ phoneNumber }`, /* ... */);

await actorCalled('Alice').attemptsTo(
  dial('(555) 123-4567'),
  // reported as: Alice dials "(555) 123-..."
);
```

--------------------------------

### Initialize Playwright Test Project

Source: https://serenity-js.org/api/playwright-test

Command to generate a new Playwright Test project structure.

```bash
npm init playwright@latest
```

--------------------------------

### port()

Source: https://serenity-js.org/api/local-server/class/LocalServer

Retrieves the port number of the local server started using the StartLocalServer interaction.

```APIDOC
## Method: port()

### Description
Retrieves the port number of the local server started using the `StartLocalServer` interaction.

### Returns
- **QuestionAdapter<number>** - An adapter containing the server port number.
```

--------------------------------

### forMocha(mochaOpts)

Source: https://serenity-js.org/api/protractor-adapter/class/TestRunnerLoader

Initializes a TestRunnerAdapter for Mocha.

```APIDOC
## forMocha(mochaOpts: object)

### Description
Loads a TestRunnerAdapter configured for Mocha.

### Parameters
- **mochaOpts** (object) - Required - Configuration options for Mocha.

### Returns
- **TestRunnerAdapter** - The configured adapter.
```

--------------------------------

### Define an HTML input widget

Source: https://serenity-js.org/api/web/class/Value

Example HTML structure for an input element with a value attribute.

```html
<input type="text" id="username" value="Alice" />
```

--------------------------------

### open(): Task

Source: https://serenity-js.org/api/html-reporter-serenity/class/TestRunsView

Navigates to the Test Runs view via the sidebar navigation.

```APIDOC
## open()

### Description
Navigates to the Test Runs view via the sidebar navigation.

### Returns
- **Task**
```

--------------------------------

### Select single option interaction

Source: https://serenity-js.org/api/web/class/Select

Example of using Select.option to choose an item and verify it with Selected.optionIn.

```typescript
import { actorCalled } from '@serenity-js/core'  
import { Select, Selected } from '@serenity-js/web'  
import { Ensure, equals } from '@serenity-js/assertions'  
  
await actorCalled('Nick')  
  .whoCan(BrowseTheWeb.using(protractor.browser))  
  .attemptsTo(  
    Select.option('Poland').from(Countries.dropdown()),  
    Ensure.that(  
      Selected.optionIn(Countries.dropdown()),  
      equals('Poland')  
    ),  
  )  
```

--------------------------------

### constructor(fs: FileSystem)

Source: https://serenity-js.org/api/cucumber-adapter/class/TempFileOutput

Creates a new instance of the TempFileOutput class.

```APIDOC
## constructor

### Description
Initializes a new TempFileOutput instance with the provided FileSystem dependency.

### Parameters
- **fs** (FileSystem) - Required - The file system utility used for managing temporary files.
```

--------------------------------

### Retrieving Protractor Configuration Parameters

Source: https://serenity-js.org/api/protractor/class/BrowseTheWebWithProtractor

Examples for defining and accessing configuration parameters within Protractor.

```javascript
// protractor.conf.js  
exports.config = {  
  params: {  
    login: {  
      username: 'jane@example.org'  
      password: process.env.PASSWORD  
    }  
  }  
  // ...  
}  
```

```javascript
BrowseTheWebWithProtractor.as(actor).param('login')  
 // returns object with username and password  
```

```javascript
BrowseTheWeb.as(actor).param('login.username')  
 // returns string 'jane@example.org'  
```

--------------------------------

### Get current time using Clock

Source: https://serenity-js.org/api/core/class/Clock

Instantiate a Clock object and retrieve the current timestamp.

```typescript
const now: Timestamp = new Clock().now()
```

--------------------------------

### new SelfLaunchingPlaywrightBrowsingSessionWithElectron()

Source: https://serenity-js.org/api/playwright/class/SelfLaunchingPlaywrightBrowsingSessionWithElectron

Constructor for creating a new instance of the self-launching Electron browsing session.

```APIDOC
## Constructor

### Description
Creates a new instance of `SelfLaunchingPlaywrightBrowsingSessionWithElectron` to manage an Electron application lifecycle.

### Signature
`new SelfLaunchingPlaywrightBrowsingSessionWithElectron(launchOptions, extraBrowserContextOptions, selectors)`

### Parameters
- **launchOptions** (Object) - Configuration for launching the Electron app.
  - **args** (string[]) - Optional: Additional arguments to pass to the application.
  - **cwd** (string) - Optional: Current working directory to launch the application from.
  - **artifactsDir** (string) - Optional: Directory to save traces, videos, and downloads.
  - **env** (Object) - Optional: Environment variables for the Electron process.
  - **executablePath** (string) - Optional: Path to the Electron executable.
- **extraBrowserContextOptions** (Partial<ExtraBrowserContextOptions>) - Optional: Additional options for the browser context.
- **selectors** (Selectors) - Optional: Custom selectors configuration.
```

--------------------------------

### Instantiate Navigation

Source: https://serenity-js.org/api/html-reporter-serenity/class/Navigation

Import and create a new instance of the Navigation class.

```typescript
import { Navigation } from '@serenity-js/html-reporter/serenity';  
  
const navigation = new Navigation();
```

--------------------------------

### Select multiple options interaction

Source: https://serenity-js.org/api/web/class/Select

Example of using Select.options to choose multiple items and verify them with Selected.optionsIn.

```typescript
import { actorCalled } from '@serenity-js/core'  
import { Select, Selected } from '@serenity-js/web'  
import { Ensure, equals } from '@serenity-js/assertions'  
  
await actorCalled('Nick')  
  .whoCan(BrowseTheWeb.using(protractor.browser))  
  .attemptsTo(  
    Select.options('Poland', 'United States').from(Countries.dropdown()),  
    Ensure.that(  
      Selected.optionsIn(Countries.dropdown()),  
      equals([ 'Poland', 'United States' ])  
    ),  
  )  
```

--------------------------------

### run

Source: https://serenity-js.org/api/jasmine-adapter/class/JasmineAdapter

Executes the loaded test scenarios.

```APIDOC
## run()

### Description
Triggers the execution of all loaded Jasmine test scenarios.

### Returns
- **Promise<void>**
```

--------------------------------

### the(templates, ...placeholders)

Source: https://serenity-js.org/api/core/function/the

Creates a MetaQuestionAdapter that generates a descriptive string based on the provided template and placeholders.

```APIDOC
## the(templates, ...placeholders)

### Description
Creates a `MetaQuestionAdapter` that produces a descriptive string. It is typically used within `Task.where` to define actor actions with dynamic content.

### Parameters
- **templates** (TemplateStringsArray) - Required - The template string parts.
- **placeholders** (...(MetaQuestion<Supported_Context_Type, any> | any)[]) - Required - The values or questions to be interpolated into the template.

### Returns
- **MetaQuestionAdapter<Supported_Context_Type, string>** - An adapter that resolves to the formatted description string.

### Example
```typescript
import { actorCalled, description, Task } from '@serenity-js/core'  
  
const dial = (phoneNumber: Answerable<string>) =>  
 Task.where(description `#actor dials ${ phoneNumber }`, /* */)
```
```

--------------------------------

### open()

Source: https://serenity-js.org/api/html-reporter-serenity/class/AboutView

Navigates to the About view via the sidebar navigation.

```APIDOC
## open()

### Description
Performs a task to navigate to the About view.

### Returns
- **Task** - The navigation task.
```

--------------------------------

### Tag tests in a group

Source: https://serenity-js.org/api/playwright-test/function/test

Applies tags to all tests within a group; tags must start with the @ symbol.

```typescript
import { test, expect } from '@playwright/test';  
  
test.describe('two tagged tests', {  
  tag: '@smoke',  
}, () => {  
  test('one', async ({ page }) => {  
    // ...  
  });  
  
  test('two', async ({ page }) => {  
    // ...  
  });  
});  
```

--------------------------------

### Perform a hover interaction

Source: https://serenity-js.org/api/web/class/Hover

Example showing an actor hovering over an element and verifying the resulting CSS class change.

```typescript
import { actorCalled } from '@serenity-js/core'  
import { Hover, CssClasses } from '@serenity-js/web'  
import { Ensure, equals } from '@serenity-js/assertions'  
  
await actorCalled('Hank')  
  .whoCan(BrowseTheWeb.using(browser))  
  .attemptsTo(  
     Ensure.that(CssClasses.of(Example.link()), equals([ 'off' ])),  
  
    Hover.over(Example.link),  
    Ensure.that(CssClasses.of(Example.link()), equals([ 'on' ])),  
  )  
```

--------------------------------

### Use ARIA role selector with WebdriverIO

Source: https://serenity-js.org/api/web/class/By

Example of using role-based locators within a WebdriverIO test suite.

```typescript
import { actorCalled } from '@serenity-js/core'  
import { Ensure } from '@serenity-js/assertions'  
import { Click, PageElement, By, isVisible } from '@serenity-js/web'  
  
// ... page element definitions as above  
  
describe('ARIA role selector', () => {  
  it('locates an element by its accessible name', async () => {  
    await actorCalled('Nick').attemptsTo(  
      Ensure.that(heading, isVisible()),  
      Click.on(checkbox),  
      Click.on(button),  
    )  
  })  
})
```
Tokens:
Raw