# Serenity BDD

> Serenity BDD is an open-source Java library for writing acceptance and regression tests (web, REST and mobile) that produce rich living-documentation reports. Current release described here: 5.4.1 (the Playwright modules are published up to 5.3.11). Requires Java 17+. Source: https://github.com/serenity-bdd/serenity-core

## Notes for AI coding assistants

Serenity supports several styles. All of them are current and valid; none is preferred or deprecated:

- Page Objects with a step library (`@Steps`), using Selenium or Playwright
- Screenplay, using Selenium, Playwright or REST
- JUnit 5 or Cucumber as the test runner

If the user hasn't said which style to use and the project doesn't show one (check `pom.xml` for `serenity-screenplay*`, `serenity-playwright`, `serenity-cucumber`, and look at existing tests), ask. Don't pick a default. Within a project, stay in one style, one driver and one runner. Don't mix Page Objects and Screenplay in one test.

Packages that are often guessed wrongly (verified against 5.4.1):

- `@Step`, `@Steps`, `@Managed`, `@DefaultUrl`, `@WithTag`: `net.serenitybdd.annotations` (not `net.thucydides.core.annotations`).
- JUnit 5: `@ExtendWith(SerenityJUnit5Extension.class)` from `net.serenitybdd.junit5`. Don't use `@RunWith(SerenityRunner.class)` in a JUnit 5 project.
- Page Objects: `net.serenitybdd.core.pages.PageObject` and `WebElementFacade`. `PageObject.open()` is final: don't redeclare it; use `@DefaultUrl` or `openAt(url)`.
- Screenplay core: `Actor`, `Task`, `Question`, `Performable` in `net.serenitybdd.screenplay`; `OnStage` and `OnlineCast` in `net.serenitybdd.screenplay.actors`; `GivenWhenThen.seeThat` in `net.serenitybdd.screenplay`.
- Screenplay with Selenium (`serenity-screenplay-webdriver`): `BrowseTheWeb` in `net.serenitybdd.screenplay.abilities`; `Open`, `Click`, `Enter`, `Hit` in `net.serenitybdd.screenplay.actions`; `Target` in `net.serenitybdd.screenplay.targets` (`locatedBy` takes a String that is read as XPath if it compiles as XPath, otherwise CSS: `.new-todo` is CSS but `input.new-todo` is read as XPath and finds nothing, so use `located(By.cssSelector(..))` for tag-prefixed CSS); questions such as `Text` and `Value` in `net.serenitybdd.screenplay.questions`. `Text.ofEach(..)` is a `Question<Collection<String>>`. Web `Ensure` is `net.serenitybdd.screenplay.ensure.Ensure` (artifact `serenity-ensure`).
- Screenplay with Playwright (`serenity-screenplay-playwright`): everything is under `net.serenitybdd.screenplay.playwright` (`abilities.BrowseTheWebWithPlaywright`, `actors.PlaywrightCast`, `interactions.*`, `questions.*`, `assertions.Ensure`). Locators are Playwright selector strings. `Text.ofEach(..)` returns `List<String>`.
- Screenplay REST (`serenity-screenplay-rest`): `net.serenitybdd.screenplay.rest.abilities.CallAnApi`, `...rest.interactions.{Get,Post,Ensure}`, `...rest.questions.LastResponse`.
- Playwright Page Objects (`serenity-playwright`): plain classes holding a `com.microsoft.playwright.Page`, registered with `PlaywrightSerenity.registerPage(page)` from `net.serenitybdd.playwright`. They don't extend `PageObject`.
- `ScenarioSteps` (`net.thucydides.core.steps`) and `Pages` (`net.thucydides.core.pages`) are correctly in `net.thucydides`. Many `net.thucydides` packages are current core packages, so don't treat that prefix as a sign of old code.
- Cucumber with JUnit 5: a `@Suite` class with `@IncludeEngines("cucumber")` and the plugin `net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel`.
- Serenity 5.4.1 depends on JUnit 6.1.3 and Cucumber 8.0.4. Don't pin older JUnit or Cucumber versions in the pom: the code compiles but the tests fail at run time with "conflicting versions". Import the JUnit BOM (`org.junit:junit-bom`) to keep all JUnit artifacts aligned.
- Configuration lives in `src/test/resources/serenity.conf`. `serenity.*` and `thucydides.*` keys are synonyms. Use only keys listed in the reference.

Every page below is also available as plain markdown (the same address with `.md` appended, and all of them in one file at https://serenity-bdd.github.io/llms-full.txt). Start with the guide to writing tests, then read the page for the style in use.

- How to write and check Serenity tests with an AI assistant (request, compile, run, can it fail, read the report): https://serenity-bdd.github.io/docs/ai/ai_writing_tests.md
- Using Serenity with AI assistants (AGENTS.md files, agent skill, reviewer agent, what was measured): https://serenity-bdd.github.io/docs/ai/ai_using_assistants.md
- Screenplay (Selenium, Playwright, REST, Cucumber): https://serenity-bdd.github.io/docs/ai/ai_screenplay_idioms.md
- Page Objects (Selenium, Playwright): https://serenity-bdd.github.io/docs/ai/ai_page_object_idioms.md
- REST with SerenityRest and a step library: https://serenity-bdd.github.io/docs/ai/ai_rest_step_library.md
- Cucumber (runner, tags under Maven and Gradle, hooks, shared state, re-running failures, parallel): https://serenity-bdd.github.io/docs/ai/ai_cucumber.md
- Configuration (serenity.conf, properties, environments, reading values; which source wins): https://serenity-bdd.github.io/docs/ai/ai_configuration.md
- Living documentation (how titles, wording and structure become the report): https://serenity-bdd.github.io/docs/ai/ai_living_documentation.md
- Reviewing tests and the report (checklist): https://serenity-bdd.github.io/docs/ai/ai_review_checklist.md
- Upgrading from Serenity 2.x, 3.x or 4.x, and recognising old code (what moved, what to change; tested on real projects): https://serenity-bdd.github.io/docs/ai/ai_upgrading.md
- Reading test results from files, also after a failed build (JSON outcome files, script, JSON summary): https://serenity-bdd.github.io/docs/ai/ai_test_results.md
- Dependencies and configuration: https://serenity-bdd.github.io/docs/ai/ai_project_setup.md
- Troubleshooting by error message (build, report and browser problems, each reproduced and fixed): https://serenity-bdd.github.io/docs/ai/ai_troubleshooting.md

Check that generated code compiles (`mvn test-compile`) before running it. Then run `mvn verify`, check that the test fails when the behaviour is broken, and read the report in `target/site/serenity/index.html`.


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_using_assistants -->

# Using Serenity BDD with AI Coding Assistants

AI coding assistants write Serenity tests quickly, and they most often go wrong by guessing: a package name from an old release, a method that does not exist, or a mix of two ways of working. Everything on this page is there to stop that. All of it describes the current release (Serenity 5.4.1; the Playwright modules are published up to 5.3.11), and every claim in it was checked against the released jars or by running it.

Serenity supports several ways of writing tests, and all of them are current: Page Objects with step libraries, Screenplay, Cucumber (with Screenplay or with page objects), REST with a step library or with Screenplay, with Selenium or Playwright, with JUnit 5 or Cucumber. None is recommended over another. An assistant that has these materials asks which one you want when it cannot tell from the project, instead of choosing for you.

## What is available

| Material | What it is | Where |
|---|---|---|
| Documentation pages | Exact packages, dependencies, idioms and compiling examples for each style, plus configuration, upgrading, living documentation and troubleshooting by symptom | [Idioms and Imports by Style](ai_idioms_overview) |
| Machine-readable results | The JSON outcome files Serenity writes for every test (also after a failed build), a script that summarises a run, and the optional JSON summary report | [Reading Test Results Without the HTML Report](ai_test_results) |
| `llms.txt` and `llms-full.txt` | An index of the documentation for AI assistants (this section first), and the full text of the pages. Every page is also plain markdown at its own address with `.md` appended, for example `https://serenity-bdd.github.io/docs/ai/ai_writing_tests.md` | [llms.txt](https://serenity-bdd.github.io/llms.txt), [llms-full.txt](https://serenity-bdd.github.io/llms-full.txt) |
| `AGENTS.md` files | One per style. They record the style, driver and runner your project uses, so an assistant stays in it | [`docs/ai/agents-md/variants`](https://github.com/serenity-bdd/serenity-core/tree/main/docs/ai/agents-md/variants) in the serenity-core repository |
| An agent skill (Claude Code) | The same material as the pages, loaded when you ask for Serenity tests: it chooses the style (or asks), writes the tests, compiles them, and reviews the report | [`docs/ai/skill/serenity-bdd`](https://github.com/serenity-bdd/serenity-core/tree/main/docs/ai/skill/serenity-bdd) |
| A test-review agent (Claude Code) | A read-only agent that judges the new tests and the report they produce: intent, business wording, grouping | [`docs/ai/skill/agents`](https://github.com/serenity-bdd/serenity-core/tree/main/docs/ai/skill/agents) |

## Installing

**Tell your assistant about the pages.** The simplest step needs no installation: give it the address of [llms.txt](https://serenity-bdd.github.io/llms.txt), or the page for your style, and ask it to compile what it writes (`mvn test-compile`).

**Add an `AGENTS.md`.** Copy the file for your style from the variants folder to the root of your project and name it `AGENTS.md`. The names are:

| File | Style |
|---|---|
| `AGENTS.po-selenium.md`, `AGENTS.po-playwright.md` | Page Objects with a step library (Selenium, Playwright) |
| `AGENTS.sp-selenium.md`, `AGENTS.sp-playwright.md`, `AGENTS.sp-rest.md` | Screenplay (Selenium, Playwright, REST) |
| `AGENTS.cuke-sp.md`, `AGENTS.cuke-pages.md` | Cucumber with Screenplay, Cucumber with page objects |
| `AGENTS.rest-steps.md` | REST with a `SerenityRest` step library |

Assistants that read `AGENTS.md` pick it up automatically. Claude Code reads `CLAUDE.md`, so copy the same file to `CLAUDE.md` as well.

**Install the skill (Claude Code).** Copy the folder `docs/ai/skill/serenity-bdd` from the serenity-core repository to `.claude/skills/serenity-bdd` in your project, or to `~/.claude/skills/serenity-bdd` to have it in every project. To add the reviewer, copy `docs/ai/skill/agents/serenity-test-reviewer.md` to `.claude/agents/` (or `~/.claude/agents/`). The skill loads when you ask for Serenity tests. If your project does not show which style it uses and you did not say, it asks you before writing anything.

## What was measured

Models were given test-writing tasks against a small online bookshop with known, planted defects. A generated test counted as good only if it compiled, passed on the healthy application, and failed when the application had the defect it was meant to catch. Each figure below is for three Claude models, with and without the material.

| Test | Without | With the references |
|---|---|---|
| 14 new tasks, Page Objects and Screenplay, one-shot | 62% | 81% |
| 8 new Playwright tasks, one-shot | 67% | 96% |
| 8 new REST and Cucumber tasks (written after the guidance), one-shot | 36% | 99% |
| Same tasks with tools (the model can run Maven and fix its own errors) | at or near 100% | at or near 100%, with about half as many Maven runs |

So the main gain is in code written in one go, and in fewer retries when the model can run the build. The materials were also scored for how well the generated tests work as living documentation (clear scenario titles in business language, tests grouped by function): the score went from about 70% to about 90%.

These are results from one evaluation, run by the authors of the materials, on Claude models and Claude Code. The full method and results are in the [evaluation write-up](https://github.com/serenity-bdd/serenity-core/blob/main/docs/ai/baseline-results.md) in the serenity-core repository, including what was not tested.

## Known limits

- The pages and the skill are verified against Serenity 5.4.1. Behaviour fixed in later releases is noted where it matters.
- The skill and reviewer agent are for Claude Code. The pages, `llms.txt` and the `AGENTS.md` files are plain text and work with any assistant, but they were only measured with Claude models.
- Mobile testing, Spring and Guice object factories, and cloud grid configuration are not covered.
- If a page here is wrong, or an error message you hit is missing from [troubleshooting](ai_troubleshooting), please open an issue.


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_writing_tests -->

# Writing Serenity BDD Tests with an AI Assistant

This page is a workflow for getting good Serenity tests from an AI coding assistant, and for checking them. It works with any assistant. Where it mentions the agent skill, that is the Claude Code skill described in [Using Serenity BDD with AI Coding Assistants](ai_using_assistants).

The short version: **say which style you want, make the assistant compile and run what it writes, and read the report yourself.** An assistant that has not been told the style will pick one, and a test that compiles and passes can still check the wrong thing.

## 1. Set up once

Do whichever of these you can; each helps on its own.

- Put an `AGENTS.md` for your style in the project root (and a copy named `CLAUDE.md` for Claude Code). It records the style, driver and runner, so every later request stays in them. See [Installing](ai_using_assistants#installing).
- Or install the agent skill, or point the assistant at [llms.txt](https://serenity-bdd.github.io/llms.txt) or at the page for your style under [Idioms and Imports by Style](ai_idioms_overview).
- Make sure the project already builds and has a working Serenity setup ([Project Setup](ai_project_setup)). An assistant extends a working project far better than it creates one from nothing.

## 2. Write the request

A good request names five things. If one is missing, a well-configured assistant asks you; a poorly configured one guesses.

| Say | Why | Example |
|---|---|---|
| The style | Serenity supports several, all current; the assistant must not mix them | "Serenity Screenplay", "Page Objects with a step library", "Cucumber with page objects" |
| The driver | Selenium and Playwright use different packages and assertions | "with Selenium", "with Playwright", "REST only" |
| The runner | JUnit 5 and Cucumber are set up differently | "JUnit 5", "Cucumber on the JUnit Platform" |
| The behaviour, in business terms | The scenario title and step wording become the report | "a reader signs in with a wrong password and sees 'Invalid email or password'" |
| The expected values, exactly | The assertion should check the specific value, not that something is shown | "the total is $80.75", "an order number of the form ORD- followed by digits" |

Also useful: how the application is found (base URL, how to start it), the accounts or test data to use, and anything it must not touch.

If you are not sure which style to choose, say so. The skill and the `AGENTS.md` files are written to make the assistant list the options and ask, not to choose for you.

## 3. Make it compile and run

Ask the assistant to run the build itself and fix what fails:

```
mvn test-compile        # catches wrong package names and methods quickly
mvn verify              # runs the tests and builds the report
```

Add `-Dheadless.mode=true` to run a browser test without opening a window. Compile errors from wrong imports are the most common fault in generated Serenity code, and the second pass fixes them. An assistant that can run Maven usually gets there; one that cannot (a chat window) will often need you to paste back the error.

If the build fails, there is no HTML report, but the result of every test is still in `target/site/serenity/*.json`; ask the assistant to read it (see [Reading Test Results Without the HTML Report](ai_test_results)). Do not stop at "it compiles". A test that passes on the application as it is has proved little until you know it can fail.

## 4. Check that the test can fail

Break the application on purpose, or point the test at a state where the behaviour is wrong, and run it again. If it still passes, it is not checking what you asked for. This is the check the evaluation used: a generated test counted as good only if it passed on the healthy application and failed on the application with the matching defect.

Common causes of a test that cannot fail:

- the assertion is on a page title or heading that is present either way;
- it checks that an element exists, not what it says;
- it asserts the right value against the wrong element;
- it waits with a sleep and checks nothing afterwards.

## 5. Read the report

Open `target/site/serenity/index.html` after `mvn verify`. Read it as someone who has not seen the code:

- Do the scenario titles say what the business behaviour is?
- Do the step names read as a story ("Reader adds 'Clean Code' to the basket"), with no selectors, ids, URLs or status codes?
- Are the tests grouped by function (packages, or `@Narrative` and readme files), so the requirements view has a sensible shape?
- Does each test end with the expectation you asked for?

The [review checklist](ai_review_checklist) has the full list, and [Living Documentation](ai_living_documentation) explains how titles and structure become the report. In Claude Code, the test-review agent applies the same checklist to the new tests and the report.

## 6. Ask for changes, one at a time

When something is wrong, say what you saw in the report and what you want instead ("the step says `Click.on(#add)`; it should say what the reader does"). Keep to one style and one driver as you iterate.

## A worked example

This is a real run, not a mock-up. Claude Opus was asked, through Claude Code with the skill installed, to write a test against a small online bookshop that the authors keep for evaluation. The application has a catalog, a basket and a checkout. The prompt (shortened here) named the style, the driver and the runner, the behaviour, and the exact expected value:

> Using Serenity BDD Screenplay with Selenium and JUnit 5, write a test where a reader signs in, adds The Pragmatic Programmer, checks out as Ada Lovelace at '1 Main St' in Germany with the terms accepted, and checks that the confirmation shows an order number of the form ORD- followed by digits.

It was also given a description of the pages (element ids and labels), as you would give for your own application.

The assistant wrote the test and its tasks, ran `mvn verify -Dheadless.mode=true`, and reported one test, no failures. The test:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class PlaceOrderTest {

    @Managed(driver = "chrome")
    WebDriver browser;

    @BeforeEach
    void setTheStage() {
        OnStage.setTheStage(new OnlineCast());
    }

    @Test
    void readerCanOrderABookAndSeeTheOrderNumber() {
        Actor reader = OnStage.theActorCalled("Reader");

        reader.attemptsTo(
                SignIn.withCredentials("reader@example.com", "correct-horse"),
                AddToBasket.theBook("The Pragmatic Programmer"),
                Checkout.as("Ada Lovelace", "1 Main St", "Germany"),
                WaitUntil.the(CheckoutPage.CONFIRMATION, isVisible()));

        reader.should(seeThat("the order confirmation",
                Text.of(CheckoutPage.CONFIRMATION), matchesPattern(".*\\bORD-\\d+\\b.*")));
    }
}
```

and one of the tasks it created, with the business wording in the step title:

```java
public class AddToBasket {
    public static Performable theBook(String title) {
        return Task.where("{0} adds '" + title + "' to the basket",
                Click.on(CatalogPage.ADD_TO_BASKET_FOR.of(title)));
    }
}
```

**Step 4, can it fail?** The evaluation then ran the same test against a copy of the bookshop in which the confirmation no longer contains an order number. The test failed, with the message `Expected: an element containing 'ORD-' but: ... [Thank you! Order]`. So the assertion does check the order number, and the test was counted as good.

**Step 5, a review.** Things a reader would still want to change: the sign-in task opens a hard-coded `http://localhost:8765/login`, which belongs in `webdriver.base.url` in `serenity.conf` (see [Configuration](ai_configuration)); and the scenario title is a method name, `readerCanOrderABookAndSeeTheOrderNumber`, which the report turns into a readable title, but you may prefer a more specific one. These are the kind of follow-ups to ask for in step 6. Passing the evaluation did not mean there was nothing to improve.

## What to expect

In the evaluation (Claude models, a small test application; full figures on [Using Serenity BDD with AI Coding Assistants](ai_using_assistants#what-was-measured)):

- Written in one go, without the reference pages, a large share of tests failed: usually an import that does not exist, or a method from a different style. With the pages or the skill, most compiled and passed.
- With tools, so the assistant can run Maven and fix its own errors, nearly every test ended up good with or without the materials. What the materials changed was the number of Maven runs, about half.
- Passing is not the same as good: the checks above (can it fail, does the report read well) are still yours to do.

## Common mistakes to watch for

| In the generated code | What it means |
|---|---|
| Imports from `net.serenitybdd.screenplay.*` in a Page Objects project, or `@Steps` in a Screenplay project | Two styles mixed; ask for one |
| `Thread.sleep(...)` | A fixed wait; Serenity waits for elements itself, or use `WaitUntil` (Screenplay) |
| Selectors, ids or URLs in step titles | The report will read as a script, not a story |
| A selector like `$("button")` or `Target.the("x").locatedBy("input.x")` | A string that starts with a tag name is read as XPath, not CSS, so the element is not found at run time. Use `#id`, `.class` or `By.cssSelector(...)`; see [Page Objects](ai_page_object_idioms) and [Screenplay](ai_screenplay_idioms) |
| A numeric REST assertion like `equalTo(90.0)` that fails | REST-assured returns JSON decimals as `Float`; see [REST](ai_rest_step_library) |
| `@Managed WebDriver` in a step library or other helper class | It is filled in only in the test class, so the field is null elsewhere; extend `UIInteractionSteps` and use `getDriver()`, or use a page object. See [Troubleshooting](ai_troubleshooting) |
| A Cucumber step that is undefined or shown as pending | The step definition does not match the step text, and an undefined step fails the build; check the Cucumber expression. See [Cucumber](ai_cucumber) |
| An import such as `net.thucydides.core.annotations.Step` that does not compile | The annotations moved to `net.serenitybdd.annotations`; see [Upgrading](ai_upgrading). Many other `net.thucydides` packages are still current core packages, so judge each import against the pages |

The [troubleshooting page](ai_troubleshooting) lists build, report and browser errors by the message you see, with a fix that was reproduced.


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_idioms_overview -->

# Idioms and Imports by Style

These pages list the exact packages, dependencies and idioms for each supported way of writing tests with Serenity BDD, with compiling examples. They are written for people and for AI coding assistants, which most often go wrong by guessing a package name.

Serenity supports several styles. All of them are current and valid:

| Approach | Drivers | Page |
|---|---|---|
| Page Objects with a step library | Selenium, Playwright | [Page Objects: Imports and Idioms](ai_page_object_idioms) |
| Screenplay | Selenium, Playwright, REST | [Screenplay: Imports and Idioms](ai_screenplay_idioms) |
| Cucumber with Screenplay | Selenium | [Screenplay: Imports and Idioms](ai_screenplay_idioms) |
| Cucumber with page objects and a step library | Selenium | [Cucumber](ai_cucumber) |
| REST with a step library (no Screenplay) | REST-assured via SerenityRest | [REST with SerenityRest and a Step Library](ai_rest_step_library) |

Use JUnit 5 as the runner for all of them. Dependencies, the report plugin and `serenity.conf` are on [Project Setup](ai_project_setup).

## Choosing a style

Pick the style the project already uses, and stay in it: one approach, one driver and one runner per project, and don't mix Page Objects and Screenplay in one test. To see which a project uses, look at `pom.xml` (`serenity-screenplay*`, `serenity-playwright`, `serenity-cucumber`) and the existing tests. For a new project, choose by what suits the team. None of the styles is deprecated.

## If you use an AI coding assistant

See [Using Serenity BDD with AI Coding Assistants](ai_using_assistants) and [Writing Serenity BDD Tests with an AI Assistant](ai_writing_tests) for the `AGENTS.md` files, the agent skill and `llms.txt`. In short: tell it which style, driver and runner you want, or point it at these pages (or at [llms.txt](https://serenity-bdd.github.io/llms.txt)). Ask it to compile its output (`mvn test-compile`) before running it. Many `net.thucydides` packages are current core packages, so that prefix on its own is not a sign of outdated code: judge each class against these pages.


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_living_documentation -->

# Living Documentation: Intent, Wording and Structure

Verified against Serenity **5.4.1**. The behaviour described here was run against the example at the end of the page.

## The idea

A Serenity report is read by people who will never open the code: product owners, analysts, new team members, auditors. Its Requirements tab is a description of what the application does, built from the tests. So every scenario has two jobs: check the application, and tell a reader **what the business expects and why it matters**. A test that only passes is half done.

Write for that reader:

- The **scenario title** says the business rule or outcome, as a sentence a user would recognise.
- The **steps** read as a story in business language: who does what, in what situation, and what they should see.
- The **tests are grouped by what the application does** (ordering, searching, signing in), so the report is a navigable table of contents.

## 1. Scenario titles: the rule, not the mechanics

| Poor | Good |
|---|---|
| `testCheckout1` | `A reader sees an order number after paying` |
| `loginTest` | `Signing in with a wrong password is refused with a clear message` |
| `shouldReturn201` | `Placing an order confirms it with an order number` |
| `searchTest` | `Searching by title finds only matching books` |

- **JUnit 5:** use `@DisplayName("...")` on the method; the report title is exactly that (verified). Without it, Serenity turns the method name into words (`shouldKeepEveryBookAddedToTheBasket` becomes "Should keep every book added to the basket"), so a method name written as a sentence is also fine. A `test` prefix or a number is not.
- **Cucumber:** the `Scenario:` name is the title; write it as a sentence. Say the rule being shown, not the clicks.
- Name what the user gets or what the rule is. Avoid HTTP codes, element ids, class names and the word "test" in titles.

## 2. Steps: business language, one level above the mechanics

The report lists the steps of each scenario. Make them read like the scenario narrated.

- **Screenplay:** give every `Task` a sentence with `{0}` for the actor, and put the important data in it (verified):

  ```java
  Task.where("{0} adds '" + title + "' to the basket", ...)
  // report: Ada adds 'Refactoring' to the basket
  ```

  Tasks are business actions (`SignIn.withCredentials`, `Checkout.as`). Interactions (`Click`, `Enter`) stay inside tasks, so the report shows the business level first. Questions and `seeThat` checks read as expectations: `seeThat("the order confirmation", TheConfirmation.text(), containsString("ORD-"))`.
- **Page Objects:** annotate step-library methods with `@Step("Search the catalog for '{0}'")` (verified; `{0}` is the first parameter). Put the business verb in the step method (`shopper.searchesFor(term)`), not in the test (`driver.findElement(..)`).
- **Cucumber:** the Gherkin is the documentation. Use Given/When/Then for context, action, outcome. Keep each step about the business ("When Ada places the order"), not the UI ("When I click the button with id place-order"). Use a `Background` for context shared by all scenarios, and a `Scenario Outline` with an `Examples` table for the same rule over several values, with a meaningful column per input.
- Do not put CSS selectors, XPath, URLs, element ids, sleeps or HTTP status codes in step text. They belong inside the page object, task or step definition.
- Serenity writes the lines under a task itself: `Open.url(..)` shows as "opens the browser at http://..." and `Enter`/`Click` show the element names. You can't remove them, so keep URLs in one place and give `Target`s business names (`Target.the("email field")`). The task line above them is what the reader reads first.
- The last step of a scenario states the business expectation ("the confirmation shows an order number"), not a technical detail.

## 3. Organise by function

The report's Requirements tab is a tree. Serenity builds it from how you organise the tests:

| Style | How the tree is built | Verified result |
|---|---|---|
| JUnit 5 (any style), no annotations | the **package** path of the test class | `shop.ordering.WhenAReaderBuildsABasketTest` gives `Shop (capability)` > `Ordering (feature)` > `When a reader builds a basket test (feature)` |
| JUnit 5, annotations (recent releases; see the "Annotation-Based Requirements" docs page) | `@Epic` > `@Feature` > `@Story` on the test class | `@Epic("Buying books") @Feature("Paying for an order") @Story("Pay by card")` gives `Buying books (capability)` > `Paying for an order (feature)` > `Pay by card (story)` |
| Cucumber | the **folders** under `src/test/resources/features`, and the feature file | `features/shopping/basket.feature` gives `Shopping (capability)` > `Shopping basket (feature)` |

Rules that follow:

1. **Group by capability, then feature.** For example `ordering`, `browsing`, `accounts` as packages (or folders), with one test class (or feature file) per feature inside, each holding the scenarios of that feature. Not one class called `ShopTest` with everything in it, and not one package per technical layer.
2. **Prefer one way for the whole project.** If package-based and annotated classes are mixed, the Requirements page shows both as separate top-level trees side by side (verified), and each class is found in only one of them, so the project reads as two organisations. Follow what is already there.
3. **Class names end up in the tree.** With packages, the class name becomes the feature name, `Test` suffix included (`WhenSearchingTheCatalogTest` is shown as "When searching the catalog test", seen in a real report). Put `@DisplayName("Searching the catalog")` on the class: the feature then shows that text (verified). With annotations, the `@Feature` and `@Story` text is what the reader sees. Write these as business phrases.
4. **Cucumber:** one feature file per feature, in a folder per capability; the text under `Feature:` (a paragraph of business context before the first scenario) is shown on the feature page (verified).

## 4. Descriptions of the areas

- **Cucumber:** a `readme.md` in a features folder is the description of that capability. Its first line should be the name (`## Shopping`). Verified: it appears in the report.
- **JUnit 5:** put `readme.md` files under `src/test/resources/stories/<package path>/` (for the example `src/test/resources/stories/shop/ordering/readme.md`); the text appears in the report. The same file in `src/test/resources/shop/ordering/` was **ignored** (verified).
- **`@Narrative(text = {...})` did not appear in the JUnit 5 report** in 5.4.1 (verified, both on the class and in `package-info.java`). Don't rely on it; use the `readme.md` files.

Keep a description to a few sentences: what the area is for, and the rules that matter.

## 5. What a good scenario looks like

The shape only: `SignIn`, `Checkout`, `shopper` and the rest are the project's own classes.

Page Objects + step library:

```java
@Test
@DisplayName("Searching by title finds only matching books")
void searchingByTitle() {
    shopper.searchesFor("Refactoring");
    shopper.shouldSeeOnlyBooksCalled("Refactoring");
}
```

Screenplay:

```java
@Test
@DisplayName("A reader sees an order number after paying")
void orderNumber() {
    ada.attemptsTo(
        SignIn.withCredentials(reader),
        AddToBasket.theBook("The Pragmatic Programmer"),
        Checkout.as("Ada Lovelace").inCountry("Germany"));
    ada.should(seeThat("the order confirmation", TheConfirmation.text(), matchesPattern("Thank you! Order ORD-\\d+")));
}
```

Cucumber:

```gherkin
Feature: Placing an order

  Readers pay for the books in their basket and get an order number back.

  Scenario: A reader sees an order number after paying
    Given Ada has "The Pragmatic Programmer" in her basket
    When she checks out and accepts the terms
    Then she sees an order number like ORD-1001
```

## 6. Checking it

After the tests run, the report is what the reader sees. Run `scripts/outline.py <project>/target/site/serenity` (from the skill directory): it prints the requirements tree, the scenario titles and the steps of each scenario, and flags the mechanical problems (titles that look like method names, selectors or ids in step text, ungrouped tests). Read its output as the reader would: could someone who has never seen the code say what the application does? The `serenity-test-reviewer` agent does this check and the judgement part (`review-checklist.md`).

## 7. Not covered

Pending and manual scenarios, tags and `@WithTag`, Serenity's custom requirement types (`serenity.requirement.types`), the Jira requirements provider, `@Title`, and the exact look of the HTML report.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).

### `scripts/outline.py`

```python
#!/usr/bin/env python3
"""Print the living documentation of a Serenity run the way a reader sees it, and flag mechanical problems.

usage: outline.py <serenity report dir> [--json]
  (the directory is normally <project>/target/site/serenity; only the *.json outcome files are read)

Prints: the requirements path of each test, its title, and its steps. Then a list of FLAGS for things a reader
would trip on. The flags are objective checks; whether the wording is good is for the reviewer to judge.
"""
import glob, json, os, re, sys

SELECTOR = re.compile(r"(#[\w-]+|\.[a-z][\w-]+\b.*[>\[]|//\w|\[@|By\.\w+|css=|xpath|data-testid|getByRole|\bid=)", re.I)
URL = re.compile(r"https?://|localhost|:\d{4}\b")
HTTP = re.compile(r"\b(?:status(?: code)?|HTTP)\s*[:=]?\s*[1-5]\d\d\b|\b(?:200|201|204|400|401|403|404|422|500)\b")
PLUMBING = re.compile(r"\b(sleep|wait(?:s)? \d|findElement|executeScript|sendKeys|driver\.|click(?:s)? (?:on )?(?:the )?(?:element|button with|link with)|locator)\b", re.I)


def load(d):
    rows = []
    for f in sorted(glob.glob(os.path.join(d, "*.json"))):
        try:
            j = json.load(open(f))
        except ValueError:
            continue
        if not isinstance(j, dict) or "userStory" not in j:
            continue
        steps = []

        def walk(nodes, depth):
            for s in nodes or []:
                steps.append((depth, s.get("description", "")))
                walk(s.get("children"), depth + 1)
        walk(j.get("testSteps"), 0)
        us = j.get("userStory", {})
        rows.append(dict(path=us.get("path", ""), story=us.get("storyName", ""), title=j.get("title") or j.get("name", ""),
                         result=j.get("result", ""), steps=steps, description=j.get("description") or ""))
    return rows


def flags(rows):
    out = []
    if not rows:
        return ["no outcome files found: run the tests first"]
    paths = {r["path"] for r in rows}
    stories = {r["story"] for r in rows}
    if len(rows) >= 4 and len(stories) == 1:
        out.append("all %d scenarios are in one group (%s): split them by feature" % (len(rows), next(iter(stories))))
    depths = {len(re.split(r"[/.]", p)) for p in paths if p}
    if len(rows) >= 6 and max(depths or {0}) < 2:
        out.append("no functional hierarchy: use packages/folders or @Epic/@Feature/@Story to group the scenarios")
    seen = {}
    for r in rows:
        seen.setdefault(r["title"].lower(), []).append(r["path"])
    for t, ps in seen.items():
        if len(ps) > 1:
            out.append("duplicate scenario title '%s' (%d times)" % (t, len(ps)))
    for st in sorted(stories):
        if re.search(r"[a-z]Test$|Tests$|^Test[A-Z]", st or ""):
            out.append("feature '%s' shows with its class name (\"%s\"): put @DisplayName with a business phrase on the class" % (st, re.sub(r"(?<!^)(?=[A-Z])", " ", st).lower()))
    for r in rows:
        t = r["title"]
        where = "%s: " % t
        if re.search(r"\d$", t) or re.match(r"test\b", t, re.I) or t.endswith("()") or "_" in t or " " not in t.strip():
            out.append(where + "title looks like a method name")
        if len(t.split()) < 3:
            out.append(where + "title is too short to state a rule or outcome")
        if SELECTOR.search(t) or HTTP.search(t) or URL.search(t):
            out.append(where + "title contains technical detail (selector, URL or status code)")
        if not r["steps"]:
            out.append(where + "no steps recorded (nothing for a reader to follow)")
        for _, d in r["steps"]:
            if SELECTOR.search(d):
                out.append(where + "step shows a selector or element id: '%s'" % d[:80])
            elif URL.search(d):
                out.append(where + "step shows a URL: '%s'" % d[:80])
            elif PLUMBING.search(d):
                out.append(where + "step is plumbing, not business language: '%s'" % d[:80])
            elif HTTP.search(d) and not re.search(r"\border\b|\bORD-", d, re.I):
                out.append(where + "step mentions an HTTP status: '%s'" % d[:80])
            elif re.match(r"^(click|type|enter|select|open|navigate)\w* ", d, re.I) and not re.search(r"\{|\b(she|he|they|\w+ (?:clicks|types|enters|opens))\b", d, re.I):
                out.append(where + "step is a bare UI action without an actor: '%s'" % d[:80])
    return sorted(set(out))


def main():
    if len(sys.argv) < 2:
        sys.exit(__doc__)
    rows = load(sys.argv[1])
    fl = flags(rows)
    if "--json" in sys.argv:
        print(json.dumps(dict(scenarios=rows, flags=fl), indent=1))
        return
    tree = {}
    for r in sorted(rows, key=lambda r: (r["path"], r["title"])):
        tree.setdefault(r["path"], []).append(r)
    for path, rs in tree.items():
        print(path.replace("/", " > ") or "(no group)")
        for r in rs:
            print("  - %s  [%s]" % (r["title"], r["result"]))
            for depth, d in r["steps"]:
                print("      %s%s" % ("  " * depth, d))
    print("\nFLAGS (%d)" % len(fl))
    for f in fl:
        print("  ! " + f)
    sys.exit(1 if fl else 0)


if __name__ == "__main__":
    main()
```

### `living-docs/shop/browsing/WhenSearchingTheCatalogTest.java`

```java
package shop.browsing;

import net.serenitybdd.annotations.Step;
import net.serenitybdd.annotations.Steps;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Searching the catalog")
class WhenSearchingTheCatalogTest {

    @Steps
    ShopperSteps shopper;

    @Test
    void searchingByTitleFindsTheMatchingBook() {
        shopper.searchesFor("Refactoring");
        shopper.shouldSeeBooks(1);
    }

    public static class ShopperSteps {
        private int found;

        @Step("Search the catalog for '{0}'")
        public void searchesFor(String term) { found = "Refactoring".equals(term) ? 1 : 0; }

        @Step("The catalog lists {0} book(s)")
        public void shouldSeeBooks(int expected) { assertThat(found).isEqualTo(expected); }
    }
}
```

### `living-docs/shop/ordering/AddToBasket.java`

```java
package shop.ordering;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Performable;
import net.serenitybdd.screenplay.Task;

public class AddToBasket {
    public static Performable theBook(String title) {
        return Task.where("{0} adds '" + title + "' to the basket",
                actor -> actor.<Basket>recall("basket").add(title));
    }
}
```

### `living-docs/shop/ordering/Basket.java`

```java
package shop.ordering;

import java.util.ArrayList;
import java.util.List;

/** A tiny in-memory basket so the example needs no browser or server. */
public class Basket {
    private final List<String> titles = new ArrayList<>();
    public void add(String title) { titles.add(title); }
    public int size() { return titles.size(); }
    public boolean isEmpty() { return titles.isEmpty(); }
}
```

### `living-docs/shop/ordering/WhenAReaderBuildsABasketTest.java`

```java
package shop.ordering;

import net.serenitybdd.annotations.Narrative;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.actors.OnlineCast;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import static net.serenitybdd.screenplay.GivenWhenThen.seeThat;
import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Building a basket")
@Narrative(text = {"As a reader", "I want to collect books in a basket", "So that I can buy them together"})
class WhenAReaderBuildsABasketTest {

    @BeforeEach
    void setTheStage() {
        OnStage.setTheStage(new OnlineCast());
    }

    @Test
    @DisplayName("A reader can add a book to an empty basket")
    void aReaderCanAddABookToAnEmptyBasket() {
        Actor ada = OnStage.theActorCalled("Ada");
        ada.remember("basket", new Basket());

        ada.attemptsTo(AddToBasket.theBook("The Pragmatic Programmer"));

        assertThat(ada.<Basket>recall("basket").size()).isEqualTo(1);
    }

    @Test
    void shouldKeepEveryBookAddedToTheBasket() {
        Actor ada = OnStage.theActorCalled("Ada");
        ada.remember("basket", new Basket());

        ada.attemptsTo(AddToBasket.theBook("Refactoring"), AddToBasket.theBook("Fluent Python"));

        assertThat(ada.<Basket>recall("basket").size()).isEqualTo(2);
    }
}
```

### `living-docs-annotated/shop/annotated/WhenPayingForAnOrderTest.java`

```java
package shop.annotated;

import net.serenitybdd.annotations.Epic;
import net.serenitybdd.annotations.Feature;
import net.serenitybdd.annotations.Story;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
@Epic("Buying books")
@Feature("Paying for an order")
@Story("Pay by card")
class WhenPayingForAnOrderTest {
    @Test
    void aReaderCanPayByCard() { }
}
```


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_screenplay_idioms -->

# Screenplay: Imports and Idioms

Verified against Serenity **5.4.1** (Playwright modules: **5.3.11**, the latest published). The examples at the end of this page compile and their tests pass.

Screenplay works with Selenium, Playwright and REST, with JUnit 5 or Cucumber. All of these are valid. Pick the one the user asked for or the project already uses, and don't mix them in one project.

## 1. Where things live

The packages are not guessable. Guessing them is the most common cause of compile errors.

### Core (all Screenplay projects), artifact `serenity-screenplay`
| Class | Package |
|---|---|
| `Actor`, `Task`, `Performable`, `Question`, `Interaction`, `Ability`, `Consequence`, `Tasks`, `RememberThat` | `net.serenitybdd.screenplay` |
| `GivenWhenThen` (`seeThat`) | `net.serenitybdd.screenplay` (use as a static import) |
| `OnStage`, `OnlineCast`, `Cast`, `Stage` | `net.serenitybdd.screenplay.actors` |
| `CastMember` | `net.serenitybdd.screenplay.annotations` |
| `Check` (conditional tasks) | `net.serenitybdd.screenplay.conditions` |
| `Wait`, `WaitUntil` | `net.serenitybdd.screenplay.waits` |

### Selenium, artifact `serenity-screenplay-webdriver`
| Class | Package |
|---|---|
| `BrowseTheWeb` | `net.serenitybdd.screenplay.abilities` |
| `Open`, `Click`, `Enter`, `Hit`, `Clear`, `Hover`, `Scroll`, `SelectFromOptions` | `net.serenitybdd.screenplay.actions` |
| `Target` | `net.serenitybdd.screenplay.targets`. `Target.the("name").locatedBy("..")` takes a **String**. Serenity treats the string as XPath if it compiles as an XPath expression, otherwise as CSS. So `.new-todo`, `#id`, `[data-test=x]` and `li label` are CSS, but a tag-prefixed selector such as `input.new-todo`, `button` or `h1` is read as XPath and finds nothing. For those use `Target.the("name").located(By.cssSelector("input.new-todo"))` (or a leading `.`/`#`, or an explicit `//input[...]`). |
| `Text`, `TextContent`, `Value`, `Attribute`, `Visibility`, `Presence`, `Enabled`, `Disabled`, `SelectedValue`, `CurrentVisibility`, `WebElementQuestion` | `net.serenitybdd.screenplay.questions` |

`Ensure` for web is in artifact `serenity-ensure`: **`net.serenitybdd.screenplay.ensure.Ensure`**.

### Playwright, artifact `serenity-screenplay-playwright`
Everything lives under `net.serenitybdd.screenplay.playwright`:

| Class | Package |
|---|---|
| `BrowseTheWebWithPlaywright` | `...playwright.abilities` |
| `PlaywrightCast` (use instead of `OnlineCast`) | `...playwright.actors` |
| `Open`, `Click`, `Enter`, `Press`, `Navigate`, `Check`, `Hover`, `WaitFor` ... | `...playwright.interactions` |
| `Text`, `Visibility`, `Count`, `Attribute` ... | `...playwright.questions` |
| `Ensure` | `...playwright.assertions` |
| `Target` | `...playwright.Target` |

Playwright locators are plain Playwright selector strings (`".new-todo"`, `"text='Delete'"`) or a Playwright `Target`.

Playwright classes that exist (all take a selector string or a `Target`):

| Kind | Classes and entry points |
|---|---|
| Interactions (`...playwright.interactions`) | `Open.url(..)`, `Navigate`, `Click.on(..)`, `DoubleClick`, `RightClick`, `Hover.over(..)`, `Enter.theValue(..).into(..)`, `Press.keys("Enter")`, `Clear`, `Focus`, `Check.the(..)`, `Uncheck.checkbox(..)`, `SelectFromOptions.byVisibleText(..)` / `.byValue(..)` / `.byIndex(..)` then `.from(selector)`, `Upload`, `Drag`, `ScrollIntoView`, `WaitFor.selector(..)` |
| Questions (`...playwright.questions`) | `Text.of(..)`, `Text.ofEach(..)` (`List<String>`), `Value.of(..)`, `SelectedOptionText.of(..)`, `Checked.of(..)`, `Visibility.of(..)`, `Presence`, `Absence`, `Count.of(..)`, `Attribute`, `Enabled`, `Disabled`, `AllOptionTexts` |
| Assertions (`...playwright.assertions.Ensure`) | `Ensure.that(selector).isVisible() / isHidden() / hasText(..) / containsText(..) / hasValue(..) / isChecked() / hasCount(n) / hasAttribute(n, v)` |

**Don't use `Ensure.thatTheCurrentUrl()` or `Ensure.thatThePageTitle()`: they return package-private classes, and any call on them fails to compile** ("UrlEnsure.contains(java.lang.String) is defined in an inaccessible class or interface"; run in the verification script in the serenity-core repository (`docs/ai/skill`)). To check the URL, assert on the page: `assertThat(BrowseTheWebWithPlaywright.as(actor).getCurrentPage().url()).contains("/catalog")` (after `attemptsTo(..)`, in the test body), or better, check something the user sees on the new page (`Ensure.that("h1").hasText("Catalog")`).

**A selector must match exactly one element** for `WaitFor.selector`, `Click.on`, `Enter`, `Ensure.that(..).hasText(..)` and `Text.of(..)` (Playwright's strict mode). A selector that matches a list (`"#books .book"` with five rows) fails at run time with `strict mode violation: ... resolved to 5 elements`. For a list: wait on the first row (`"#books .book >> nth=0"`), count with `Ensure.that("#books .book").hasCount(5)`, read all texts with `Text.ofEach(..)`, pick one with `">> nth=0"` or `">> nth=-1"` (last), or narrow with `has-text`/`text-is` (`"tr.book:has(td.title:text-is('Refactoring'))"`). `sp-playwright/todo/ListTest.java` runs these.

**Don't build a Playwright text pattern with `Pattern.quote(..)`.** Playwright sends the pattern to the browser's JavaScript engine, which doesn't understand Java's `\Q..\E`, so `setHasText(Pattern.compile("^\\s*" + Pattern.quote(title) + "\\s*$"))` matches nothing and the step times out after 30 seconds (two Opus runs). Use the plain string (`setHasText(title)` matches by substring, ignoring case; `text-is('..')` / `has-text('..')` in a selector string match exactly or by substring), or write the pattern by hand (`Pattern.compile("^\\s*Clean Code\\s*$")`). Run in the verification script in the serenity-core repository (`docs/ai/skill`).

In a Playwright selector string a role needs the prefix: `"role=heading[name=\"Sign in\"]"`; without `role=` it throws `InvalidSelectorError` (run in the verification script in the serenity-core repository (`docs/ai/skill`)).

Playwright has no `net.serenitybdd.screenplay.ensure.Ensure` and no `Target` from `net.serenitybdd.screenplay.targets`: use the Playwright ones. See `sp-playwright/todo/FormTest.java`.

### REST, artifact `serenity-screenplay-rest`
| Class | Package |
|---|---|
| `CallAnApi` | `net.serenitybdd.screenplay.rest.abilities` |
| `Get`, `Post`, `Delete`, `Ensure` ... | `net.serenitybdd.screenplay.rest.interactions` |
| `LastResponse`, `TheResponse` | `net.serenitybdd.screenplay.rest.questions` |

### Shared across all styles
| Class | Package |
|---|---|
| `@Managed`, `@Step`, `@Steps`, `@DefaultUrl`, `@WithTag` ... | `net.serenitybdd.annotations` (never `net.thucydides.core.annotations`) |
| `SerenityJUnit5Extension` | `net.serenitybdd.junit5` |
| `ScenarioSteps` (Page Objects) | `net.thucydides.core.steps` (**this one is correct** under `net.thucydides`) |

## 2. Common mistakes

| Wrong | Right |
|---|---|
| `import net.serenitybdd.rest.abilities.*` or `net.serenitybdd.rest.questions.*` for Screenplay REST (those packages don't exist) | `net.serenitybdd.screenplay.rest.abilities.CallAnApi`, `...rest.questions.LastResponse` |
| `Target.the("x").locatedBy(By.id("x"))` | `locatedBy("#x")`, a String; for a `By` use `located(By.id("x"))` |
| `locatedBy("input.new-todo")` (tag-prefixed CSS; read as XPath, element not found at run time) | `located(By.cssSelector("input.new-todo"))` or `locatedBy(".new-todo")` | run-time failure, 5 of 66 unguided agentic runs |
| Two `public` classes in one file, or a class name different from its file name | One public class per file, and the file name equals the class name |
| `import net.serenitybdd.screenplay.webdriver.BrowseTheWeb` (package doesn't exist) | `net.serenitybdd.screenplay.abilities.BrowseTheWeb` |
| `Question<List<String>>` returned from `Text.ofEach(target)` (Selenium) | `Question<Collection<String>>`. Playwright's `Text.ofEach` returns `List<String>` |
| `.viewedBy(actor)` on `Text`/`Value`/`Visibility`... | `actor.asksFor(Text.of(target))` or `Text.of(target).answeredBy(actor)`. `.viewedBy` is the old API |
| `net.thucydides.core.annotations.DefaultUrl` (and `Step`, `Managed`) | `net.serenitybdd.annotations.*` |
| JUnit 4 `@RunWith(SerenityRunner.class)` in a JUnit 5 project | `@ExtendWith(SerenityJUnit5Extension.class)` |
| Moving `ScenarioSteps` to `net.serenitybdd...` | `net.thucydides.core.steps.ScenarioSteps` |
| `OnlineCast` in the wrong package | `net.serenitybdd.screenplay.actors.OnlineCast` |
| `@Page` annotation | Doesn't exist. In Page Object tests use `@Steps` for step libraries and extend `PageObject` for pages |
| `Instrumented` as a class | `Tasks.instrumented(MyTask.class, args)` (static method), or prefer `Task.where(..)` |
| `Ensure.thatTheCurrentUrl().contains(..)` or `Ensure.thatThePageTitle()` (Playwright) | Doesn't compile (package-private return types). Assert on `BrowseTheWebWithPlaywright.as(actor).getCurrentPage().url()` or on visible page content | 6 of the 8 guided Playwright compile failures inspected |
| `WaitFor.selector("#books .book")` or `Ensure.that("#books .book").hasText(..)` where the selector matches several rows | `"#books .book >> nth=0"`, or `hasCount(n)`, or `Text.ofEach(..)` | strict mode violation at run time, 2 guided runs |
| `Navigate` from a Selenium package | Selenium: `Open.url(..)`. `Navigate` exists only in Playwright |

## 3. Minimal working patterns

The source files are under `` and are compile-checked. Names are the same across styles so you can compare them.

| Style | Files | Key points |
|---|---|---|
| Screenplay + Selenium + JUnit 5 | `sp-selenium/todo/*` | `@ExtendWith(SerenityJUnit5Extension.class)`, `@Managed(driver="chrome") WebDriver`, `OnStage.setTheStage(new OnlineCast())`, `OnStage.theActorCalled("Toby")`, `Task.where(..)`, `Target.the(..).locatedBy(..)`, `seeThat(question, matcher)` or `Ensure.that(..)` |
| Screenplay + Playwright + JUnit 5 | `sp-playwright/todo/*` (todo list, form with select and checkbox) | `new PlaywrightCast()`, string selectors, `Press.keys("Enter")`, `Ensure.that(selector).hasText(..)` |
| Screenplay + REST + JUnit 5 | `sp-rest/api/*` | `Actor.named(..).whoCan(CallAnApi.at(baseUrl))`, `Get.resource(..)`, `Post.to(..).with(request -> ...)`, `LastResponse.received()` |
| Cucumber + Screenplay | `cuke-sp/*` | `@Suite` + `@IncludeEngines("cucumber")` + `@SelectClasspathResource("features")`, plugin `net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel`, a `{actor}` `@ParameterType`, `@Before` that sets the stage |

### Rules of thumb
- Use `Task.where("{0} does something", step1, step2)` for tasks. Use a class with `performAs` only when the task needs real logic.
- `actor.attemptsTo(..)` for actions. `actor.should(seeThat(..))` or `Ensure` for checks.
- Keep locators in a `Target` holder class (Selenium) or constants (Playwright).
- Build tasks and questions with a static factory (`AddATodo.called("Buy milk")`) so the test reads like a sentence.

## 4. Not yet verified
- `Ensure` for web has several overloads. Only `that(Target).hasText(..)` is compile-tested.
- Page Objects (Selenium and Playwright) are covered in `page-objects.md`, not here.
- The examples were run once against the live sample sites with Serenity 5.4.1 (Playwright modules 5.3.11). Other sites and larger suites may behave differently.
- `serenity-screenplay-playwright` is documented at 5.3.11, not 5.4.x.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).

### `sp-selenium/todo/AddATodo.java`

```java
package todo;

import net.serenitybdd.screenplay.Performable;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.actions.Enter;
import org.openqa.selenium.Keys;

public class AddATodo {
    public static Performable called(String item) {
        return Task.where("{0} adds a todo called " + item,
                Enter.theValue(item).into(TodoList.NEW_TODO).thenHit(Keys.ENTER));
    }
}
```

### `sp-selenium/todo/AddTodoTest.java`

```java
package todo;

import net.serenitybdd.annotations.Managed;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.actions.Open;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.actors.OnlineCast;
import net.serenitybdd.screenplay.ensure.Ensure;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.WebDriver;

import static net.serenitybdd.screenplay.GivenWhenThen.seeThat;
import static org.hamcrest.Matchers.hasItem;

@ExtendWith(SerenityJUnit5Extension.class)
class AddTodoTest {

    @Managed(driver = "chrome")
    WebDriver browser;

    @BeforeEach
    void setTheStage() {
        OnStage.setTheStage(new OnlineCast());
    }

    @Test
    void shouldShowTheNewTodo() {
        var toby = OnStage.theActorCalled("Toby");
        toby.attemptsTo(
                Open.url("https://todo-app.serenity-js.org"),
                AddATodo.called("Buy milk"));
        toby.should(seeThat(TheTodos.displayed(), hasItem("Buy milk")));
    }

    @Test
    void shouldShowTheNewTodoUsingEnsure() {
        var toby = OnStage.theActorCalled("Toby");
        toby.attemptsTo(
                Open.url("https://todo-app.serenity-js.org"),
                AddATodo.called("Buy milk"),
                Ensure.that(TodoList.ITEMS).hasText("Buy milk"));
    }
}
```

### `sp-selenium/todo/TheTodos.java`

```java
package todo;

import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.questions.Text;

import java.util.Collection;

public class TheTodos {
    // Text.ofEach(..) is a Question<Collection<String>> - not List<String>
    public static Question<Collection<String>> displayed() {
        return Text.ofEach(TodoList.ITEMS);
    }
}
```

### `sp-selenium/todo/TodoList.java`

```java
package todo;

import net.serenitybdd.screenplay.targets.Target;
import org.openqa.selenium.By;

public class TodoList {
    // locatedBy(String) treats a string as XPath whenever it compiles as one, so a CSS selector such as
    // "input.new-todo" (a valid XPath name) is NOT found. Use located(By.cssSelector(..)) for those.
    public static final Target NEW_TODO = Target.the("new todo field").located(By.cssSelector("input.new-todo"));
    public static final Target ITEMS = Target.the("todo items").locatedBy(".todo-list li label");
}
```

### `sp-playwright/todo/AddTodoTest.java`

```java
package todo;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.Performable;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.playwright.actors.PlaywrightCast;
import net.serenitybdd.screenplay.playwright.assertions.Ensure;
import net.serenitybdd.screenplay.playwright.interactions.Enter;
import net.serenitybdd.screenplay.playwright.interactions.Open;
import net.serenitybdd.screenplay.playwright.interactions.Press;
import net.serenitybdd.screenplay.playwright.questions.Text;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import static net.serenitybdd.screenplay.GivenWhenThen.seeThat;
import static org.hamcrest.Matchers.hasItem;

@ExtendWith(SerenityJUnit5Extension.class)
class AddTodoTest {

    static final String NEW_TODO = ".new-todo";
    static final String ITEMS = ".todo-list li label";

    static Performable addATodo(String item) {
        return Task.where("{0} adds a todo called " + item,
                Enter.theValue(item).into(NEW_TODO),
                Press.keys("Enter"));
    }

    @BeforeEach
    void setTheStage() {
        OnStage.setTheStage(new PlaywrightCast());
    }

    @Test
    void shouldShowTheNewTodo() {
        var toby = OnStage.theActorCalled("Toby");
        toby.attemptsTo(
                Open.url("https://todo-app.serenity-js.org"),
                addATodo("Buy milk"),
                Ensure.that(ITEMS).hasText("Buy milk"));
        // Playwright's Text.ofEach(..) is a Question<List<String>> (Selenium's is Collection<String>)
        toby.should(seeThat(Text.ofEach(ITEMS), hasItem("Buy milk")));
    }
}
```

### `sp-playwright/todo/FormTest.java`

```java
package todo;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.playwright.actors.PlaywrightCast;
import net.serenitybdd.screenplay.playwright.assertions.Ensure;
import net.serenitybdd.screenplay.playwright.interactions.Check;
import net.serenitybdd.screenplay.playwright.interactions.Click;
import net.serenitybdd.screenplay.playwright.interactions.Open;
import net.serenitybdd.screenplay.playwright.interactions.SelectFromOptions;
import net.serenitybdd.screenplay.playwright.interactions.WaitFor;
import net.serenitybdd.screenplay.playwright.questions.Checked;
import net.serenitybdd.screenplay.playwright.questions.SelectedOptionText;
import net.serenitybdd.screenplay.playwright.questions.Value;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import static net.serenitybdd.screenplay.GivenWhenThen.seeThat;
import static org.hamcrest.Matchers.equalTo;

/** Playwright interactions and questions for forms. Selectors are Playwright selector strings. */
@ExtendWith(SerenityJUnit5Extension.class)
class FormTest {

    // A self-contained page, so the example runs without a network or a site
    static final String FORM_PAGE = "data:text/html,"
            + "<select id='country'><option value='us'>United States</option><option value='ca'>Canada</option></select>"
            + "<input type='checkbox' id='terms'><button id='submit'>Send</button>";

    @BeforeEach
    void setTheStage() {
        OnStage.setTheStage(new PlaywrightCast());
    }

    @Test
    void shouldFillInAForm() {
        var ana = OnStage.theActorCalled("Ana");
        ana.attemptsTo(
                Open.url(FORM_PAGE),
                SelectFromOptions.byVisibleText("Canada").from("#country"),   // also byValue(..), byIndex(..)
                Check.the("#terms"),                                          // Uncheck.checkbox(..) to clear
                WaitFor.selector("#submit"),
                Click.on("#submit"),
                Ensure.that("#country").hasValue("ca"),
                Ensure.that("#terms").isChecked());
        ana.should(
                seeThat(SelectedOptionText.of("#country"), equalTo("Canada")),
                seeThat(Value.of("#country"), equalTo("ca")),
                seeThat(Checked.of("#terms")));
    }
}
```

### `sp-playwright/todo/ListTest.java`

```java
package todo;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.playwright.actors.PlaywrightCast;
import net.serenitybdd.screenplay.playwright.assertions.Ensure;
import net.serenitybdd.screenplay.playwright.interactions.Open;
import net.serenitybdd.screenplay.playwright.interactions.WaitFor;
import net.serenitybdd.screenplay.playwright.questions.Text;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import java.util.List;

import static net.serenitybdd.screenplay.GivenWhenThen.seeThat;
import static org.hamcrest.Matchers.contains;

/**
 * A selector used by WaitFor, Click, Ensure.hasText and Text.of must match exactly ONE element (Playwright's strict mode).
 * For a list, wait on the first row, count with hasCount, read all texts with Text.ofEach, or pick one with ">> nth=N".
 */
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Reading a list on a page")
class ListTest {

    static final String LIST_PAGE = "data:text/html,<table><tbody id='rows'>"
            + "<tr class='row'><td class='title'>Fluent Python</td></tr>"
            + "<tr class='row'><td class='title'>Clean Code</td></tr>"
            + "<tr class='row'><td class='title'>Refactoring</td></tr></tbody></table>";

    @BeforeEach
    void setTheStage() {
        OnStage.setTheStage(new PlaywrightCast());
    }

    @Test
    @DisplayName("The rows of a list can be counted, read and picked by position")
    void rowsCanBeCountedReadAndPickedByPosition() {
        var ana = OnStage.theActorCalled("Ana");
        ana.attemptsTo(
                Open.url(LIST_PAGE),
                WaitFor.selector("#rows .row >> nth=0"),            // not "#rows .row": that matches 3 elements and fails
                Ensure.that("#rows .row").hasCount(3),              // hasCount is the check for "how many"
                Ensure.that("#rows .row >> nth=0 >> .title").hasText("Fluent Python"),
                Ensure.that("#rows .row >> nth=-1 >> .title").hasText("Refactoring"));
        ana.should(seeThat(Text.ofEach("#rows .title"), contains("Fluent Python", "Clean Code", "Refactoring")));
    }
}
```

### `sp-rest/api/UsersApi.java`

```java
package api;

import net.serenitybdd.screenplay.Performable;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.rest.interactions.Get;
import net.serenitybdd.screenplay.rest.interactions.Post;

public class UsersApi {
    public static Performable fetchUser(int id) {
        return Task.where("{0} fetches user " + id, Get.resource("/users/" + id));
    }

    public static Performable createPost(String title) {
        return Task.where("{0} creates a post titled " + title,
                Post.to("/posts").with(request -> request
                        .header("Content-Type", "application/json")
                        .body("{\"title\":\"" + title + "\",\"body\":\"text\",\"userId\":1}")));
    }
}
```

### `sp-rest/api/UsersApiTest.java`

```java
package api;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.rest.abilities.CallAnApi;
import net.serenitybdd.screenplay.rest.questions.LastResponse;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import static net.serenitybdd.screenplay.GivenWhenThen.seeThat;
import static org.hamcrest.Matchers.equalTo;

@ExtendWith(SerenityJUnit5Extension.class)
class UsersApiTest {

    Actor alice;

    @BeforeEach
    void setUp() {
        alice = Actor.named("Alice").whoCan(CallAnApi.at("https://jsonplaceholder.typicode.com"));
    }

    @Test
    void shouldFindUserOne() {
        alice.attemptsTo(UsersApi.fetchUser(1));
        alice.should(
                seeThat("the status code", actor -> LastResponse.received().answeredBy(actor).statusCode(), equalTo(200)),
                seeThat("the user name", actor -> LastResponse.received().answeredBy(actor).path("name"), equalTo("Leanne Graham")));
    }

    @Test
    void shouldCreateAPost() {
        alice.attemptsTo(UsersApi.createPost("Hello"));
        alice.should(seeThat("the status code", actor -> LastResponse.received().answeredBy(actor).statusCode(), equalTo(201)));
    }
}
```

### `cuke-sp/features/add_todo.feature`

```gherkin
Feature: Todo list

  Scenario: Adding a todo
    Given Toby has opened the todo app
    When Toby adds "Buy milk" to the list
    Then Toby should see "Buy milk" in the list
```

### `cuke-sp/todo/AddATodo.java`

```java
package todo;

import net.serenitybdd.screenplay.Performable;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.actions.Enter;
import org.openqa.selenium.Keys;

public class AddATodo {
    public static Performable called(String item) {
        return Task.where("{0} adds a todo called " + item,
                Enter.theValue(item).into(TodoList.NEW_TODO).thenHit(Keys.ENTER));
    }
}
```

### `cuke-sp/todo/RunCucumberTests.java`

```java
package todo;

import org.junit.platform.suite.api.ConfigurationParameter;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectClasspathResource;
import org.junit.platform.suite.api.Suite;

import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;
import static io.cucumber.junit.platform.engine.Constants.PLUGIN_PROPERTY_NAME;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "todo")
@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME, value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel,pretty")
public class RunCucumberTests {
}
```

### `cuke-sp/todo/TheTodos.java`

```java
package todo;

import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.questions.Text;

import java.util.Collection;

public class TheTodos {
    // Text.ofEach(..) is a Question<Collection<String>> - not List<String>
    public static Question<Collection<String>> displayed() {
        return Text.ofEach(TodoList.ITEMS);
    }
}
```

### `cuke-sp/todo/TodoList.java`

```java
package todo;

import net.serenitybdd.screenplay.targets.Target;

public class TodoList {
    public static final Target NEW_TODO = Target.the("new todo field").locatedBy(".new-todo");
    public static final Target ITEMS = Target.the("todo items").locatedBy(".todo-list li label");
}
```

### `cuke-sp/todo/TodoStepDefinitions.java`

```java
package todo;

import io.cucumber.java.Before;
import io.cucumber.java.ParameterType;
import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.actions.Open;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.actors.OnlineCast;

import static net.serenitybdd.screenplay.GivenWhenThen.seeThat;
import static org.hamcrest.Matchers.hasItem;

public class TodoStepDefinitions {

    @Before
    public void setTheStage() {
        OnStage.setTheStage(new OnlineCast());
    }

    @ParameterType(".*")
    public Actor actor(String name) {
        return OnStage.theActorCalled(name);
    }

    @Given("{actor} has opened the todo app")
    public void opensTheApp(Actor actor) {
        actor.attemptsTo(Open.url("https://todo-app.serenity-js.org"));
    }

    @When("{actor} adds {string} to the list")
    public void addsATodo(Actor actor, String item) {
        actor.attemptsTo(AddATodo.called(item));
    }

    @Then("{actor} should see {string} in the list")
    public void seesTheTodo(Actor actor, String item) {
        actor.should(seeThat(TheTodos.displayed(), hasItem(item)));
    }
}
```


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_cucumber -->

# Cucumber: Runner, Tags, Hooks, Gradle and Parallel

Verified against Serenity **5.4.1** (Cucumber 8.0.4, JUnit 6.1.3). Every command on this page was run against the example at the end of the page.

## 1. Setup

- **Maven:** the Cucumber row of the dependency table on the project-setup page: `serenity-core`, `serenity-junit5`, `serenity-cucumber`, `io.cucumber:cucumber-java`, `io.cucumber:cucumber-junit-platform-engine`, `junit-platform-suite`. Use the JUnit BOM, and use the Cucumber version Serenity brings.
- **Gradle:** the `build.gradle` at the end of this page is a working build (below).
- Feature files go in `src/test/resources/features`, step definitions and hooks in a package under `src/test/java`.

## 2. The runner

A JUnit Platform suite. No `@RunWith`:

```java
@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "demo")   // the package(s) with steps and hooks
@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME, value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel,pretty")
public class RunCucumberTests {
}
```

- The plugin class is `net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel`. It connects Cucumber to Serenity: without it, Serenity APIs used in steps fail with "No BaseStepListener has been registered".
- Name the class so that Maven's test plugin runs it: ending in `Test` or `Tests` (`RunCucumberTests`). A name such as `CucumberSuite` is skipped silently (see the troubleshooting page, "Results: 0 tests").
- `@RunWith(CucumberWithSerenity.class)` (from `net.serenitybdd.cucumber`) is the JUnit 4 style runner. In a JUnit 5 project use the suite above.

## 3. Running part of the suite

All of these were run against the example. Add them to the Maven command line:

| Goal | Option | Scenarios run (of 5) |
|---|---|---|
| Only `@smoke` | `-Dcucumber.filter.tags=@smoke` |
| Everything except `@wip` | `-Dcucumber.filter.tags="not @wip"` |
| Tag expression | `-Dcucumber.filter.tags="@basket and not @wip"` |
| By scenario name (regular expression) | `-Dcucumber.filter.name="Adding passes"` |
| One feature file | `-Dcucumber.features=src/test/resources/features/basket.feature` |

The same filters can be fixed in the project instead of the command line:

- in the runner: `@ConfigurationParameter(key = FILTER_TAGS_PROPERTY_NAME, value = "not @wip")` (`Constants.FILTER_TAGS_PROPERTY_NAME`, the same class as `GLUE_PROPERTY_NAME`): 4 scenarios, or
- in `src/test/resources/junit-platform.properties`: `cucumber.filter.tags=not @wip`: 4 scenarios.

When `cucumber.features` is given, Cucumber ignores the runner's `@SelectClasspathResource` and prints a warning saying so; that is expected.

**Re-running failed scenarios.** Add the Cucumber `rerun` plugin to the runner (`...SerenityReporterParallel,pretty,rerun:target/rerun.txt`). After a run that has failures, `target/rerun.txt` lists them (`classpath:features/failing.feature:3`). Run only those with `-Dcucumber.features=@target/rerun.txt` (verified: 6 scenarios, then 1).

## 4. Gradle

the `build.gradle` at the end of this page (Serenity Gradle plugin `net.serenity-bdd.serenity-gradle-plugin` 5.4.1, Gradle 9.8.1 tested, tasks `test` and `aggregate`) was run: `gradle clean test` ran the 5 scenarios and `aggregate` produced `target/site/serenity/index.html`.

**Gradle does not pass `-D` options to the test JVM.** `gradle test -Dcucumber.filter.tags=@smoke` runs every scenario unless the build forwards the option (verified: 4 outcomes without it, 1 with it):

```groovy
test {
    useJUnitPlatform()
    systemProperties System.properties.findAll { k, v -> k.toString().startsWith('cucumber.') }
    finalizedBy 'aggregate'
}
```

The same applies to any other `-D` option your tests read. `ignoreFailures = true` in that file lets the report task run when a scenario fails (the same idea as `-Dmaven.test.failure.ignore=true` for Maven); leave it out if the build must fail.

## 5. Scenario outlines, data tables and parameter types

`cuke-plain/features/maths.feature` has a `Scenario Outline` with an `Examples` table (2 rows) and `basket.feature` has a `Background` and a data table. In the steps (`BasketSteps.java`):

- a data table argument is `io.cucumber.datatable.DataTable` (`items.asMaps()` gives a list of rows);
- a custom parameter type is a method annotated `@ParameterType("\\d+\\.\\d+")` that returns the type (`{money}` in the step text gives a `BigDecimal`);
- Maven counts each example row as a scenario (the example has 5: 1 + 2 + 2); the Serenity outcome files (`target/site/serenity/*.json`) count the outline once (4 files for these 5 scenarios), so two counts of the same run can differ.

## 6. Hooks

`cuke-plain/demo/Hooks.java`:

- `@Before` and `@After` from `io.cucumber.java`; they take an optional `io.cucumber.java.Scenario` argument (`getName()`, `getSourceTagNames()`, `isFailed()`, `getStatus()`).
- `@Before("@basket")` runs only for scenarios with that tag; `order` sorts hooks: `@Before` hooks run from the lowest order to the highest, `@After` hooks from the highest to the lowest (verified: before-1, before-5, after-5, after-1).
- `Serenity.recordReportData().withTitle("..").andContents("..")` adds data to the scenario in the Serenity report (checked: it appears in the outcome files).

## 7. Sharing state between steps

Cucumber creates new step-definition objects for every scenario. Three ways to share state inside one scenario:

1. **Fields of one step class.** Fine when all the steps are in that class.
2. **Serenity session variables** (used in the example): `Serenity.setSessionVariable("basketTotal").to(value)` and `Serenity.sessionVariableCalled("basketTotal")`. They are per scenario (and per thread) and work from any class.
3. **Dependency injection with PicoContainer:** add `io.cucumber:cucumber-picocontainer` (same version as Cucumber), give each step class a constructor that takes the shared object, and Cucumber creates one instance per scenario (verified with two step classes sharing a `Shared` object).

Do not use static fields to share scenario state: with parallel execution scenarios overwrite each other.

## 8. Parallel execution

`src/test/resources/junit-platform.properties`:

```
cucumber.execution.parallel.enabled=true
cucumber.execution.parallel.config.strategy=fixed
cucumber.execution.parallel.config.fixed.parallelism=4
```

Verified: the 5 scenarios ran and the report was produced. Keep in mind that each scenario needs its own state (section 7) and, in a web test, its own browser. Reports of parallel runs are a common source of problems; the troubleshooting page says what has and has not been reproduced.

## 9. Cucumber with Screenplay

Put `OnStage.setTheStage(new OnlineCast())` in a `@Before` hook and a `@ParameterType` named `actor` that returns `OnStage.theActorCalled(name)`, as in the Screenplay page's Cucumber example.

## 10. Cucumber with page objects and a step library (no Screenplay)

The glue code is thin: each step definition calls one `@Step` method of a step library, and the step library uses a page object. The example `cuke-pages` has the whole chain (`SignInStepDefinitions` -> `ReaderSteps` -> `SignInPage`) and its 3 scenarios pass in headless Chrome; the verification script in the serenity-core repository (`docs/ai/skill`) runs the claims below.

- Declare the library in the step-definition class with **`@Steps ReaderSteps reader;`** (`net.serenitybdd.annotations.Steps`). Declare the page object as a plain field of the step library (`SignInPage signInPage;`); Serenity creates it and gives it the driver. With `ReaderSteps reader = new ReaderSteps();` the page field stays null and the scenario errors with `NullPointerException: ... "this.signInPage" is null`.
- Page objects extend `net.serenitybdd.core.pages.PageObject` and use `@FindBy` with `WebElementFacade`; no `@Managed` is needed in Cucumber. See `page-objects.md` for the idioms.
- The report shows both layers: the Gherkin line ("When Reader signs in as ...") with the `@Step` text nested under it ("Sign in as reader@example.com with the password wrong"). Write the `@Step` text in business language too.
- The runner and plugin are the same as in section 2: the plugin class is `net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel`.

### Optional text `book(s)` in a Cucumber expression

In a step written `@Then("the catalogue lists {int} book(s)")`, `(s)` is **optional text**: the step matches "5 book" and "5 books". It does **not** match a feature line that contains the characters `book(s)`. Reproduced: a feature saying `the catalogue lists 5 book(s)` gave `The step 'the catalogue lists 5 book(s)' is undefined.` and Maven failed the build, while the Serenity report shows the scenario as **pending** (not failed), so look at the console output as well as the report. Write the feature in plain words ("1 book", "5 books"); to match a literal `(s)`, escape it in the step as `book\\(s)`.

## 11. Not covered here

Gherkin in other languages, `@Before` for browser start-up in cloud grids, the Cucumber `Transpose`/`DocString` types, Spring or Guice object factories, and Cucumber-JVM versions other than the one Serenity brings.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).

### `build.gradle`

```groovy
plugins {
    id 'java'
    id 'net.serenity-bdd.serenity-gradle-plugin' version '5.4.1'
}

repositories {
    mavenCentral()
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

dependencies {
    // One JUnit version for every JUnit artifact (Serenity 5.4.1 brings JUnit 6.1.3)
    testImplementation platform('org.junit:junit-bom:6.1.3')
    testImplementation 'org.junit.jupiter:junit-jupiter'
    testImplementation 'org.junit.platform:junit-platform-suite'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    testImplementation 'net.serenity-bdd:serenity-core:5.4.1'
    testImplementation 'net.serenity-bdd:serenity-junit5:5.4.1'
    testImplementation 'net.serenity-bdd:serenity-cucumber:5.4.1'
    testImplementation 'io.cucumber:cucumber-java:8.0.4'
    testImplementation 'io.cucumber:cucumber-junit-platform-engine:8.0.4'
    testImplementation 'org.assertj:assertj-core:3.27.7'
    testRuntimeOnly 'org.slf4j:slf4j-simple:2.0.17'
}

test {
    useJUnitPlatform()
    ignoreFailures = true               // so that the report task still runs when a scenario fails
    // Gradle does not pass -D options on to the test JVM: forward the Cucumber ones
    systemProperties System.properties.findAll { k, v -> k.toString().startsWith('cucumber.') }
    finalizedBy 'aggregate'             // build the Serenity report after the tests
}
```

### `cuke-plain/demo/BasketSteps.java`

```java
package demo;

import io.cucumber.datatable.DataTable;
import io.cucumber.java.ParameterType;
import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import net.serenitybdd.core.Serenity;

import java.math.BigDecimal;
import java.util.List;
import java.util.Map;

import static org.assertj.core.api.Assertions.assertThat;

public class BasketSteps {

    // A custom parameter type: "3.70 dollars" -> BigDecimal
    @ParameterType("\\d+\\.\\d+")
    public BigDecimal money(String amount) {
        return new BigDecimal(amount);
    }

    @Given("an empty basket")
    public void anEmptyBasket() {
        // Serenity session variables live for one scenario and can be read from any step class
        Serenity.setSessionVariable("basketTotal").to(BigDecimal.ZERO);
    }

    @When("I add these items:")
    public void iAddTheseItems(DataTable items) {
        List<Map<String, String>> rows = items.asMaps();
        for (Map<String, String> row : rows) {
            addToTotal(new BigDecimal(row.get("price")));
        }
    }

    @When("I add a {string} costing {money} dollars")
    public void iAddACosting(String name, BigDecimal price) {
        addToTotal(price);
    }

    @Then("the basket total should be {money} dollars")
    public void theTotalShouldBe(BigDecimal expected) {
        BigDecimal total = Serenity.sessionVariableCalled("basketTotal");
        assertThat(total).isEqualByComparingTo(expected);
    }

    private void addToTotal(BigDecimal price) {
        BigDecimal total = Serenity.sessionVariableCalled("basketTotal");
        Serenity.setSessionVariable("basketTotal").to(total.add(price));
    }
}
```

### `cuke-plain/demo/Hooks.java`

```java
package demo;

import io.cucumber.java.After;
import io.cucumber.java.Before;
import io.cucumber.java.Scenario;
import net.serenitybdd.core.Serenity;

public class Hooks {

    // Runs before every scenario. The Scenario parameter is optional.
    @Before(order = 0)
    public void beforeEachScenario(Scenario scenario) {
        Serenity.recordReportData().withTitle("Scenario tags").andContents(String.join(", ", scenario.getSourceTagNames()));
    }

    // Only for scenarios tagged @basket
    @Before(value = "@basket", order = 1)
    public void beforeBasketScenarios() {
        Serenity.recordReportData().withTitle("Setup").andContents("basket scenario");
    }

    @After
    public void afterEachScenario(Scenario scenario) {
        if (scenario.isFailed()) {
            Serenity.recordReportData().withTitle("Failed scenario").andContents(scenario.getName());
        }
    }
}
```

### `cuke-plain/demo/MathSteps.java`

```java
package demo;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;

import static org.assertj.core.api.Assertions.assertThat;

public class MathSteps {
    int sum;

    @Given("I have {int} and {int}")
    public void have(int a, int b) { sum = a + b; }

    @Then("the sum should be {int}")
    public void sumIs(int expected) { assertThat(sum).isEqualTo(expected); }
}
```

### `cuke-plain/demo/RunCucumberTests.java`

```java
package demo;

import org.junit.platform.suite.api.ConfigurationParameter;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectClasspathResource;
import org.junit.platform.suite.api.Suite;

import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;
import static io.cucumber.junit.platform.engine.Constants.PLUGIN_PROPERTY_NAME;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "demo")
@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME, value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel,pretty")
public class RunCucumberTests {
}
```

### `cuke-plain/features/basket.feature`

```gherkin
@basket
Feature: Shopping basket

  Background:
    Given an empty basket

  Scenario: Adding items
    When I add these items:
      | name  | price |
      | Tea   | 2.50  |
      | Bread | 1.20  |
    Then the basket total should be 3.70 dollars

  @wip
  Scenario: Work in progress
    When I add a "Cake" costing 4.00 dollars
    Then the basket total should be 4.00 dollars
```

### `cuke-plain/features/maths.feature`

```gherkin
Feature: Arithmetic

  @smoke
  Scenario: Adding passes
    Given I have 2 and 2
    Then the sum should be 4

  Scenario Outline: Adding several pairs
    Given I have <a> and <b>
    Then the sum should be <sum>

    Examples:
      | a | b | sum |
      | 1 | 1 | 2   |
      | 2 | 3 | 5   |
```

### `cuke-pages/features/sign_in.feature`

```gherkin
Feature: Signing in to the bookshop

  Scenario: A reader with the right password reaches the catalogue
    Given Reader is on the sign-in page
    When Reader signs in as "reader@example.com" with the password "correct-horse"
    Then the Catalogue page is shown

  Scenario: A reader with the wrong password is refused
    Given Reader is on the sign-in page
    When Reader signs in as "reader@example.com" with the password "wrong"
    Then Reader is told "Invalid email or password"

  Scenario Outline: The catalogue says how many books it holds
    Given Reader is on the sign-in page
    When Reader signs in as "reader@example.com" with the password "correct-horse"
    Then the catalogue lists <count> books

    Examples:
      | count |
      | 5     |
```

### `cuke-pages/shop/ReaderSteps.java`

```java
package shop;

import net.serenitybdd.annotations.Step;

import static org.assertj.core.api.Assertions.assertThat;

/** The step library: business-level steps that use the page object. Cucumber's glue code calls these. */
public class ReaderSteps {

    SignInPage signInPage;   // page objects are created for you when declared as fields

    @Step("Open the sign-in page")
    public void opensTheSignInPage() {
        signInPage.show();
    }

    @Step("Sign in as {0} with the password {1}")
    public void signsInWith(String email, String password) {
        signInPage.signInWith(email, password);
    }

    @Step("The {0} page should be shown")
    public void shouldSeeThePage(String name) {
        assertThat(signInPage.headingText()).isEqualTo(name);
    }

    @Step("The message {0} should be shown")
    public void shouldBeToldThat(String message) {
        assertThat(signInPage.messageText()).isEqualTo(message);
    }
}
```

### `cuke-pages/shop/RunCucumberTests.java`

```java
package shop;

import org.junit.platform.suite.api.ConfigurationParameter;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectClasspathResource;
import org.junit.platform.suite.api.Suite;

import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;
import static io.cucumber.junit.platform.engine.Constants.PLUGIN_PROPERTY_NAME;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "shop")
@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME, value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel,pretty")
public class RunCucumberTests {
}
```

### `cuke-pages/shop/SignInPage.java`

```java
package shop;

import net.serenitybdd.core.pages.PageObject;
import net.serenitybdd.core.pages.WebElementFacade;
import org.openqa.selenium.support.FindBy;

// A small page served from a data: URL, so the example needs no server or network.
public class SignInPage extends PageObject {
    static final String HTML = "<html><head><title>Bookshop</title></head><body>"
            + "<h1 id='heading'>Sign in</h1>"
            + "<input id='email'><input id='password' type='password'>"
            + "<button id='go' onclick=\"if (document.getElementById('password').value == 'correct-horse') {"
            + "document.getElementById('heading').innerText='Catalogue';"
            + "document.getElementById('error').innerText='5 books'} else {"
            + "document.getElementById('error').innerText='Invalid email or password'}\">Sign in</button>"
            + "<p id='error'></p></body></html>";

    @FindBy(id = "email")
    WebElementFacade email;

    @FindBy(id = "password")
    WebElementFacade password;

    @FindBy(id = "go")
    WebElementFacade signInButton;

    @FindBy(id = "heading")
    WebElementFacade heading;

    @FindBy(id = "error")
    WebElementFacade message;

    public void show() {
        getDriver().get("data:text/html;charset=utf-8," + HTML.replace("#", "%23"));
    }

    public void signInWith(String emailAddress, String secret) {
        email.type(emailAddress);
        password.type(secret);
        signInButton.click();
    }

    public String headingText() {
        return heading.getText();
    }

    public String messageText() {
        return message.getText();
    }
}
```

### `cuke-pages/shop/SignInStepDefinitions.java`

```java
package shop;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import net.serenitybdd.annotations.Steps;

public class SignInStepDefinitions {

    @Steps
    ReaderSteps reader;

    @Given("Reader is on the sign-in page")
    public void readerIsOnTheSignInPage() {
        reader.opensTheSignInPage();
    }

    @When("Reader signs in as {string} with the password {string}")
    public void readerSignsIn(String email, String password) {
        reader.signsInWith(email, password);
    }

    @Then("the {word} page is shown")
    public void thePageIsShown(String name) {
        reader.shouldSeeThePage(name);
    }

    @Then("Reader is told {string}")
    public void readerIsTold(String message) {
        reader.shouldBeToldThat(message);
    }

    // "book(s)" is optional text in a Cucumber expression: this step matches "5 book" and "5 books",
    // but NOT the literal text "5 book(s)" if a feature file contains it.
    @Then("the catalogue lists {int} book(s)")
    public void theCatalogueLists(int count) {
        reader.shouldBeToldThat(count + " books");
    }
}
```


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_page_object_idioms -->

# Page Objects: Imports and Idioms

Verified against Serenity **5.4.1** (Playwright module: **5.3.11**, the latest published). The examples at the end of this page compile and their tests pass.

Page Objects with step libraries work with Selenium and with Playwright, with JUnit 5. This is as valid as Screenplay. Use the style the user asked for or the project already uses, and don't mix Page Objects and Screenplay in one test.

## 1. Structure

```
Test (@Steps field)  ->  Step library (@Step methods)  ->  Page Object (locators and page actions)
```

Tests call step methods that read like business actions. Page Objects hide locators.

## 2. Where things live

| Class | Package |
|---|---|
| `@Step`, `@Steps`, `@Managed`, `@DefaultUrl`, `@WhenPageOpens`, `@WithTag`, `@Title`, `@Narrative`, `@Pending` | `net.serenitybdd.annotations` (**never** `net.thucydides.core.annotations`) |
| `SerenityJUnit5Extension` | `net.serenitybdd.junit5` |
| `PageObject`, `WebElementFacade` | `net.serenitybdd.core.pages` |
| `UIInteractionSteps` (base class for Selenium step libraries) | `net.serenitybdd.core.steps` |
| `Serenity` (static facade) | `net.serenitybdd.core.Serenity` |
| `ScenarioSteps` (older step library base class, still valid) | `net.thucydides.core.steps` |
| `Pages` | `net.thucydides.core.pages` |
| `@FindBy` | `org.openqa.selenium.support.FindBy` (Serenity also has `net.serenitybdd.core.annotations.findby.FindBy`) |

`net.thucydides.core.pages.WebElementFacade` and `net.thucydides.core.annotations.findby.FindBy` are deprecated aliases. Use the `net.serenitybdd` ones.

Maven: Selenium needs `serenity-core` and `serenity-junit5`. Playwright adds `serenity-playwright` and `com.microsoft.playwright:playwright`.

## 3. Selenium Page Objects

Files: `po-selenium/todo/{TodoPage,TodoSteps,AddTodoTest}.java`

- Page: `@DefaultUrl("https://...")`, `extends PageObject`, `@FindBy(css = "...") WebElementFacade field;`, or `$("css")`, `$$("css")` for lookups. **A String that starts with a tag name is not read as CSS.** `$("button")`, `$("th[data-sort='title']")` and `thenFind("button")` compile as XPath, so they look for the wrong thing and fail with `ElementShouldBeEnabledException` or `NoSuchElementException ... xpath`. Start the selector with `#` or `.` (`$("#go")`, `$(".sort")`), or use `$(By.cssSelector("button"))` (for a child element `row.findBy(By.cssSelector("button"))`; `thenFind` has no `By` version), or write a real XPath. The same rule applies to Screenplay `Target.the("name").locatedBy(..)`.
- **Don't write your own `open()`.** `PageObject.open()` already exists and opens the `@DefaultUrl`; it is `final`, so redeclaring it fails to compile. For another URL use `openAt("https://...")`, or a differently named method.
- `@FindBy(css = ...)` takes a String. `$(By.cssSelector(..))` takes a `By`. Don't mix them up.
- Step library: `extends UIInteractionSteps`, a field for each page object (injected automatically), and `@Step("Add the todo '{0}'")` on public methods. `{0}` is the first argument.
- Test: `@ExtendWith(SerenityJUnit5Extension.class)`, `@Managed(driver = "chrome") WebDriver driver;`, `@Steps TodoSteps todo;`. Assertions in the test with AssertJ or Hamcrest, or with `assertThat` inside a `@Step` method.
- Useful `WebElementFacade` methods: `type(..)`, `typeAndEnter(..)`, `click()`, `getText()`, `isVisible()`, `waitUntilVisible()`, `selectByVisibleText(..)`, `getValue()`.

## 4. Playwright Page Objects

Files: `po-playwright/todo/{TodoPage,TodoSteps,AddTodoTest}.java`

- The Page Object is a plain class that holds a `com.microsoft.playwright.Page`. It does **not** extend `PageObject`, and doesn't use `@FindBy`, `WebElementFacade` or `@DefaultUrl`. Locators are Playwright `page.locator("css")`, `getByRole(..)`.
- A locator used with `click()`, `fill()`, `textContent()` or `waitFor()` must match exactly one element (strict mode); for lists use `.first()`, `.nth(i)`, `.count()` or `allTextContents()`. **Don't build a Playwright text pattern with `Pattern.quote(..)`.** Playwright sends the pattern to the browser's JavaScript engine, which doesn't understand Java's `\Q..\E`, so `setHasText(Pattern.compile("^\\s*" + Pattern.quote(title) + "\\s*$"))` matches nothing and the step times out after 30 seconds (two Opus runs). Use the plain string (`setHasText(title)` matches by substring, ignoring case; `text-is('..')` / `has-text('..')` in a selector string match exactly or by substring), or write the pattern by hand (`Pattern.compile("^\\s*Clean Code\\s*$")`). Run in the verification script in the serenity-core repository (`docs/ai/skill`).
- Playwright Java API details models get wrong (run in the verification script in the serenity-core repository (`docs/ai/skill`)): `page.getByRole(role, new Page.GetByRoleOptions()...)` but `locator.getByRole(role, new Locator.GetByRoleOptions()...)`: passing the `Page` options to a locator is a compile error; and as a selector string a role needs the prefix, `"role=heading[name=\"Sign in\"]"`: `"heading[name=...]"` throws `InvalidSelectorError`.
- The test owns the browser: start `Playwright` and the `Browser` in `@BeforeAll`, and in `@BeforeEach` create a page and call `PlaywrightSerenity.registerPage(page)`. In `@AfterEach` call `PlaywrightSerenity.unregisterPage(page)` and close the page.
- Step library: a plain class with `@Step` methods that get the page from `PlaywrightSerenity.getCurrentPage()` (or take a `Page` parameter) and wrap it in the Page Object. No `UIInteractionSteps`.
- `PlaywrightSerenity` is in `net.serenitybdd.playwright`. A `@SerenityPlaywright` meta-annotation (`net.serenitybdd.playwright.junit5`) combines the extensions. See `serenity-playwright-demo` for it.

## 5. Common mistakes

| Wrong | Right |
|---|---|
| `import net.thucydides.core.annotations.{Step,Steps,Managed,DefaultUrl}` (most Page Object failures) | `net.serenitybdd.annotations.*` |
| Declaring `public void open()` in a page object | Delete it. Use the inherited `open()` with `@DefaultUrl`, or `openAt(url)` |
| `@FindBy("...")` or passing a String where a `By` is needed (and the reverse) | `@FindBy(css = "...")`; `$("css")` for Strings; `$(By.id("x"))` for a `By` |
| `$("button")`, `$("th[data-sort='title']")`, `row.thenFind("button")` (read as XPath) | `$("#go")`, `$(By.cssSelector("button"))`, `row.findBy(By.cssSelector("button"))` |
| JUnit 4 `@RunWith(SerenityRunner.class)` | `@ExtendWith(SerenityJUnit5Extension.class)` |
| `@Page` annotation | Doesn't exist. Use a page object field in the step library, or `@Steps` for step libraries in the test |
| `ScenarioSteps` from `net.serenitybdd...` | `net.thucydides.core.steps.ScenarioSteps` (this one *is* under `net.thucydides`) |
| Extending `PageObject` for a Playwright page, or `Page` from Selenium | Playwright pages are plain classes using `com.microsoft.playwright.Page` |

## 6. Not yet verified
- Runtime behaviour beyond the examples: they ran once against the live todo app.
- `@WhenPageOpens`, `waitFor`/`waitUntil*` helpers and `Pages`-based injection are not covered by examples.
- The Playwright section is based on 5.3.11 and the `serenity-playwright-demo` module.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).

### `po-selenium/todo/AddTodoTest.java`

```java
package todo;

import net.serenitybdd.annotations.Managed;
import net.serenitybdd.annotations.Steps;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.WebDriver;

import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
class AddTodoTest {

    @Managed(driver = "chrome")
    WebDriver driver;

    @Steps
    TodoSteps todo;

    @Test
    void shouldShowTheNewTodo() {
        todo.openTheApplication();
        todo.addTodo("Buy milk");
        assertThat(todo.todoItems()).contains("Buy milk");
    }
}
```

### `po-selenium/todo/TodoPage.java`

```java
package todo;

import net.serenitybdd.annotations.DefaultUrl;
import net.serenitybdd.core.pages.PageObject;
import net.serenitybdd.core.pages.WebElementFacade;
import org.openqa.selenium.support.FindBy;

import java.util.List;

// Do not declare your own open(): PageObject already has open() and it uses @DefaultUrl.
@DefaultUrl("https://todo-app.serenity-js.org")
public class TodoPage extends PageObject {

    @FindBy(css = ".new-todo")
    WebElementFacade newTodoField;

    public void addTodo(String item) {
        newTodoField.typeAndEnter(item);
    }

    public List<String> todoItems() {
        return $$(".todo-list li label").stream().map(WebElementFacade::getText).toList();
    }
}
```

### `po-selenium/todo/TodoSteps.java`

```java
package todo;

import net.serenitybdd.annotations.Step;
import net.serenitybdd.core.steps.UIInteractionSteps;

import java.util.List;

public class TodoSteps extends UIInteractionSteps {

    TodoPage todoPage;   // page objects are injected into step libraries

    @Step("Open the todo application")
    public void openTheApplication() {
        todoPage.open();
    }

    @Step("Add the todo '{0}'")
    public void addTodo(String item) {
        todoPage.addTodo(item);
    }

    public List<String> todoItems() {
        return todoPage.todoItems();
    }
}
```

### `po-playwright/todo/AddTodoTest.java`

```java
package todo;

import com.microsoft.playwright.Browser;
import com.microsoft.playwright.BrowserType;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Playwright;
import net.serenitybdd.annotations.Steps;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.playwright.PlaywrightSerenity;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
class AddTodoTest {

    @Steps
    TodoSteps todo;

    static Playwright playwright;
    static Browser browser;
    Page page;

    @BeforeAll
    static void startBrowser() {
        playwright = Playwright.create();
        browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(true));
    }

    @AfterAll
    static void stopBrowser() {
        browser.close();
        playwright.close();
    }

    @BeforeEach
    void openPage() {
        page = browser.newPage();
        PlaywrightSerenity.registerPage(page);   // lets Serenity report screenshots and steps
    }

    @AfterEach
    void closePage() {
        PlaywrightSerenity.unregisterPage(page);
        page.close();
    }

    @Test
    void shouldShowTheNewTodo() {
        todo.openTheApplication();
        todo.addTodo("Buy milk");
        assertThat(todo.todoItems()).contains("Buy milk");
    }
}
```

### `po-playwright/todo/TodoPage.java`

```java
package todo;

import com.microsoft.playwright.Page;

import java.util.List;

/** A plain class that wraps a Playwright Page. It does not extend Serenity's PageObject. */
public class TodoPage {

    private final Page page;

    public TodoPage(Page page) {
        this.page = page;
    }

    public void open() {
        page.navigate("https://todo-app.serenity-js.org");
    }

    public void addTodo(String item) {
        page.locator(".new-todo").fill(item);
        page.locator(".new-todo").press("Enter");
    }

    public List<String> todoItems() {
        return page.locator(".todo-list li label").allInnerTexts();
    }
}
```

### `po-playwright/todo/TodoSteps.java`

```java
package todo;

import com.microsoft.playwright.Page;
import net.serenitybdd.annotations.Step;
import net.serenitybdd.playwright.PlaywrightSerenity;

import java.util.List;

public class TodoSteps {

    private TodoPage todoPage() {
        Page page = PlaywrightSerenity.getCurrentPage();   // the page registered by the test
        return new TodoPage(page);
    }

    @Step("Open the todo application")
    public void openTheApplication() {
        todoPage().open();
    }

    @Step("Add the todo '{0}'")
    public void addTodo(String item) {
        todoPage().addTodo(item);
    }

    public List<String> todoItems() {
        return todoPage().todoItems();
    }
}
```


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_rest_step_library -->

# REST with SerenityRest and a Step Library

Verified against Serenity **5.4.1**. The example at the end of this page compiles and its tests pass; each claim was run.

This is one of several valid ways to test a REST API with Serenity. The other is Screenplay with `CallAnApi` (see `screenplay.md` and `sp-rest/`). Use the one the user asked for or the project already uses; don't mix them.

## What you need

Artifact `serenity-rest-assured` (it brings REST-assured and Hamcrest), plus `serenity-core` and `serenity-junit5` as in `project-setup.md`. Do not pin REST-assured or Groovy versions (see `troubleshooting.md`).

## Where things live

| Class | Package |
|---|---|
| `SerenityRest` (`given()`, `then()`, `lastResponse()`, `reset()`) | `net.serenitybdd.rest` |
| `@Step` | `net.serenitybdd.annotations` |
| `@Steps` | `net.serenitybdd.annotations` |
| `SerenityJUnit5Extension` | `net.serenitybdd.junit5` |
| `ScenarioSteps` (optional base class, not needed) | `net.thucydides.core.steps` |

## The pattern

1. **A step library**: a plain class whose methods are annotated `@Step("business wording")`. The REST calls go inside the methods, using `SerenityRest.given()...when().get(..)`. Use `SerenityRest`, not `io.restassured.RestAssured`: it is the same API, but Serenity records every request and response in the report.
2. **The test** declares `@Steps BookshopApi bookshop;` (Serenity creates the library) and reads like a story: `bookshop.listTheBooks(); bookshop.responseShouldHaveStatus(200);`.
3. **Checks go in `@Step` methods too**, using `SerenityRest.then().statusCode(..)` and `.body("path", matcher)`, so the report shows "The response should have status 200".

`SerenityRest.then()` checks the last response of the current thread. The base URI is not remembered between calls unless you keep it in the step library (as the example does) or set `SerenityRest`/`RestAssured.baseURI`.

## Mistakes models make

| Wrong | Right |
|---|---|
| `import net.thucydides.core.annotations.Step` or `...annotations.Steps` (compile error: cannot find symbol) | `net.serenitybdd.annotations.Step`, `net.serenitybdd.annotations.Steps` |
| `import io.restassured.RestAssured.given` for calls that should appear in the report | `net.serenitybdd.rest.SerenityRest.given` |
| Creating the library with `new BookshopApi()` in the test | `@Steps BookshopApi bookshop;`. With `new`, the business steps vanish from the report and only raw `GET http://...` lines remain. |
| `@Step` missing on a method | The method still runs but the report shows only the raw `GET http://...` line instead of your wording. |
| `body("total", equalTo(90.0))` or `closeTo(90.0, 0.001)` | JSON numbers with a decimal point come back as `Float`, so a `Double` matcher fails (`Expected: <90.0>`, `Expected: a numeric value within <0.001> of <90.0>`). Use `equalTo(90.0f)`, or read the value as a double: `SerenityRest.lastResponse().jsonPath().getDouble("total")` and assert on that (AssertJ). |
| Extending `ScenarioSteps` because old guides did | Not needed. A plain class works. If you do extend it, the package is `net.thucydides.core.steps.ScenarioSteps`. |

## Wording for the living documentation

Name steps for what a person does or sees, not for the HTTP call: "Look up book number 2", "The response should show the title Clean Code", not "GET /api/books/2" or "Check JSON path title". Give each `@Test` a `@DisplayName` that states the business outcome, and the class a `@DisplayName` naming the feature (see `living-documentation.md`).

## Examples

| Style | Files |
|---|---|
| REST + step library + JUnit 5 | `rest-steps/api/*` |

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).

### `rest-steps/api/BookshopApi.java`

```java
package api;

import net.serenitybdd.annotations.Step;
import net.serenitybdd.rest.SerenityRest;

import static net.serenitybdd.rest.SerenityRest.given;

/** A step library: each @Step method is one line in the report, and holds the REST calls for it. */
public class BookshopApi {
    private String baseUri;

    public void usingTheServerAt(String baseUri) {
        this.baseUri = baseUri;
    }

    @Step("List the books in the catalogue")
    public void listTheBooks() {
        given().baseUri(baseUri).when().get("/api/books");
    }

    @Step("Look up book number {0}")
    public void lookUpBook(int id) {
        given().baseUri(baseUri).when().get("/api/books/" + id);
    }

    @Step("Place an order for book {0} as a signed-in reader")
    public void placeAnOrderFor(int bookId) {
        given().baseUri(baseUri)
                .header("Authorization", "Bearer abc123")
                .contentType("application/json")
                .body("{\"items\":[{\"bookId\":" + bookId + ",\"qty\":2}],\"name\":\"Ada\"}")
                .when().post("/api/orders");
    }

    @Step("Place an order without signing in")
    public void placeAnOrderWithoutSigningIn() {
        given().baseUri(baseUri)
                .contentType("application/json")
                .body("{\"items\":[{\"bookId\":1,\"qty\":1}],\"name\":\"Ada\"}")
                .when().post("/api/orders");
    }

    @Step("The response should have status {0}")
    public void responseShouldHaveStatus(int status) {
        SerenityRest.then().statusCode(status);
    }

    @Step("The response should list {0} books")
    public void responseShouldListBooks(int count) {
        SerenityRest.then().body("size()", org.hamcrest.Matchers.equalTo(count));
    }

    @Step("The response should show the title {0}")
    public void responseShouldShowTitle(String title) {
        SerenityRest.then().body("title", org.hamcrest.Matchers.equalTo(title));
    }

    @Step("The response should show the error {0}")
    public void responseShouldShowError(String message) {
        SerenityRest.then().body("error", org.hamcrest.Matchers.equalTo(message));
    }

    @Step("The order total should be {0}")
    public void orderTotalShouldBe(double total) {
        SerenityRest.then().body("total", org.hamcrest.Matchers.equalTo((float) total));
    }
}
```

### `rest-steps/api/BookshopApiTest.java`

```java
package api;

import net.serenitybdd.annotations.Steps;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Browsing the book catalogue")
class BookshopApiTest {

    static final BookshopServer server = new BookshopServer();
    static int port;

    @Steps
    BookshopApi bookshop;

    @BeforeAll
    static void startServer() throws Exception {
        port = server.start();
    }

    @AfterAll
    static void stopServer() {
        server.stop();
    }

    @BeforeEach
    void pointAtTheServer() {
        bookshop.usingTheServerAt("http://localhost:" + port);
    }

    @Test
    @DisplayName("A shopper sees the catalogue and finds Clean Code by its number")
    void shopperFindsABook() {
        bookshop.listTheBooks();
        bookshop.responseShouldHaveStatus(200);
        bookshop.responseShouldListBooks(2);

        bookshop.lookUpBook(2);
        bookshop.responseShouldShowTitle("Clean Code");
    }

    @Test
    @DisplayName("A shopper who asks for a book that does not exist is told so")
    void unknownBook() {
        bookshop.lookUpBook(99);
        bookshop.responseShouldHaveStatus(404);
        bookshop.responseShouldShowError("Book not found");
    }

    @Test
    @DisplayName("A signed-in reader can place an order, and an anonymous visitor cannot")
    void ordering() {
        bookshop.placeAnOrderFor(1);
        bookshop.responseShouldHaveStatus(201);
        bookshop.orderTotalShouldBe(90.0);

        bookshop.placeAnOrderWithoutSigningIn();
        bookshop.responseShouldHaveStatus(401);
        bookshop.responseShouldShowError("Authentication required");
    }
}
```

### `rest-steps/api/BookshopServer.java`

```java
package api;

import com.sun.net.httpserver.HttpServer;

import java.io.IOException;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;

/** A tiny stand-in for the application under test, so the example runs without a network. */
public class BookshopServer {
    private HttpServer server;

    public int start() throws IOException {
        server = HttpServer.create(new InetSocketAddress("localhost", 0), 0);
        server.createContext("/api/books", exchange -> {
            String path = exchange.getRequestURI().getPath();
            int status = 200;
            String body;
            if (path.equals("/api/books")) {
                body = "[{\"id\":1,\"title\":\"Fluent Python\",\"price\":45.0},{\"id\":2,\"title\":\"Clean Code\",\"price\":33.5}]";
            } else if (path.equals("/api/books/2")) {
                body = "{\"id\":2,\"title\":\"Clean Code\",\"price\":33.5}";
            } else {
                status = 404;
                body = "{\"error\":\"Book not found\"}";
            }
            byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
            exchange.getResponseHeaders().add("Content-Type", "application/json");
            exchange.sendResponseHeaders(status, bytes.length);
            exchange.getResponseBody().write(bytes);
            exchange.close();
        });
        server.createContext("/api/orders", exchange -> {
            boolean signedIn = "Bearer abc123".equals(exchange.getRequestHeaders().getFirst("Authorization"));
            int status = signedIn ? 201 : 401;
            String body = signedIn ? "{\"id\":\"ORD-1001\",\"total\":90.0,\"status\":\"PLACED\"}" : "{\"error\":\"Authentication required\"}";
            byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
            exchange.getResponseHeaders().add("Content-Type", "application/json");
            exchange.sendResponseHeaders(status, bytes.length);
            exchange.getResponseBody().write(bytes);
            exchange.close();
        });
        server.start();
        return server.getAddress().getPort();
    }

    public void stop() {
        server.stop(0);
    }
}
```


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_configuration -->

# Configuration: serenity.conf, Properties and Environments

Verified against Serenity **5.4.1**. The behaviour described here was run against the example at the end of the page.

## 1. Where configuration comes from

| Source | Where | Read? |
|---|---|---|
| `serenity.conf` (HOCON) | `src/test/resources/` (on the classpath) | yes |
| `serenity.conf` | project root | **no, ignored** |
| `serenity.properties` | project root | yes |
| `serenity.properties` | `src/test/resources/` | yes |
| System properties | `-Dkey=value` on the Maven command line | yes, override the files |

What wins:

- A `-D` option wins over both files (`-Dwebdriver.base.url=...` replaced the value in the file).
- `serenity.properties` in the **project root** wins over `serenity.conf` in `src/test/resources`.
- `serenity.conf` wins over a `serenity.properties` that is also in `src/test/resources`.
- OS environment variables (`SERENITY_PROJECT_NAME=...`) did **not** set `serenity.project.name`.

`thucydides.*` and `serenity.*` are synonyms: `thucydides.project.name = "x"` in either file sets the project name. Prefer `serenity.*`.

After deleting or moving a configuration file, run `mvn clean ...`: Maven leaves the old copy in `target/test-classes`, so a deleted `serenity.conf` is still read (checked: the old value was still used without `clean`).

## 2. `serenity.conf`

HOCON. Nested and dotted forms mean the same:

```hocon
serenity {
  project.name = "My project"
  take.screenshots = FOR_FAILURES
}
webdriver {
  base.url = "https://example.com"
}
headless.mode = true
```

The full example, with environments, is `config/resources/serenity.conf`.

## 3. Environments

```hocon
environments {
  default { app.url = "https://dev.example.com"
            db.name = "dev" }
  staging { app.url = "https://staging.example.com" }
  all     { company = "Acme" }
}
```

Pick one with `-Denvironment=staging`.

- With no `environment`, the `default` block applies. With `-Denvironment=staging`, `staging` applies and values it does not define fall back to `default` (`db.name` stayed `dev`).
- `all` applies in every environment.
- **Your own keys inside `environments { }` are NOT visible as plain properties.** `environmentVariables.getProperty("app.url")` returns **null**, in every environment. Read them through `EnvironmentSpecificConfiguration` (next section). This is the usual cause of "I get null when I read a value from serenity.conf".
- **Serenity's own keys inside `environments { }` do work** and override the top-level value: `webdriver.base.url` and `serenity.project.name` inside `environments { staging { } }` took effect with `-Denvironment=staging`. Values in `default` override the top-level value too.
- Command-line override of a value in `environments`: use the full name, `-Denvironments.staging.app.url=https://...`. A plain `-Dapp.url=...` did **not** override it.

## 4. Reading values in code

```java
EnvironmentVariables env = SystemEnvironmentVariables.currentEnvironmentVariables();   // net.thucydides.model.environment
String name = ThucydidesSystemProperty.SERENITY_PROJECT_NAME.from(env);                 // net.thucydides.model
String url  = EnvironmentSpecificConfiguration.from(env).getOptionalProperty("app.url").orElse("none"); // net.serenitybdd.model.environment
```

- Works anywhere, including static code and static initialisers. `Serenity.environmentVariables()` (`net.serenitybdd.core.Serenity`) returns the same kind of object.
- In a step library (a class with `@Step` methods used through `@Steps`), declare a field `EnvironmentVariables environmentVariables;` (type `net.thucydides.model.util.EnvironmentVariables`): Serenity injects it.
- Built-in keys: `ThucydidesSystemProperty.X.from(env)` (also `integerFrom`, `booleanFrom`, `isDefinedIn`) or `env.getProperty("webdriver.base.url")`.
- Your own keys outside `environments { }` can be read with `env.getProperty("my.key")`.

## 5. Common keys

All of these exist in `ThucydidesSystemProperty` (checked). Meanings are from the Serenity documentation, except where marked *(run)*.

| Key | Meaning |
|---|---|
| `webdriver.driver` | Which browser to run in (`chrome`, `firefox`, `edge`, `safari`, ...). An unknown name fails with `Unsupported browser type` *(run)*. |
| `webdriver.base.url` | The default starting URL; base for relative paths. Read back *(run)*. |
| `headless.mode` | Headless Chrome, Firefox or Edge. `true` added Chrome's `--headless` arguments *(run)*. |
| `webdriver.chrome.driver` | Path to a chromedriver binary. Only set it if you really supply one; a missing file is an error *(run)*. |
| `webdriver.autodownload` | `false` stops Serenity downloading driver binaries. |
| `webdriver.remote.url`, `webdriver.remote.driver` | The URL of a Selenium Grid or cloud hub, and the driver to use there. |
| `webdriver.timeouts.implicitlywait` | How long the driver waits for elements to appear, in milliseconds. |
| `webdriver.wait.for.timeout` | How long fluent waits wait, in milliseconds. |
| `serenity.project.name` | The name shown on reports. Read back *(run)*. |
| `serenity.outputDirectory` | Where reports go (default `target/site/serenity`). |
| `serenity.take.screenshots` | `FOR_EACH_ACTION`, `BEFORE_AND_AFTER_EACH_STEP`, `AFTER_EACH_STEP`, `FOR_FAILURES` or `DISABLED`. On a passing test `DISABLED` and `FOR_FAILURES` stored no screenshots; the other values, and not setting it, stored some *(run)*. |
| `serenity.browser.width`, `serenity.browser.height` | Browser window size. |
| `serenity.restart.browser.frequency` | Start a new browser every N rows in data-driven tests. |
| `serenity.reports.show.step.details` | Show a breakdown of steps by result in report tables. |

Do not invent keys. If a key is not in the Serenity documentation or `ThucydidesSystemProperty`, it is probably ignored without any message.

## 6. Setting values from the build

- **Maven, one run:** `mvn verify -Denvironment=staging -Dwebdriver.driver=firefox`.
- **Maven, fixed in the pom:** put them in the test plugin's `<systemPropertyVariables>`. (A pom property such as `${cucumber.filter.tags}` can feed it.)
- **Gradle:** `gradle test -Denvironment=staging` does **not** reach the tests unless `build.gradle` forwards it, as for the Cucumber options (see the Cucumber page): a filtered selection inside `test { }`, such as `systemProperties System.properties.findAll { k, v -> k.toString().startsWith('serenity.') || k == 'environment' }`.

## 7. Mistakes

| Wrong | Right |
|---|---|
| `serenity.conf` in the project root | `src/test/resources/serenity.conf` |
| Reading `app.url` with `env.getProperty` when it is defined under `environments { }` | `EnvironmentSpecificConfiguration.from(env).getOptionalProperty("app.url")` |
| `-Dapp.url=...` to override a value defined under `environments { staging { } }` | `-Denvironments.staging.app.url=...` |
| An old `serenity.properties` in the project root silently beating `serenity.conf` | Keep one file, or remember that the root properties file wins |
| Setting a key through an OS environment variable | Use `-D`, the file, or the build tool's system property settings |
| Hard-coding `webdriver.chrome.driver` to a path on one machine | Leave it unset (see Troubleshooting) |

## 8. Not covered

Cloud and grid capabilities (`serenity.driver.capabilities`, `webdriver.capabilities.*`), proxies, Appium settings, the `drivers { os { } }` blocks, requirements and report customisation keys, and `.serenity` files in a user home directory. See the documentation page of Serenity properties.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).

### `config/cfg/ConfigReader.java`

```java
package cfg;

import net.serenitybdd.model.environment.EnvironmentSpecificConfiguration;
import net.thucydides.model.util.EnvironmentVariables;

/** A step library. Serenity injects the EnvironmentVariables field. */
public class ConfigReader {

    EnvironmentVariables environmentVariables;

    public String appUrl() {
        return EnvironmentSpecificConfiguration.from(environmentVariables).getOptionalProperty("app.url").orElse("<none>");
    }

    public boolean injected() {
        return environmentVariables != null;
    }
}
```

### `config/cfg/ConfigurationTest.java`

```java
package cfg;

import net.serenitybdd.annotations.Steps;
import net.serenitybdd.core.Serenity;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.model.environment.EnvironmentSpecificConfiguration;
import net.thucydides.model.ThucydidesSystemProperty;
import net.thucydides.model.environment.SystemEnvironmentVariables;
import net.thucydides.model.util.EnvironmentVariables;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
class ConfigurationTest {

    @Steps
    ConfigReader reader;

    @Test
    void readsValuesFromSerenityConf() {
        // Anywhere in the code, including a static context:
        EnvironmentVariables env = SystemEnvironmentVariables.currentEnvironmentVariables();
        EnvironmentSpecificConfiguration environmentConfig = EnvironmentSpecificConfiguration.from(env);

        // Plain keys: through the property enum, or by name
        System.out.println("CFG base.url=" + ThucydidesSystemProperty.WEBDRIVER_BASE_URL.from(env));
        System.out.println("CFG project.name=" + ThucydidesSystemProperty.SERENITY_PROJECT_NAME.from(env));
        System.out.println("CFG by-name=" + env.getProperty("webdriver.base.url"));
        System.out.println("CFG serenity-facade=" + Serenity.environmentVariables().getProperty("webdriver.base.url"));

        System.out.println("CFG my.setting=" + env.getProperty("my.setting"));

        // Keys under environments { }: ONLY through EnvironmentSpecificConfiguration
        System.out.println("CFG plain app.url=" + env.getProperty("app.url"));
        System.out.println("CFG specific app.url=" + environmentConfig.getOptionalProperty("app.url").orElse("<none>"));
        System.out.println("CFG specific db.name=" + environmentConfig.getOptionalProperty("db.name").orElse("<none>"));
        System.out.println("CFG specific company=" + environmentConfig.getOptionalProperty("company").orElse("<none>"));
        System.out.println("CFG injected=" + reader.injected() + " " + reader.appUrl());

        assertThat(ThucydidesSystemProperty.SERENITY_PROJECT_NAME.from(env)).isNotBlank();
        assertThat(reader.injected()).isTrue();
    }
}
```

### `config/resources/serenity.conf`

```hocon
# src/test/resources/serenity.conf  (HOCON). Serenity reads it from the classpath, not from the project root.
serenity {
  project.name = "Config demo"
  take.screenshots = FOR_FAILURES
}

webdriver {
  base.url = "https://base.example.com"
}

headless.mode = true

# A key of your own, outside environments { }
my.setting = "plain value"

# Values that depend on the environment. Select one with -Denvironment=staging.
environments {
  default {
    app.url = "https://dev.example.com"
    db.name = "dev"
  }
  staging {
    app.url = "https://staging.example.com"
  }
  all {
    company = "Acme"
  }
}
```


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_project_setup -->

# Project Setup: Dependencies and Configuration

Verified against Serenity **5.4.1**. The dependency sets, JUnit BOM and report plugin were run end to end (`mvn clean verify` ran the examples and produced the report). The `serenity.conf` snippet follows the project's own samples but was not run.

Use one Serenity version for every `net.serenity-bdd` artifact (a `serenity.version` property). Java 17+. Playwright modules are published up to 5.3.11, so a Playwright project may need `serenity.version` 5.3.11 for those artifacts; check Maven Central for the latest before pinning.

## Dependencies by style (all `test` scope)

| Style | `net.serenity-bdd` artifacts | Other |
|---|---|---|
| Page Objects + Selenium | `serenity-core`, `serenity-junit5` | `org.junit.jupiter:junit-jupiter`, `org.assertj:assertj-core` |
| Page Objects + Playwright | `serenity-core`, `serenity-junit5`, `serenity-playwright` | + `com.microsoft.playwright:playwright` |
| Screenplay + Selenium | `serenity-core`, `serenity-junit5`, `serenity-screenplay`, `serenity-screenplay-webdriver`, `serenity-ensure` | JUnit Jupiter, AssertJ |
| Screenplay + Playwright | `serenity-core`, `serenity-junit5`, `serenity-screenplay`, `serenity-screenplay-playwright`, `serenity-playwright` | JUnit Jupiter, `com.microsoft.playwright:playwright` |
| Screenplay + REST | `serenity-core`, `serenity-junit5`, `serenity-screenplay`, `serenity-screenplay-rest`, `serenity-rest-assured`, `serenity-ensure` | JUnit Jupiter |
| Cucumber (+ Screenplay) | the Screenplay web set above, plus `serenity-cucumber` | `io.cucumber:cucumber-java`, `io.cucumber:cucumber-junit-platform-engine`, `org.junit.platform:junit-platform-suite` |

Serenity 5.4.1 itself depends on **JUnit 6.1.3** (`serenity-junit5`) and **Cucumber 8.0.4** (`serenity-cucumber`). Don't pin older JUnit or Cucumber versions: mixed JUnit versions fail at run time with "conflicting versions" errors, even though the code compiles. Import the JUnit BOM so every JUnit artifact (including `junit-platform-suite` and the engine that `cucumber-junit-platform-engine` brings in) has the same version:

```xml
<dependencyManagement>
  <dependencies>
    <dependency><groupId>org.junit</groupId><artifactId>junit-bom</artifactId><version>6.1.3</version><type>pom</type><scope>import</scope></dependency>
  </dependencies>
</dependencyManagement>
```

Then list `junit-jupiter` and `junit-platform-suite` without versions, and use Cucumber 8.0.4 for `cucumber-java` and `cucumber-junit-platform-engine`. Other versions in the harness: Playwright 1.52.0, AssertJ 3.27.7. Add `org.slf4j:slf4j-simple` to silence logging warnings.

## Build and reports

```xml
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.1</version></plugin>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-failsafe-plugin</artifactId><version>3.5.1</version></plugin>
<plugin>
  <groupId>net.serenity-bdd.maven.plugins</groupId>
  <artifactId>serenity-maven-plugin</artifactId>
  <version>${serenity.version}</version>
  <executions>
    <execution><id>serenity-reports</id><phase>post-integration-test</phase><goals><goal>aggregate</goal></goals></execution>
  </executions>
</plugin>
```

- Compile only: `mvn test-compile` (fast, use it to check generated code).
- Run and build the report: `mvn clean verify`. The report is in `target/site/serenity/index.html`.
- Name test classes so surefire/failsafe pick them up (`*Test`, or `*IT` for failsafe); a Cucumber runner is a JUnit Platform `@Suite` class.

## `src/test/resources/serenity.conf` (HOCON)

```hocon
serenity {
  project.name = "My project"
  take.screenshots = FOR_FAILURES      # FOR_EACH_ACTION, BEFORE_AND_AFTER_EACH_STEP, DISABLED
}
headless.mode = true
webdriver.base.url = "https://example.com"
environments {
  default { base.url = "https://example.com" }
}
```

`serenity.*` and `thucydides.*` keys are synonyms; prefer `serenity.*`. Don't invent keys: check `docs/reference` on https://serenity-bdd.github.io or `ThucydidesSystemProperty` in `serenity-model`.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_troubleshooting -->

# Troubleshooting by Symptom

Verified against Serenity **5.4.1** (Playwright modules: **5.3.11**). Each entry was reproduced in a test project and its fix was run.

How to use this page: find the message you see (the text is quoted from the real output), read the cause, apply the fix, and run the build again. If nothing here matches, read the first `Caused by:` and the first `[ERROR]` line in the Maven output, not the last.

## Where to look first

- Serenity writes one JSON file per test to `target/site/serenity/` as the tests run. If the HTML report is missing, these files still show what happened.
- The line `Results: N tests | ...` in the Maven output (from the Serenity Maven plugin) tells you how many tests Serenity saw.
- `mvn -q test-compile` separates compile errors from run-time ones.

## The build fails or does nothing

### "The wrapped NoClassDefFoundError is likely caused by the versions of JUnit jars ... not being properly aligned"

```
The following conflicting versions were detected:
- org.junit.jupiter.api: 6.1.3
- org.junit.platform.suite.api: 1.12.2 ...
```

- **Cause:** the pom pins `junit-jupiter`, `junit-platform-suite` or another JUnit artifact to a version other than the one Serenity brings. Serenity 5.4.1 depends on **JUnit 6.1.3**. The code compiles; the tests fail when they start.
- **Fix:** remove the pinned JUnit versions and import the JUnit BOM so all JUnit artifacts match:

```xml
<dependencyManagement>
  <dependencies>
    <dependency><groupId>org.junit</groupId><artifactId>junit-bom</artifactId><version>6.1.3</version><type>pom</type><scope>import</scope></dependency>
  </dependencies>
</dependencyManagement>
```

List `junit-jupiter` and `junit-platform-suite` without versions.

### `java.lang.AbstractMethodError: Receiver class io.cucumber.junit.platform.engine.CucumberConfiguration does not define or inherit an implementation of the resolved method 'abstract ... getGlueDiscoveryRequest()'`

- **Cause:** `cucumber-java` or `cucumber-junit-platform-engine` is pinned to a version that does not match the Cucumber that `serenity-cucumber` brings (8.0.4 for Serenity 5.4.1; 7.34.2 for 5.3.11). Reproduced with 7.31.0.
- **Fix:** use the version Serenity brings (check with `mvn dependency:tree -Dincludes=io.cucumber`), or leave the Cucumber versions out.

### `Failed to transform configuration parameter with key 'cucumber.plugin' and initial value 'io.cucumber.core.plugin.SerenityReporterParallel,pretty'`

- **Cause:** the Serenity plugin class is named with the wrong package.
- **Fix:** `@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME, value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel,pretty")`.

### The build succeeds but `Results: 0 tests | 0 passed | ...`, no Cucumber scenarios ran, and the report is empty

```
[INFO]   - Results: 0 tests | 0 passed | 0 failed | 0 errors | 0 compromised | 0 pending | 0 aborted
```

- **Cause:** Maven's test plugin only runs classes whose names match its default patterns (`*Test`, `*Tests`, `Test*`, `*TestCase`). A Cucumber `@Suite` class called, for example, `CucumberSuite` or `CucumberTestSuite` is skipped without any warning. Reproduced with `CucumberSuite`.
- **Fix:** name the runner `RunCucumberTests` (or any name ending in `Test` or `Tests`), or add the name to `<includes>` in the surefire plugin configuration.

## The report is missing or wrong

### Tests failed, and there is no `target/site/serenity/index.html`

- **Cause:** the report is built by the Serenity Maven plugin in the `post-integration-test` phase, which Maven never reaches when tests fail. The per-test JSON files exist, but no HTML. Reproduced: after a failing scenario, `mvn verify` printed `There are test failures`, and `index.html` was absent.
- **Fix:** run the report goal after the failed build. This is the recommended way, because the build keeps its failing exit code:

```
mvn net.serenity-bdd.maven.plugins:serenity-maven-plugin:5.4.1:aggregate
```

(this produced `index.html`). The alternative is to let the build continue past test failures with `-Dmaven.test.failure.ignore=true`, but then the exit code is 0 even when tests fail, so a CI job must check results another way; avoid it unless you do. To find out what failed without any report, read the JSON files: `python3 scripts/results.py target/site/serenity` (see `test-results.md`).

### `Conflicting module versions. Module [groovy-xml is loaded in version 4.0.29 and you are trying to load version 3.0.9` / `Could not initialize class io.restassured.RestAssured`

- **Cause:** the pom pins REST-assured (`io.rest-assured:*`) or Groovy (`org.codehaus.groovy:groovy*`, Groovy 3) versions left over from an older Serenity. Serenity 5.4.1's REST support uses Groovy 4. Reproduced with REST-assured 4.5.1 and Groovy 3.0.9.
- **Fix:** delete those dependencies and let `serenity-rest-assured` bring its own. Seen when upgrading a real Serenity 2.4 project, which then passed 3 of 3 scenarios.

### The report shows more tests, or old failures, than the run had

- **Cause:** Serenity counts every outcome file in `target/site/serenity`, including ones left by earlier runs. Reproduced: after a full run (5 scenarios), a run filtered to 1 scenario, without cleaning, reported `Results: 5 tests`; after the directory was deleted it reported 1 (the verification script in the serenity-core repository (`docs/ai/skill`), case `stale-outcomes-counted`).
- **Fix:** start from a clean directory: `mvn clean verify`, or delete `target/site/serenity` (Gradle: `gradle clean test`, whose `clean` also clears it).

### "No BaseStepListener has been registered - are you running your test using the Serenity runners?"

```
java.lang.NullPointerException: No BaseStepListener has been registered - are you running your test using the Serenity runners?
```

- **Cause:** code that uses Serenity's reporting or Screenplay (for example `Serenity.recordReportData()`, an actor performing a task) runs outside a Serenity-managed test. In Cucumber the usual reason is that the Serenity plugin is not in the runner's `PLUGIN_PROPERTY_NAME`. Reproduced by removing the plugin.
- **Fix:** in Cucumber, add `net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel` to the plugins. In a JUnit 5 test, add `@ExtendWith(SerenityJUnit5Extension.class)`.

### A value defined in `serenity.conf` reads as `null`

- **Cause (two common ones):** (1) the value is under `environments { }`, and `environmentVariables.getProperty("app.url")` never returns those; (2) the file is not where Serenity looks: `serenity.conf` is read from `src/test/resources`, not the project root. Reproduced both (the verification script in the serenity-core repository (`docs/ai/skill`)).
- **Fix:** (1) `EnvironmentSpecificConfiguration.from(env).getOptionalProperty("app.url")`; (2) move the file to `src/test/resources/serenity.conf` and run `mvn clean`.

### Filtering by tag does nothing under Gradle: all scenarios still run

- **Cause:** Gradle does not pass `-D` options on the command line to the tests' JVM, so `gradle test -Dcucumber.filter.tags=@smoke` is ignored. Reproduced: 4 outcomes with the option, unchanged, and 1 once the build forwarded it.
- **Fix:** forward the option in `build.gradle`, as in the Cucumber page: `systemProperties System.properties.findAll { k, v -> k.toString().startsWith('cucumber.') }` inside `test { }`.

## The browser

### `NullPointerException: Cannot invoke "org.openqa.selenium.WebDriver.get(String)" because "this.driver" is null`

- **Cause:** a `@Managed WebDriver driver;` field in a **step library** (or any class other than the test class). `@Managed` only fills the field in the test class; elsewhere it stays null. Reproduced in a step library.
- **Fix:** extend `net.serenitybdd.core.steps.UIInteractionSteps` and use `getDriver()` (or use a page object, which gets the driver itself). Keep `@Managed` for the test class.

### `DriverConfigurationError: Unsupported browser type: chromee. Did you mean firefox?`

- **Cause:** `webdriver.driver` (system property or `serenity.conf`) names a browser Serenity does not know. Reproduced with a misspelling.
- **Fix:** use a supported name: `chrome`, `firefox`, `edge`, `safari`, `iexplorer`, `appium`, `remote`, ... (in this case the message guessed `firefox` for a misspelt `chrome`, so read the list rather than trusting the suggestion).

### `DriverConfigurationError: After several attempts, could not instantiate new WebDriver instance of type class org.openqa.selenium.chrome.ChromeDriver (Unable to obtain: chromedriver, error chromedriver must exist: /no/such/chromedriver`

- **Cause:** `webdriver.chrome.driver` points to a file that does not exist (a stale path from another machine or an old setup).
- **Also seen as:** `chromedriver must be executable: src/test/resources/webdriver/mac/chromedriver`, from an old `drivers { mac { webdriver.chrome.driver = "..." } }` block with a bundled binary (found upgrading a real Serenity 2.1 project; removing the block let Chrome start).
- **Fix:** remove the property so Selenium downloads or finds a matching driver by itself, or set it to a real path. Do not commit machine-specific absolute paths; if a driver must be supplied, see the OS-specific `drivers` settings in the driver configuration docs.

### `no such element: Unable to locate element: {"method":"xpath","selector":"input.new-todo"}` (Screenplay with Selenium)

- **Cause:** `Target.the(..).locatedBy("input.new-todo")`. Serenity reads the string as XPath when it compiles as an XPath expression, and `input.new-todo` does (a name test). So the element is searched as XPath and not found. `.new-todo`, `#id` and `[data-x=y]` are read as CSS.
- **Fix:** `Target.the(..).located(By.cssSelector("input.new-todo"))`, or a CSS selector that starts with `.`, `#` or `[`.

### `NoClassDefFoundError: io/cucumber/core/eventbus/EventBus` (and similar) after raising the Serenity version

- **Cause:** the project still pins an older Cucumber (4.x) and excludes `cucumber-core` from Serenity, as old starter projects did. Seen upgrading a real Serenity 2.1 project; not reproduced in the test projects here. After the pin and the exclusion were replaced by Cucumber 8.0.4 the project built; remember `mvn clean`, because old compiled classes can hide the next error (see the upgrading reference).
- **Fix:** use the Cucumber version Serenity brings (8.0.4 for 5.4.1) and remove the exclusion.

## Not reproduced here

These come up often in public questions. They are not covered by a tested fix, so use the driver configuration and Maven documentation, and do not rely on advice you cannot check:

- `Chrome failed to start: exited normally` / `session not created` after a Chrome update, `DevToolsActivePort file doesn't exist`, and browser start-up problems inside Docker or on Jenkins (they depend on the machine, user and container).
- Dependency convergence errors and `Could not resolve dependencies` (they depend on the project's other dependencies).
- `NoClassDefFoundError` after upgrading from Serenity 3 to 4 (for example `net.thucydides.model.util.EnvironmentVariables`): classes moved between packages. The upgrade guide in the documentation lists them.
- Slow report aggregation, wrong counts and reports from parallel runs.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_upgrading -->

# Upgrading to Serenity 5 and Recognising Old Code

Verified against Serenity **5.4.1**. The class counts come from the released jars, and the recipe was applied to five real projects.

## 1. What changed, by release

| Coming from | Java needed | What you must change |
|---|---|---|
| 4.x (tested: 4.2.34) | Java **17** (4.x classes are Java 11, 5.x classes are Java 17) | Versions only. All 1,587 public classes in the core, model, JUnit, Screenplay (including WebDriver and REST), REST-assured, Cucumber and Ensure jars have the same name and package in 5.4.1. A 4.2.8 project compiled with only a version bump. Align the JUnit and Cucumber versions with Serenity's (section 3). |
| 3.x (tested: 3.9.8) | Java 17 (3.x classes are Java 8) | Version bump, **511 of 1,574 classes moved** (section 2), the artifact changes in section 3, and the fixes for removed API found by the compiler. |
| 2.x | Java 17 | The same as 3.x, plus renamed Cucumber artifacts. |

Serenity 5.4.1 depends on **JUnit 6.1.3** and **Cucumber 8.0.4** (`../references/project-setup.md`).

## 2. Classes that moved (3.x to 5.x)

Of the 1,574 public classes in the 3.9.8 jars: 1,051 are unchanged, 511 moved to exactly one new place, 7 have a same-named class in more than one place, 5 are gone. Many `net.thucydides` packages are still correct (for example `net.thucydides.core.steps.ScenarioSteps`, `net.thucydides.core.pages.Pages`, and the 47 classes in `net.thucydides.core.steps` that did not move): only the classes in the table moved. All of `net.serenitybdd.screenplay.*`, `net.serenitybdd.core.pages`, `net.serenitybdd.junit.runners` and `net.thucydides.core.webdriver` (except two classes) kept their packages.

| Old package (3.x) | New package | Classes |
|---|---|---|
| `net.serenitybdd.core` | `net.serenitybdd.model` | `CurrentOS`, `IgnoredStepException`, `PendingStepException`, `SerenitySystemProperties`, `SkipStepException` |
| `net.serenitybdd.core.buildinfo` | `net.serenitybdd.model.buildinfo` | `BuildInfoProvider`, `BuildProperties`, `DriverCapabilityRecord`, `PropertyBasedDriverCapabilityRecord` |
| `net.serenitybdd.core.collect` | `net.serenitybdd.model.collect` | `NewList`, `NewMap`, `NewSet` |
| `net.serenitybdd.core.di` | `net.serenitybdd.model.di` | `DependencyInjector`, `ModelInfrastructure` |
| `net.serenitybdd.core.environment` | `net.serenitybdd.model.environment` | `ConfiguredEnvironment`, `EnvironmentSpecificConfiguration`, `UndefinedEnvironmentVariableException`, `UnknownEnvironmentException` |
| `net.serenitybdd.core.exceptions` | `net.serenitybdd.model.exceptions` | `CausesAssertionFailure`, `CausesCompromisedTestFailure`, `NoException`, `SerenityManagedException`, `TestCompromisedException`, `TheErrorType`, `UnrecognisedException` |
| `net.serenitybdd.core.history` | `net.serenitybdd.model.history` | `ClearDirectoryContents`, `FileSystemTestOutcomeSummaryRecorder`, `HistoricalFlagProvider`, `LeaveDirectoryContents`, `NewFailure`, `PrepareHistoryDirectory`, `PreviousTestOutcome`, `TestOutcomeSummaryRecorder` |
| `net.serenitybdd.core.i8n` | `net.serenitybdd.model.i8n` | `LocalisedLabels` |
| `net.serenitybdd.core.model` | `net.serenitybdd.model.model` | `FailureDetails`, `TestOutcomeName` |
| `net.serenitybdd.core.rest` | `net.serenitybdd.model.rest` | `RestMethod`, `RestQuery` |
| `net.serenitybdd.core.strings` | `net.serenitybdd.model.strings` | `FirstLine`, `Joiner` |
| `net.serenitybdd.core.tags` | `net.serenitybdd.model.tags` | `EnvironmentDefinedTags` |
| `net.serenitybdd.core.time` | `net.serenitybdd.model.time` | `InternalSystemClock`, `Stopwatch`, `SystemClock` |
| `net.serenitybdd.core.webdriver.driverproviders` | `net.serenitybdd.core.webdriver.servicepools` | `DriverServices` |
| `net.thucydides.core` | `net.thucydides.model` | `ThucydidesSystemProperty` |
| `net.thucydides.core.adapters` | `net.thucydides.model.adapters` | `JUnitStrategy`, `MultiStrategyAdapter`, `TestFramework`, `TestStrategyAdapter` |
| `net.thucydides.core.adapters.legacy` | `net.thucydides.model.adapters.legacy` | `DefaultJUnitAdapter`, `DefaultJUnitStrategy` |
| `net.thucydides.core.annotations` | `net.serenitybdd.annotations` | `AnnotatedDescription`, `At`, `BlurScreenshots`, `ClearCookiesPolicy`, `DefaultUrl`, `Description`, `DriverOptions`, `Feature`, `Fields`, `Issue`, `Issues`, `Managed`, `ManagedPages`, `Manual`, `NamedUrl`, `NamedUrls`, `Narrative`, `Pending`, `Reported`, `Screenshots`, `SectionNumber`, `Shared`, `SingleBrowser`, `Step`, `StepGroup`, `Steps`, `TestAnnotations`, `TestsRequirement`, `TestsRequirements`, `Title`, `UsePersistantStepLibraries`, `UserStoryCode`, `Version`, `WhenPageOpens`, `WithDriver`, `WithTag`, `WithTagValuesOf`, `WithTags` |
| `net.thucydides.core.batches` | `net.thucydides.model.batches` | `BatchManager`, `BatchStrategy`, `SystemVariableBasedBatchManager`, `TestCountBasedBatchManager`, `UnsupportedBatchStrategyException` |
| `net.thucydides.core.configuration` | `net.thucydides.model.configuration` | `BuildDirectoryProvider`, `FilePathParser`, `MavenBuildDirectory`, `MavenOrGradleBuildPath`, `SessionLocalTempDirectory`, `SystemPropertiesConfiguration`, `TimeoutConfiguration`, `TimeoutValue` |
| `net.thucydides.core.digest` | `net.thucydides.model.digest` | `Digest` |
| `net.thucydides.core.environment` | `net.thucydides.model.environment` | `MockEnvironmentVariables`, `SystemEnvironmentVariables`, `TestLocalEnvironmentVariables` |
| `net.thucydides.core.files` | `net.thucydides.model.files` | `TheDirectoryStructure` |
| `net.thucydides.core.images` | `net.thucydides.model.images` | `Refit`, `ResizableImage`, `ResizedImage` |
| `net.thucydides.core.issues` | `net.thucydides.model.issues` | `IssueKeyFormat`, `IssueTracking`, `SystemPropertiesIssueTracking` |
| `net.thucydides.core.logging` | `net.thucydides.model.logging` | `ConsoleColors`, `ConsoleEvent`, `ConsoleHeading`, `ConsoleHeadingStyle`, `ConsoleLoggingListener`, `LoggingLevel` |
| `net.thucydides.core.matchers` | `net.thucydides.model.matchers` | `BeanCollectionMatcher`, `BeanCountMatcher`, `BeanFieldMatcher`, `BeanMatcher`, `BeanMatcherAsserts`, `BeanMatchers`, `BeanPropertyMatcher`, `BeanUniquenessMatcher`, `BigDecimalValueMatcher`, `FileMatchers`, `InstantiatedBeanMatcher`, `MaxFieldValueMatcher`, `MinFieldValueMatcher`, `PublicThucydidesMatchers`, `ScreenshotHasFilenamesMatcher`, `SimpleValueMatcher`, `TestOutcomeResultsMatcher`, `ThucydidesMatchers` |
| `net.thucydides.core.matchers.dates` | `net.thucydides.model.matchers.dates` | `BeanFields`, `DateCollectionContainsSameDatesMatcher`, `DateComparator`, `DateIsAfterMatcher`, `DateIsBeforeMatcher`, `DateIsBetweenMatcher`, `DateIsSameAsMatcher`, `DateMatcherFormatter`, `DateMatchers`, `DateTimeCollectionContainsSameDatesMatcher`, `DateTimeIsAfterMatcher`, `DateTimeIsBeforeMatcher`, `DateTimeIsBetweenMatcher`, `DateTimeIsCloseToAsMatcher`, `DateTimeIsSameAsMatcher`, `DateTimeIsSameTimeAsMatcher`, `TimeIsCloseToAsMatcher` |
| `net.thucydides.core.model` | `net.thucydides.model.domain` | `AnnotatedStoryTitle`, `BadgeBackground`, `ContextIcon`, `DataSet`, `DataSetDescriptor`, `DataTable`, `DataTableRow`, `Downloadables`, `ErrorMessageFormatter`, `ExternalLink`, `FeatureTagAsDefined`, `HeuristicTestResult`, `LastElement`, `ManualTestEvidence`, `NumericalFormatter`, `OutcomeCounter`, `PackageBasedLeafRequirements`, `PathElement`, `PathElementResolver`, `ReportData`, `ReportNamer`, `ReportType`, `RequirementCache`, `Rule`, `RuleBackground`, `ScenarioOutcomeCounter`, `Stories`, `TakeScreenshots`, `TestCaseOrder`, `TestClassHierarchy`, `TestDuration`, `TestFailureException`, `TestOutcome`, `TestOutcomeAnnotationReader`, `TestOutcomeSummary`, `TestResult`, `TestResultComparison`, `TestResultList`, `TestStep`, `TestTag`, `TestTagCache`, `TestTags`, `TestType`, `TitleBuilder` |
| `net.thucydides.core.model.failures` | `net.thucydides.model.domain.failures` | `FailureAnalysis`, `FailureAnalysisConfiguration`, `RootCause` |
| `net.thucydides.core.model.features` | `net.thucydides.model.domain.features` | `ApplicationFeature` |
| `net.thucydides.core.model.featuretags` | `net.thucydides.model.domain.featuretags` | `FeatureFileStrategy`, `FeatureTagStrategy`, `FeatureTitle`, `NoFeatureStrategy`, `StoryFileStrategy` |
| `net.thucydides.core.model.flags` | `net.thucydides.model.domain.flags` | `Flag`, `FlagCounts`, `FlagProvider` |
| `net.thucydides.core.model.formatters` | `net.thucydides.model.domain.formatters` | `IssueExtractor`, `ReportFormatter`, `TestCoverageFormatter` |
| `net.thucydides.core.model.results` | `net.thucydides.model.domain.results` | `MergeStepResultStrategy`, `NextStepCompromisedStrategy`, `NextStepFailedStrategy`, `NextStepStatusTakesPriorityStrategy`, `NextStepWasSkippedStrategy`, `StepResultMergeStragegy` |
| `net.thucydides.core.model.screenshots` | `net.thucydides.model.domain.screenshots` | `Screenshot`, `ScreenshotPreferencesByClass` |
| `net.thucydides.core.model.stacktrace` | `net.thucydides.model.domain.stacktrace` | `FailureCause`, `RootCauseAnalyzer`, `StackTraceSanitizer` |
| `net.thucydides.core.output` | `net.thucydides.model.output` | `ResultsOutput`, `SpreadsheetResultsOutput` |
| `net.thucydides.core.reflection` | `net.thucydides.model.reflection` | `ClassFinder`, `FieldFinder`, `FieldSetter`, `FieldValue`, `MethodFinder`, `StackTraceAnalyser` |
| `net.thucydides.core.releases` | `net.thucydides.model.releases` | `ReleaseManager` |
| `net.thucydides.core.reports` | `net.thucydides.model.reports` | `AcceptanceTestFullReporter`, `AcceptanceTestLoader`, `AcceptanceTestReporter`, `AnsiEscapes`, `AsciiColors`, `FlagsAugmenter`, `FormatConfiguration`, `JiraUpdaterService`, `NumberOfThreads`, `OutcomeAugmenter`, `OutcomeFormat`, `OutcomeSummary`, `ReportGenerationFailedError`, `ReportLoadingFailedError`, `ReportOptions`, `ReportService`, `ReporterRuntime`, `ResultChecker`, `SystemReporterRuntime`, `TestOutcomeCounter`, `TestOutcomeLoader`, `TestOutcomeStream`, `TestOutcomes`, `TestOutcomesCompromised`, `TestOutcomesError`, `TestOutcomesFailures`, `ThucydidesReporter`, `UserStoryTestReporter` |
| `net.thucydides.core.reports.adaptors` | `net.thucydides.model.reports.adaptors` | `AdaptorService`, `TestOutcomeAdaptor`, `UnknownAdaptor` |
| `net.thucydides.core.reports.adaptors.common` | `net.thucydides.model.reports.adaptors.common` | `FilebasedOutcomeAdaptor` |
| `net.thucydides.core.reports.adaptors.lettuce` | `net.thucydides.model.reports.adaptors.lettuce` | `LettuceXUnitAdaptor` |
| `net.thucydides.core.reports.adaptors.specflow` | `net.thucydides.model.reports.adaptors.specflow` | `ScenarioSplitter`, `ScenarioStep`, `ScenarioStepReader`, `SpecflowAdaptor`, `SpecflowScenario`, `SpecflowScenarioTitleLine`, `SpecflowTableRow` |
| `net.thucydides.core.reports.adaptors.xunit` | `net.thucydides.model.reports.adaptors.xunit` | `BasicXUnitLoader`, `CouldNotReadXUnitFileException`, `DefaultXUnitAdaptor`, `XUnitLoader` |
| `net.thucydides.core.reports.adaptors.xunit.io` | `net.thucydides.model.reports.adaptors.xunit.io` | `XUnitFiles` |
| `net.thucydides.core.reports.adaptors.xunit.model` | `net.thucydides.model.reports.adaptors.xunit.model` | `Skip`, `TestCase`, `TestError`, `TestException`, `TestSuite` |
| `net.thucydides.core.reports.csv` | `net.thucydides.model.reports.csv` | `CSVReporter` |
| `net.thucydides.core.reports.history` | `net.thucydides.model.reports.history` | `DateProvider`, `ProgressSnapshot`, `SystemDateProvider`, `TestResultSnapshot` |
| `net.thucydides.core.reports.html` | `net.thucydides.model.reports.html` | `ContextIconFormatter`, `CucumberCompatibleFilter`, `CucumberTagConverter`, `DescriptionSplitter`, `ExampleTable`, `MarkdownRendering`, `ReportNameProvider`, `RequirementsFilter`, `ResultCounts`, `ResultIconFormatter`, `ScenarioResultCounts`, `TagExclusions`, `TagFilter`, `TagMatch`, `TestOutcomeFilter` |
| `net.thucydides.core.reports.integration` | `net.thucydides.model.reports.integration` | `TestStepFactory` |
| `net.thucydides.core.reports.json` | `net.thucydides.model.reports.json` | `AScenarioHasNoNameException`, `JSONConverter`, `JSONTestOutcomeReporter` |
| `net.thucydides.core.reports.json.gson` | `net.thucydides.model.reports.json.gson` | `ClassTypeAdapter`, `CollectionAdapter`, `FileDeserializer`, `FileSerializer`, `GsonJSONConverter`, `GsonPreviousOutcomeConverter`, `InterfaceAdapter`, `OptionalTypeAdapter`, `StackTraceElementDeserializer`, `StackTraceElementSerializer`, `ZonedDateTimeAdapter` |
| `net.thucydides.core.reports.junit` | `net.thucydides.model.reports.junit` | `JUnitXMLConverter`, `JUnitXMLOutcomeReporter` |
| `net.thucydides.core.reports.matchers` | `net.thucydides.model.reports.matchers` | `TestOutcomeMatchers` |
| `net.thucydides.core.reports.remoteTesting` | `net.thucydides.model.reports.remoteTesting` | `BrowserStackLinkGenerator`, `LinkGenerator`, `RemoteTestingLinkManager` |
| `net.thucydides.core.reports.templates` | `net.thucydides.model.reports.templates` | `FreeMarkerTemplateManager`, `FreemarkerReportTemplate`, `ReportTemplate`, `TemplateManager`, `TemplateMergeException` |
| `net.thucydides.core.reports.util` | `net.thucydides.model.reports.util` | `CopyDirectory` |
| `net.thucydides.core.reports.xml` | `net.thucydides.model.reports.xml` | `NotAThucydidesReportException`, `TestOutcomeConverter` |
| `net.thucydides.core.requirements` | `net.thucydides.model.requirements` | `AbstractRequirementsTagProvider`, `AllRequirements`, `BaseRequirementsService`, `ChildrenFirstOrderedMap`, `ClasspathRequirementsProviderService`, `CoreTagProvider`, `CouldNotLoadRequirementsException`, `DefaultCapabilityTypes`, `DefaultRequirements`, `DisabledRequirementsStore`, `ExcludedUnrelatedRequirementTypes`, `FeatureFilePath`, `FileSystemRequirements`, `FileSystemRequirementsService`, `FileSystemRequirementsStore`, `FileSystemRequirementsTagProvider`, `JSONRequirementsTree`, `MultiSourceRequirementsService`, `OverridableTagProvider`, `PackageAnnotationBasedTagProvider`, `PackageRequirementsTagProvider`, `ParentRequirementProvider`, `ParentRequirementsProvided`, `PathStartsWith`, `ReleaseProvider`, `RequirementAncestry`, `RequirementPersister`, `RequirementTypesProvider`, `Requirements`, `RequirementsList`, `RequirementsMerger`, `RequirementsPath`, `RequirementsProvided`, `RequirementsProviderService`, `RequirementsService`, `RequirementsStore`, `RequirementsTagProvider`, `RequirementsTree`, `RootDirectory`, `SearchForFilesOfType`, `SearchForFilesWithName`, `SerenityTestCaseFinder`, `TestOutcomeRequirementsTagProvider`, `WindowsFriendly` |
| `net.thucydides.core.requirements.annotations` | `net.thucydides.model.requirements.annotations` | `ClassInfoAnnotations`, `NarrativeFinder` |
| `net.thucydides.core.requirements.classpath` | `net.thucydides.model.requirements.classpath` | `AnnotatedTags`, `ChildElementAdder`, `ClassNarrative`, `LeafRequirementAdder`, `NarrativeTitle`, `NonLeafRequirementsAdder`, `PackageInfoClass`, `PackageInfoNarrative` |
| `net.thucydides.core.requirements.model` | `net.thucydides.model.requirements.model` | `CustomFieldValue`, `Example`, `ExampleBuilder`, `FeatureBackgroundNarrative`, `FeatureType`, `LoadedNarrative`, `NarrativeReader`, `OverviewReader`, `Requirement`, `RequirementBuilderNameStep`, `RequirementBuilderTypeStep`, `RequirementDefinition`, `RequirementTree`, `RequirementTypeAt`, `RequirementsConfiguration` |
| `net.thucydides.core.requirements.model.cucumber` | `net.thucydides.model.requirements.model.cucumber` | `AnnotatedFeature`, `BlankRowResultIcon`, `CucumberParser`, `DescriptionWithScenarioReferences`, `ExampleRowResultIcon`, `ExampleTableInMarkdown`, `FeatureFileAnaysisErrors`, `FeatureFileChecker`, `FeatureFileFinder`, `IdentifiedExampleTable`, `IdentifiedScenario`, `InvalidFeatureFileException`, `NamedExampleTable`, `NamedScenario`, `NarrativeFromCucumberComments`, `ReferencedExampleTable`, `ReferencedScenario`, `RenderedExampleTable`, `RowResultIcon`, `ScenarioDisplayOption`, `ScenarioReport`, `SummaryRowResultIcon`, `URIResource`, `UnknownExampleTable`, `UnknownScenario` |
| `net.thucydides.core.requirements.reports` | `net.thucydides.model.requirements.reports` | `AcceptanceCriteriaRequirmentCounter`, `ChildRequirementCounter`, `CompoundDuration`, `ExampleOutcome`, `ExampleOutcomes`, `FileSystemRequirmentsOutcomeFactory`, `MultipleSourceRequirmentsOutcomeFactory`, `PercentageRequirementCounter`, `RenderMarkdown`, `ReportBadges`, `RequirementOutcome`, `RequirementsOutcomeFactory`, `RequirementsOutcomes`, `RequirementsOutcomesOfTypeCache`, `RequirementsPercentageFormatter`, `RequirementsProportionCounter`, `RequirmentCalculator`, `ScenarioOutcome`, `ScenarioOutcomes`, `ScenarioSummaryOutcome`, `SingleScenarioOutcome`, `SubrequirementsCount`, `SubrequirementsPercentageCount`, `SubrequirementsProportionCount` |
| `net.thucydides.core.requirements.reports.cucumber` | `net.thucydides.model.requirements.reports.cucumber` | `FeatureCache`, `FeatureFileScenarioOutcomes`, `OptionalAnnotatedFeature`, `RenderCucumber` |
| `net.thucydides.core.requirements.tree` | `net.thucydides.model.requirements.tree` | `Node` |
| `net.thucydides.core.resources` | `net.thucydides.model.resources` | `FileResources`, `ResourceCopyingError`, `ResourceList` |
| `net.thucydides.core.screenshots` | `net.serenitybdd.annotations` | `BlurLevel` |
| `net.thucydides.core.screenshots` | `net.thucydides.model.screenshots` | `ScreenshotAndHtmlSource`, `ScreenshotException` |
| `net.thucydides.core.statistics` | `net.thucydides.model.statistics` | `AtomicTestCount`, `TestCount` |
| `net.thucydides.core.statistics.service` | `net.thucydides.model.statistics.service` | `AnnotationBasedTagProvider`, `ClasspathTagProviderService`, `ContextTagProvider`, `FeatureStoryTagProvider`, `InjectedTagProvider`, `JUnitTagProviderStrategy`, `TagProvider`, `TagProviderFilter`, `TagProviderService`, `TagProviderStrategy` |
| `net.thucydides.core.steps` | `net.thucydides.model.steps` | `AnnotatedStepDescription`, `ExecutedStepDescription`, `FailingManualTestException`, `MetaField`, `ReplaceField`, `ScreenplayInspector`, `StepArgumentWriter`, `StepFailure`, `StepFailureException`, `StepListener`, `TestFailureCause`, `TestSourceType`, `TestStatus` |
| `net.thucydides.core.steps.di` | `net.thucydides.model.steps.di` | `ClasspathDependencyInjectorService`, `DependencyInjectorService` |
| `net.thucydides.core.steps.events` | `net.serenitybdd.cucumber.events` | `SetTestManualEvent` |
| `net.thucydides.core.tags` | `net.thucydides.model.tags` | `BreadcrumbTagFilter`, `OutcomeTagFilter`, `TagConverters`, `TagScanner`, `Taggable` |
| `net.thucydides.core.util` | `net.thucydides.model.util` | `Acronym`, `ConfigCache`, `EnvironmentVariables`, `FileSystemUtils`, `Inflection`, `Inflector`, `LocalPreferences`, `MultipleInflection`, `NameConverter`, `PropertiesLocalPreferences`, `PropertiesUtil`, `TagInflector`, `TestResources`, `VersionProvider` |
| `net.thucydides.core.webdriver` | `net.thucydides.model.webdriver` | `Configuration`, `WebdriverAssertionError` |

The annotations are the ones most code touches: `Step`, `Steps`, `Managed`, `DefaultUrl`, `Title`, `Narrative`, `Pending`, `WithTag`, `Issue` and the rest of `net.thucydides.core.annotations` are now in **`net.serenitybdd.annotations`**. `EnvironmentVariables` is in `net.thucydides.model.util`; `EnvironmentSpecificConfiguration` is in `net.serenitybdd.model.environment`.

Ambiguous: `Story` (`net.serenitybdd.annotations.Story` for the annotation, `net.thucydides.model.domain.Story` for the model class), `CastMember` (`net.serenitybdd.screenplay.annotations.CastMember` for Screenplay), `Release`, `PathElements` and `TagParser`: decide by what the code uses it for. Gone: the WebDriverManager integration classes (`WebDriverManagerSetup`, `WebDriverManagerEnhancer`, `DefaultWebDriverManagerEnhancer`; drivers are found by Selenium itself now), `MergedRequirementList` and `RecordStepResultEvent`.

**Rewriting imports automatically:** the `fix_imports.py` script in the serenity-core repository (`docs/ai/skill/upgrade-checks`) rewrites every class in the table (imports, fully qualified names, wildcard imports) and lists the ambiguous and removed classes it found, for a person to decide.

## 3. The upgrade recipe

Each step was needed by at least one of the five tested projects.

1. **Java 17** or later for the build and the tests.
2. **Set the Serenity version** everywhere it appears (`serenity.version`, the Maven plugin version, `serenity.cucumber.version`).
3. **Artifact names.** `serenity-cucumber4`, `serenity-cucumber5` and `serenity-cucumber6` stopped at 2.1.2, 2.2.6 and 2.6.0: use **`serenity-cucumber`**. The JUnit 4 runner (`net.serenitybdd.junit.runners.SerenityRunner`) lives in **`serenity-junit`**, which a 3.x project got through `serenity-core`: add it, with JUnit 4.13.2, if you keep JUnit 4 tests. `serenity-jbehave` has no 5.x release (its last version is 1.46.0): JBehave stories need migrating to Cucumber first. Check any other `serenity-*` artifact on Maven Central before relying on it.
4. **Remove versions that Serenity manages.** Pins that were right for the old Serenity break the new one at run time, not at compile time:
   - Cucumber: a pinned `cucumber-java`, `cucumber-junit` or an `<exclusion>` of `cucumber-core` gives `NoClassDefFoundError: io/cucumber/core/eventbus/EventBus` (a project with Cucumber 4.8.1 and the exclusion). Use 8.0.4, or none, and delete the exclusion.
   - REST-assured and Groovy: pinned `io.rest-assured:*` and `org.codehaus.groovy:groovy*` (Groovy 3) give `Conflicting module versions. Module [groovy-xml is loaded in version 3.0.6 and you are trying to load version 4.0.29`. Delete them; `serenity-rest-assured` brings the right ones.
   - JUnit: see the troubleshooting reference ("conflicting versions"); import the JUnit BOM.
5. **Imports.** Run `fix_imports.py` (section 2).
6. **Configuration clean-up** (`../references/configuration.md`):
   - Delete a `drivers { mac { webdriver.chrome.driver = "src/test/resources/webdriver/..." } }` block of bundled driver binaries. A 2020 chromedriver cannot drive a current Chrome, and the symptom is `Could not instantiate class org.openqa.selenium.chrome.ChromeDriver ... chromedriver must be executable`. With the block removed, Chrome started.
   - `screenshooter=shutterbug` needs the separate `serenity-shutterbug` artifact; otherwise the test fails with `Unable to instantiate screen shooter net.serenitybdd.screenshots.shutterbug.ShutterbugScreenShooter`. Delete the line (default screenshots) or add the artifact.
7. **Compile from clean:** `mvn clean test-compile`. Without `clean`, Maven keeps classes compiled against the old libraries: a `cucumber.api.CucumberOptions` import compiled for as long as the stale class file existed, and the runner then silently ran **0 scenarios**.
8. **Fix removed or renamed API** (the compiler lists it). Found in the tested projects: `InputField.called("x")` and `PageElement.called("x")` (gone by 3.9.8) became `InputField.withNameOrId("x")` and `PageElement.withNameOrId("x")`. `cucumber.api.CucumberOptions` became `io.cucumber.junit.CucumberOptions`, and `cucumber.api.java.en.*` became `io.cucumber.java.en.*` (the `cucumber.api` package does not exist in Cucumber 8).
9. **Run the tests.** Failures that remain may belong to the application under test: three of the five old projects' remaining failures were a changed page (a search box and a to-do input that no longer exist).

## 4. Evidence: five real projects

| Project (Serenity version) | Result |
|---|---|
| REST starter with Cucumber (2.4.51) | Version, `serenity-cucumber6` to `serenity-cucumber`, 2 class references rewritten, REST-assured and Groovy pins removed: **3 of 3 scenarios pass**. |
| Cucumber 4 starter (2.1.12) | Version, 4 class references rewritten, Cucumber 4.8.1 and the exclusion replaced by 8.0.4, runner import fixed, bundled drivers removed: compiles and the 4 scenarios run in Chrome; they fail on the DuckDuckGo search box, which has changed. |
| Screenplay with JUnit 4 and Cucumber, todo app (3.3.0) | Version, `serenity-junit` added, 6 class references rewritten: compiles; 4 of 10 scenarios pass, 6 fail on a to-do input that one of the sample apps no longer has. |
| Screenplay quickstart (3.0.2) | Compiles after `called` became `withNameOrId`; the run needed the `shutterbug` line removed, then fails on Wikipedia's changed search box (`element not interactable`). |
| Toolshop (4.2.8) | Compiles with only the version bump. Its tests were not run. |

## 5. JUnit 4 and the old Cucumber runner still work

You do not have to move to JUnit 5. With `serenity-junit` and JUnit 4.13.2, `@RunWith(SerenityRunner.class)` with `@Steps` ran on 5.4.1 (1 test passed), and so did `@RunWith(CucumberWithSerenity.class)` with `@CucumberOptions(features = ..., glue = ...)` from `io.cucumber.junit` (3 scenarios passed). Use the JUnit 5 extension and the JUnit Platform suite for new code (`../references/cucumber.md`); do not rewrite a working JUnit 4 suite only to follow it. Keep one style per project.

## 6. Recognising old code in generated or copied examples

| Old | Current |
|---|---|
| `import net.thucydides.core.annotations.{Step,Steps,Managed,DefaultUrl,...}` | `net.serenitybdd.annotations.*` |
| `net.thucydides.core.util.EnvironmentVariables` | `net.thucydides.model.util.EnvironmentVariables` |
| `net.serenitybdd.core.environment.EnvironmentSpecificConfiguration` | `net.serenitybdd.model.environment.EnvironmentSpecificConfiguration` |
| `serenity-cucumber4/5/6`, `cucumber.api.*` | `serenity-cucumber`, `io.cucumber.*` |
| `InputField.called(..)`, `PageElement.called(..)` | `InputField.withNameOrId(..)`, `PageElement.withNameOrId(..)` |
| `drivers { os { webdriver.chrome.driver = ... } }` with bundled binaries | nothing: leave driver selection to Serenity and Selenium |
| `serenity-jbehave` stories | no 5.x release: migrate to Cucumber |
| `@RunWith(SerenityRunner.class)` | still valid with `serenity-junit` and JUnit 4; for JUnit 5 use `@ExtendWith(SerenityJUnit5Extension.class)` |
| `net.thucydides.core.steps.ScenarioSteps`, `net.thucydides.core.pages.Pages` | **not old**: still in those packages |

## 7. Not covered

Gradle plugin version history, Serenity 1.x, Appium and mobile modules, the Spring, JIRA and cloud-provider modules, and Selenium 3 to 4 API changes outside Serenity's own classes.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_test_results -->

# Reading Test Results Without the HTML Report

Verified against Serenity **5.4.1** by running a passing and a failing project: the files, the fields and the script were all checked.

An AI assistant, a script or a CI step can read the outcome of a run from files, not from the HTML report or the Maven console. Serenity writes them to `target/site/serenity/`.

## What is written, and when

| File | Written | Contains |
|---|---|---|
| `<64 hex characters>.json`, one per test | **While the tests run.** It exists after a failed build, when no HTML report was generated | The full outcome of one test: title, result, requirement path, the step tree, and the failure |
| `SERENITY-JUNIT-<same 64 hex characters>.xml`, one per test | While the tests run | The same test in standard JUnit XML, for CI tools |
| `index.html`, the other `.html` pages, `summary.txt` | **Only if the report was generated.** `mvn verify` stops at a failed test, so after a failure they are missing (see the troubleshooting page) | The HTML report; `summary.txt` has the totals as prose |
| `serenity-summary.json` | Only if the optional JSON summary report is enabled (below) | Totals and one entry per scenario |

The JSON file name is a 64-character hash. It was the same on every run of the same test, but it tells you nothing about the test, so read the `title`, `testCaseName` and `methodName` fields inside.

So after any run, including a failed one, **read `target/site/serenity/*.json`**. Do not wait for `index.html` and do not scrape it.

## The quickest way: `scripts/results.py`

The script is in the skill (`scripts/results.py`) and in the serenity-core repository at `docs/ai/skill/serenity-bdd/scripts/results.py`; copy it into the project if the skill is not installed.

```bash
python3 <skill>/scripts/results.py target/site/serenity          # totals, a line per test, details of each failure
python3 <skill>/scripts/results.py target/site/serenity --json   # the same as one JSON document
```

It prints the totals, one line per test (result, title, requirement path, outcome file), and for each failed test the failing step, the exception type and message, the first stack frame in the project's own code, and the outcome file to open for the full detail. The exit code is 1 if any test failed, errored or was compromised, and 2 if there are no outcome files. A run of more than 40 tests lists only the tests that did not pass unless you add `--all`. It reads only the JSON files, uses no dependencies, and is a different tool from `outline.py` (which judges the wording and structure of the report, not the result of the run).

When the failure is an assertion or a wait (for example Screenplay `WaitUntil` or `should(seeThat(..))`), Serenity may not mark any step as failed. The script then says so and gives the last step recorded; the stack frame names the line of your test that failed.

## The fields of an outcome file

```text
title, name          the scenario title as the report shows it
result               SUCCESS, FAILURE, ERROR, COMPROMISED, PENDING, SKIPPED, IGNORED ...
testCaseName         class name; methodName: the test method (JUnit)
userStory            { path, storyName, ... }  the requirement it belongs to (package path or feature file)
featureTag, tags     the feature and any @tags
startTime, duration  duration in milliseconds
testSource           JUnit5, Cucumber ...
testSteps            the step tree: [ { number, description, result, duration, children: [ ... ] } ]
```

For a test that did not pass, the file also has:

```text
testFailureCause     { errorType, message, stackTrace: [ { declaringClass, methodName, fileName, lineNumber } ] }
testFailureClassname the exception class
testFailureMessage   the exception message
testFailureSummary   "FAILURE;<class>;<message>;<file>"
```

and the step that failed (when one is marked) has `exception` with the same `errorType`, `message` and `stackTrace`. REST steps carry `restQuery` with `method`, `path`, `requestHeaders`, `content`, `statusCode`, `responseHeaders` and `responseBody`, which is often all that is needed to see why an API test failed. Nested steps are in `children`.

The step tree is long for big tests (every request, with its response body, is in it). Read the summary first and open one outcome file only for a test you are investigating.

## Optional: a JSON summary of the whole run

The `serenity-json-summary-report` artifact writes one `serenity-summary.json` for the run. It is not enabled by default. Add it as a dependency of the Serenity Maven plugin and ask for the report:

```xml
<plugin>
  <groupId>net.serenity-bdd.maven.plugins</groupId>
  <artifactId>serenity-maven-plugin</artifactId>
  <version>${serenity.version}</version>
  <dependencies>
    <dependency>
      <groupId>net.serenity-bdd</groupId>
      <artifactId>serenity-json-summary-report</artifactId>
      <version>${serenity.version}</version>
    </dependency>
  </dependencies>
  <!-- keep your existing executions -->
</plugin>
```

```bash
mvn serenity:reports -Dserenity.reports=json-summary
```

`serenity-summary.json` has `report`, `results` (`counts`: total, success, failure, error, pending, skipped ...; durations), `resultsByFeature` (each feature with its scenarios: `title`, `result` and for each outcome an `errorMessage`), `frequentFailures`, `unstableFeatures`, `coverage` and `tags`. It has the failure message of each scenario but not the failing step, the stack trace or the link to the outcome file, so for investigating a failure use the outcome files (or `results.py`). The goal ran after a failed build and produced it from the outcome files, with no HTML report.

## What this is not

- The outcome file format is Serenity's own. It is stable in practice but is not a published contract, so read the fields listed above and ignore the rest.
- The JUnit XML (`SERENITY-JUNIT-*.xml`) and Maven's `target/surefire-reports/*.xml` are the standard formats; use them when a tool expects JUnit XML.

## What an assistant should do after a run

1. Run the build (`mvn verify`). If it fails, do not stop at the console output.
2. Run `results.py` on `target/site/serenity`. Fix compile errors from the console first; they produce no outcome files.
3. For each failed test, read the message and the stack frame in your own code, and decide whether the test or the application is wrong. If the application is wrong, say so rather than editing the test to pass.
4. When all tests pass, build the report (`mvn verify` does it when the tests pass) and review it with `outline.py` and the review checklist.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).


---

<!-- https://serenity-bdd.github.io/docs/ai/ai_review_checklist -->

# Reviewing Tests and Living Documentation

Used by the `serenity-test-reviewer` agent after tests are written, and by anyone reviewing Serenity tests. Style-neutral: it applies to Page Objects, Screenplay and Cucumber, Selenium, Playwright and REST. Do not ask for a different style; judge the tests inside the style they use.

Read `living-documentation.md` first for what Serenity does with titles, steps and structure.

## What to look at

1. The test sources (and the feature files).
2. The report as a reader sees it: run the tests, then `python3 <skill>/scripts/outline.py <project>/target/site/serenity`. If the tests cannot run here, review the sources and say the report was not seen.
3. The task the user asked for, to check that the tests cover it.

## The checks

Each check is PASS, WEAK or FAIL. Quote the line or title, and write the replacement.

### A. Intent: does a reader learn the business rule?
- **A1** The scenario title states the rule or outcome in business words (not `testCheckout1`, not `shouldReturn201`, not a description of clicks).
- **A2** The scenario is about one behaviour. A title with "and" covering two rules should be two scenarios.
- **A3** It is clear why the behaviour matters or what the user gets (a title like "A reader sees an order number after paying" says it; "Checkout works" does not).
- **A4** Cucumber: the feature has a short business description; scenario outlines use meaningful example column names.

### B. Steps: business language
- **B1** Steps read as a narrated story with who/what, in the project's domain terms.
- **B2** No selectors, ids, URLs, sleeps, driver calls or HTTP codes in step text, titles or the test body (they belong inside page objects, tasks, step libraries, step definitions). In a REST test, a status code is fine inside the check, not as the step name.
- **B3** The final step/check states the business expectation ("the confirmation shows an order number"), and the check really proves that (see D1).
- **B4** One level of abstraction per scenario: business tasks at the top, mechanics inside them.

### C. Organisation: easy to navigate
- **C1** Scenarios are grouped by function (package/folder per capability, one class or feature file per feature, or `@Epic/@Feature/@Story`), not one big class and not by technical layer.
- **C2** The report tree (from `outline.py`) reads like a table of contents of what the application does. Names are business phrases, with no class name showing ("When signing in test": the class needs `@DisplayName`) and no duplicates.
- **C3** One grouping method for the whole project (not package structure mixed with `@Feature` annotations).
- **C4** Description files exist where an area needs explaining (Cucumber `readme.md`, or `src/test/resources/stories/<package path>/readme.md`) and are short and about the business.

### D. Test quality
- **D1** The assertions check what the title claims, with specific expected values from the task (not "page loaded", not `isNotNull`, not the same value read back from the test's own input). Ask: if the application broke in the way the title describes, would this test fail?
- **D2** No fixed sleeps. Waits are on a condition (Serenity waits, `WaitUntil`, Playwright auto-wait).
- **D3** Scenarios are independent: no shared mutable state between tests, no dependence on order, no static fields for scenario state.
- **D4** Test data is visible where it matters (the value a rule depends on is in the scenario, not hidden in a helper), and secrets are not hard-coded beyond what the task gave.
- **D5** No duplicated flows: repeated step sequences are a task, step method or Background.
- **D6** It follows the project's existing style, driver and runner, and does not mix styles in one test. The project builds and the tests were run or the reason is stated.
- **D7** Covers what was asked, including the negative case when the task mentioned one, and nothing invented beyond the application's described behaviour.

## Output

```
VERDICT: READY | NEEDS CHANGES

LIVING DOCUMENTATION AS A READER SEES IT
<the outline, trimmed>

FINDINGS (worst first)
1. [FAIL B2] src/test/java/.../CheckoutTest.java:31: step "Click #place-order" shows a selector
   Change to: Task.where("{0} places the order", ...)
...

WHAT IS GOOD
<one or two lines>
```

READY means no FAIL and at most two WEAK, and the report was seen. Be specific and brief: every finding says where it is and what to write instead. Do not edit files; the author applies the changes, and a second review follows if there were FAILs.

## Examples

These files compile against Serenity 5.4.1 (Playwright examples: 5.3.11).


---

<!-- https://serenity-bdd.github.io/docs/tutorials/first_test -->

# Your First Web Test
In this tutorial you'll write your very first Serenity BDD test, using JUnit 5 and Selenium. We'll start out simple, then explore some of the features that make Serenity BDD rather special. So let's get started!

## Pre-requisites
To run this tutorial, you will need a few things installed on your machine:
* **Java**: Serenity BDD is a Java library, so you'll need a recent JDK installed. JDK 17 or higher should be fine.
* **A Java IDE**: You'll also need a Java Development Environment such as IntelliJ or Eclipse (and a working knowledge of Java).
* **Git**: We'll be using a starter project on Github, and the sample code for this project lives on Github too, so I'll be assuming you have a basic understanding of Git.

## Creating Your First Serenity BDD Project

We will be using the **[Serenity BDD with JUnit](https://github.com/serenity-bdd/serenity-junit-screenplay-starter)** template project to get a simple project up and running quickly.

:::note
We'll be using a fairly conventional test automation style in this tutorial, using action classes and page objects. In the next tutorial, we'll see how to do all this using the Screenplay Pattern.
:::

Go to the [project template page on Github](https://github.com/serenity-bdd/serenity-junit-pageobjects-starter) and click on [Use This Template](https://github.com/serenity-bdd/serenity-junit-pageobjects-starter/generate).

![](img/junit-template.png)

## Writing a simple test

Let's start with a simple test. We will run a simple search for the keyword "Cucumber" on the DuckDuckGo search engine:
![](img/duckduckgo.png)

First of all, we create a new package for our DuckDuckGo tests. The Serenity test reports mirror the directory structure we use to organize our tests, so it helps to make the structure and the package name meaningful.

![](img/initial-directory-structure.png)

### Basic test structure

Now we create a new test class (let's call it "WhenSearchingByKeyword"), and an empty test case (we can call it "theKeywordShouldAppearInTheResultsSidebar").

```java
package starter.duckduckgo;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)              
class WhenSearchingByKeyword {              

    @Test
    void theKeywordShouldAppearInTheResultsSidebar() {

    }
}
```

:::caution
There are a few things to note here:
  - The `@ExtendWith` annotation tells JUnit that this test uses Serenity - don't forget this annotation or your test won't be recognised as a Serenity test
  - The `@Test` annotation uses the `org.junit.jupiter.api.Test` class, from JUnit 5. Be careful not to get this mixed up with the JUnit 4 annotation of the same name (`org.junit.Test`), otherwise your test won't run.
:::

### Setting up WebDriver

Next, let's add the code Serenity will need to work. First of all, since this will be a web test, we need to add a WebDriver field. Serenity manages the WebDriver lifecycle for us (it even downloads the WebDriver binaries for us), so all we need to do is to declare a `WebDriver` field, and annotate it with the `@Managed` annotation. In the code below, I've also added the `driver` attribute and the `options` attribute to ensure the browser opens in headless mode:

```java
import net.serenitybdd.annotations.Managed;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.WebDriver;

@ExtendWith(SerenityJUnit5Extension.class)
class WhenSearchingByKeyword {

    @Managed(driver = "chrome", options = "headless")
    WebDriver driver;

    @Test
    void theKeywordShouldAppearInTheResultsSidebar() {

    }
}
```

This driver will be used throughout the test, including in any page objects or action classes (more on these later) that are created as part of the test.

### Creating Action Classes

We could simply start using this `driver` variable to interact with the browser. That would work fine. But keeping your test code well organised and well structured is essential to keeping maintenance costs down. And Serenity BDD gives us a number of ways to do this.

One of the simplest ways to do this is called _Action Classes_. Action Classes are small, reusable classes with methods that encapsulate key user actions.

For example, we could break this test down into three steps:
  - Navigate to the DuckDuckGo home page
  - Search by the keyword "Cucumber"
  - Check that the main topic heading on the result page is "Cucumber"

Let's start with the first action: navigating to the DuckDuckGo home page. Create a new class called `NavigateActions` in the same package and add the following:

```java
import net.serenitybdd.core.steps.UIInteractions;

public class NavigateActions extends UIInteractions {
    public void toTheDuckDuckGoSearchPage() {
        openUrl("https://duckduckgo.com/");
    }
}
```

A UI Interactions class is a class containing methods that can interact with a web page. When we extend the `UIInteractions` class, Serenity will automatically inject the `@Managed` WebDriver instance we saw earlier whenever we use an instance of this class in our tests.

The `UIInteractions` class gives you access to a range of methods that you can use to interact with the page. For example, as we can see in this example, the `openUrl()` method is used to open a page at a specified URL.

Next, let's move on to the second action, where we need to search for a specific term. Create a new class called `SearchActions`, and make it extend the `UIInteractions` class.

```java
import net.serenitybdd.core.steps.UIInteractions;

public class SearchActions extends UIInteractions {}
```

Now add a method to search by a given keyword, called `byKeyword`, which will do the actual search. Inside this method, we can use the `$` notation to search for elements on the page using CSS or XPath locators, like this:

```java
import net.serenitybdd.core.steps.UIInteractions;
import org.openqa.selenium.Keys;

public class SearchActions extends UIInteractions {
    public void byKeyword(String keyword) {
      $("#searchbox_input").sendKeys(keyword, Keys.ENTER);
    }
}
```

### Creating a Page Component class

The third step of our test is to read the title of the search results sidebar and check that it is the value we expect.

![](img/result-module-title.png)

We can do this with a Page Component object. Page Components (which extend the `PageComponent` class) are similar to action classes, but focus on reading information from a particular part of a web page, rather than modeling user interactions.

To read the title of the sidebar on this screen, create a new class called `SearchResultSidebar` with the following code:

```java
import net.serenitybdd.core.pages.PageComponent;

public class SearchResultSidebar extends PageComponent {
    public String heading() {
        return $("[data-testid=about] h2").getText();
    }
}
```

Once again we are locating the element using the `$` operator and a CSS selector, and returning the text value of the element we find.

### Using Action Classes and Page Components In The Test

Now that we've created action classes for the first two steps, let's add them to our test. Serenity recognises action classes and page component objects and instantiates them automatically with the @Managed WebDriver instance, so we simply need to declare them as class fields, and then use them in our test.

```java
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import net.serenitybdd.annotations.Managed;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.WebDriver;
import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
class WhenSearchingByKeyword {

    @Managed(driver = "chrome", options = "headless")
    WebDriver driver;

    NavigateActions navigate;
    SearchActions search;
    SearchResultSidebar searchResultSidebar;

    @Test
    void theKeywordShouldAppearInTheResultsSidebar() {
        navigate.toTheDuckDuckGoSearchPage();
        search.byKeyword("Cucumber");
        assertThat(searchResultSidebar.heading()).isEqualTo("Cucumber");
    }
}
```

### Reporting the steps

We now have a working test. You can run it from within your IDE, or by running `mvn verify` on the command line.

However, there is one more step we can do. Serenity BDD is a living documentation tool, which means it aims to document not only what tests are executed, but how they are executed.

We can control how Serenity reports each method in a `UIInteractions` class using the `@Step` annotation. When you place a `@Step` annotation on a `UIInteractions` method, this method will appear in the Serenity reports whenever it is called.

Let's see how it works. Update the `NaviagateActions` and `SearchActions` classes to include the `@Step` annotations like this:

```java
import net.serenitybdd.annotations.Step;
import net.serenitybdd.core.steps.UIInteractions;

public class NavigateActions extends UIInteractions {
    @Step("Navigate to the home page")
    public void toTheDuckDuckGoSearchPage() {
        openUrl("https://duckduckgo.com/");
    }
}
```

```java
import net.serenitybdd.annotations.Step;
import net.serenitybdd.core.steps.UIInteractions;
import org.openqa.selenium.Keys;

public class SearchActions extends UIInteractions {

    @Step("Search for '{0}'")
    public void byKeyword(String keyword) {
      $("#searchbox_input").sendKeys(keyword, Keys.ENTER);
    }
}
```

### Reporting on assertions

The last step of our test is an assertion. We can report on the assertion by wrapping it in the `Serenity.reportThat()` method, using a Lambda expression for the actual assertion:

```java
@Test
void theKeywordShouldAppearInTheResultsSidebar() {
    navigate.toTheDuckDuckGoSearchPage();
    search.byKeyword("Cucumber");

    Serenity.reportThat("The keyword should appear in the sidebar heading",
            () -> assertThat(searchResultSidebar.heading()).isEqualTo("Cucumber")
    );
}
```


## Generating the reports

Let's run the tests and see what the reports look like. Delete the `wikipedia` package (we don't need the sample tests anymore), and run `mvn verify` from the command line. You should see an output along the following lines:

```bash
$ mvn verify
...
[INFO]  SERENITY TESTS: SUCCESS
[INFO] -----------------------------------------
[INFO] | Tests executed         | 1
[INFO] | Tests passed           | 1
[INFO] | Tests failed           | 0
[INFO] | Tests with errors      | 0
[INFO] | Tests compromised      | 0
[INFO] | Tests aborted          | 0
[INFO] | Tests pending          | 0
[INFO] | Tests ignored/skipped  | 0
[INFO] ------------------------ | --------------
[INFO] | Total Duration         | 5s 626ms
[INFO] | Fastest test took      | 5s 626ms
[INFO] | Slowest test took      | 5s 626ms
[INFO] -----------------------------------------
[INFO]
[INFO] SERENITY REPORTS
[INFO]   - Full Report: file:///Users/john/Projects/Serenity/serenity-new-documentation/serenity-users-guide/sample-code/docs-starter-tutorial/target/site/serenity/index.html
[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M5:verify (default) @ serenity-junit-starter ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  21.729 s
[INFO] Finished at: 2021-11-30T11:27:29Z
[INFO] ------------------------------------------------------------------------
```

Now open the `index.html` file in the `target/site/serenity` directory. You should see something like this:

![](img/report-home.png)

Click on the "Test Results" tab and open the "When Searching By Keyword" scenario. This should show you the step-by-step details of your test:

![](img/report-keyword-search.png)

## Conclusion

Congratulation! You've written your first Serenity BDD test, and seen a little of what Serenity BDD can do!


---

<!-- https://serenity-bdd.github.io/docs/tutorials/screenplay -->

# Your First Screenplay Scenario

The Screenplay Pattern is a way to write clean, readable, scalable test automation modeled around the user. 

Screenplay builds on good software engineering principles such as the Single Responsibility Principle, the Open-Closed Principle, and effective use of Layers of Abstraction. It encourages good testing habits and well-designed test suites that are easy to read, easy to maintain and easy to extend, enabling teams to write more robust and more reliable automated tests more effectively.

In this section, we will show you how to write your first Screenplay scenario using Serenity BDD. You will learn how to write a simple scenario for the well-known [TodoMVC](http://todomvc.com) project.

![](img/journey-todo-app.png)

## Pre-requisites
To run this tutorial, you will need a few things installed on your machine:
* **Java**: Serenity BDD is a Java library, so you'll need a recent JDK installed. JDK 17 or higher should be fine.
* **A Java IDE**: You'll also need a Java Development Environment such as IntelliJ or Eclipse (and a working knowledge of Java).
* **Git**: We'll be using a starter project on Github, and the sample code for this project lives on Github too, so I'll be assuming you have a basic understanding of Git.  You will also need a Git client installed on your computer.

## Introducing the Screenplay Pattern

The goal of the Screenplay pattern is to help you write cleaner, more readable, more maintainable test automation code for any domain. With Screenplay, your tests use an intuitive, readable style like the following:
```java
        wendy.attemptsTo(
                Navigate.toTheHomePage(),
                Search.byKeyword("Everest"),
                Ensure.that(DisplayedArticle.firstHeading()).isEqualTo("Mount Everest")
        );
```

As you can see here, Screenplay uses a user-centric model, where we describe _actors_ who interact with an application in various ways to perform _tasks_ that help them achieve their goals. Actors have _abilities_, such as the ability to interact with a web browser or query a database, that help them perform these tasks. Actors can also answer _questions_ about the state of the system, so that we can check whether a feature is behaving the way we would expect it to.

![](img/screenplay-model.svg)


## Creating a Screenplay project

### Using the Serenity template projects
The quickest way to start a new Screenplay project is to clone one of the starter projects. For this tutorial, we will start with the [Serenity JUnit Screenplay Starter project](https://github.com/serenity-bdd/serenity-junit-screenplay-starter), which uses Serenity Screenplay and JUnit 5.

:::tip
This starter project has a sample Screenplay test in the `src/test/java/starter/wikipedia` folder. You won't need this code for this tutorial so you can safely delete it.
:::

### The project directory structure
We will use some simple conventions to organise our test classes, based on the standard Maven project structure you can see here:

![](img/screenplay-directory-layout.png)

Our test code will be stored in two folders, underneath `src/test/java/todomvc`. The first directory named `features` will contain our test classes. The second, `screenplay`, will contain our Screenplay classes. Screenplay classes are designed to be highly modular and reusable, and often appear in many tests, so it makes sense to keep them separate from the tests themselves.

Serenity organises JUnit test results based on the package structure we use, so we need to tell it the name of the root package where our tests will live. We do this in the `serenity.conf` file in the `src/test/resources` folder. Open this file and add the following line:

```
serenity.test.root = todomvc.features
```

## Writing your first scenario

### Creating the test case 
For our first scenario, we will simply add a 'to do' item (say, "Buy some milk") to an empty list. 

Start by creating a new empty test case under the `src/test/java/todomvc/features` package like this:

```java
package todomvc.features;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
class AddNewTodos {

    @Test
    @DisplayName("Add a todo item to an empty list")
    void addToEmptyList() {
    }
}
```

The line `@ExtendWith(SerenityJUnit5Extension.class)` indicates that this is a Serenity BDD test.

### Introducing the actor

Screenplay uses an actor-centric approach, where our tests describe _actors_, who represent actual users of our application, and the actions they perform. 

In a Serenity BDD JUnit test, we can use the `@CastMember` annotation to declare an actor like this:

```java
    @CastMember(name = "Toby")
    Actor toby;
```

This will instantiate a new actor (called Toby) for our test, and assign a webdriver instance that he can use to interact with our application. 

### Actors perform tasks and interactions
In a Screenplay test, everything starts with the actor, who interacts with the system under test to achieve their goals. In this case, the first thing Toby needs to do is to open the TodoMvc application at a given URL. We do this by calling the `attemptsTo()` method on the `Actor` class. The `attemptsTo()` method takes a list of actions that the actor needs to perform. We call these actions _performables_. We generally talk about two types of _performables_:
  - _Interactions_, where the actor interacts directly with the application (Click a button or Open a URL), and
  - _Tasks_, which are groups of interactions that the actor needs to perform to achieve some goal (Add an item to the cart or purchase an item).

An example of a simple Interaction is the `Open.url()` interaction, which opens a given URL. 

```java
Open.url("https://todomvc.com/examples/angularjs/#/")
```

In our "add a todo item to an empty list" test, the first step will be for Toby to open the browser on the TodoMVC application home page. We can do this with the following code:

```java
@Test
@DisplayName("Add a todo item to an empty list")
void addToEmptyList() {
    toby.attemptsTo(
        Open.url("https://todomvc.com/examples/angularjs/#/")
    );
}
```

### Actors can interact with a web application

The next thing we need to do is to enter a value into the input field on the TodoMVC home page that you can see here:

![](img/todomvc-input.png)

To enter a value into a field, we can use the `Enter` interaction class. This field can be located using a CSS locator like _".new-todo"_. So to enter the value into this field, we can use the following interaction:

```java
Enter.theValue("Buy some milk").into(".new-todo")
```

There is no submit button on this form. To add the item to the list, we need to press the _RETURN_ key. We can do this by adding the `thenHit()` method, like this:

```java
Enter.theValue("Buy some milk").into(".new-todo").thenHit(Keys.RETURN)
```

When we add this to our test, we get the following:

```java
@Test
@DisplayName("Add a todo item to an empty list")
void addToEmptyList() {
    toby.attemptsTo(
        Open.url("https://todomvc.com/examples/angularjs/#/"),
        Enter.theValue("Buy some milk").into(".new-todo").thenHit(Keys.RETURN)
    );
}
```

### Actors can ask about the state of the system

Once Toby hits RETURN, the item will be added to the todo list, as we can see here:

![](img/todo-list-1-item.png)

Now we need to check that the item we entered was successfully added to this list. In Screenplay we do this using _Questions_. A Question is a class that knows how to retrieve a specific piece of information about the state of the application. This could be the value of a text field, the result of a REST API call, or even the result of a database query. 

In this case, we can identify the names of the todo items in the list using a CSS locator such as ".todo-list li". So a _question_ to retrieve each of the todo items displayed on the page might look like this:
```java
Text.ofEach(".todo-list li")
```

A question does nothing by itself - just as we need an actor to perform an interaction, we also need an actor to ask a question. 

One way we do this is to use the `asksFor()` method, like this:

```java
        var todos = toby.asksFor(Text.ofEach(".todo-list label"));
```

If we add an AssertJ assertion to check that the list contains the value we expect, our completed test will look like the following:

```java
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.actions.Enter;
import net.serenitybdd.screenplay.actions.Open;
import net.serenitybdd.screenplay.annotations.CastMember;
import net.serenitybdd.screenplay.questions.Text;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.Keys;

import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
class AddNewTodos {

    @CastMember(name = "Toby")
    Actor toby;

    @Test
    @DisplayName("Add a todo item to an empty list")
    void addToEmptyList() {
        toby.attemptsTo(
                Open.url("https://todomvc.com/examples/angularjs/#/"),
                Enter.theValue("Buy some milk").into(".new-todo").thenHit(Keys.RETURN)
        );
        var todos = toby.asksFor(Text.ofEach(".todo-list li"));
        assertThat(todos).containsExactly("Buy some milk");
    }
}

```

## Generating the reports

Let's run the tests and see what the reports look like. Just run `mvn clean verify` from the command line. You should see an output along the following lines:

```bash
$ mvn verify
...
[INFO] -----------------------------------------
[INFO]  SERENITY TESTS: SUCCESS
[INFO] -----------------------------------------
[INFO] | Test cases executed    | 1
[INFO] | Tests executed         | 1
[INFO] | Tests passed           | 1
[INFO] | Tests failed           | 0
[INFO] | Tests with errors      | 0
[INFO] | Tests compromised      | 0
[INFO] | Tests aborted          | 0
[INFO] | Tests pending          | 0
[INFO] | Tests ignored/skipped  | 0
[INFO] ------------------------ | --------------
[INFO] | Total Duration         | 7s 292ms
[INFO] | Fastest test took      | 7s 292ms
[INFO] | Slowest test took      | 7s 292ms
[INFO] -----------------------------------------
[INFO]
[INFO] SERENITY REPORTS
[INFO]   - Full Report: file:///C:/Users/johns/projects/todomvc-screenplay-tutorial/target/site/serenity/index.html
[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M5:verify (default) @ serenity-junit-screenplay-starter ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  21.660 s
[INFO] Finished at: 2022-04-04T13:34:26+01:00
[INFO] ------------------------------------------------------------------------
```

Now open the `index.html` file in the `target/site/serenity` directory using a web browser, and navigate to the Test Results tab. Open up the "Add a todo item to an empty list" scenario. Notice how the report renders the actor's actions almost word-for-word:

![](img/screenplay-report-1.png)


## Conclusion

You have now seen just a little of the power of the Screenplay pattern. To learn more about what you can do with the Screenplay pattern, check out [the full Screenplay Documentation](../screenplay/screenplay_fundamentals).


---

<!-- https://serenity-bdd.github.io/docs/tutorials/rest -->

# Your First API Test

In the previous tutorial we looked at how to write a simple web test with Serenity BDD. But Serenity isn't just for web tests: Serenity BDD also provides tight integration with [Rest Assured](https://rest-assured.io/), a popular open source library for testing REST APIs.

## Pre-requisites
To run this tutorial, you will need a few things installed on your machine:
* **Java**: Serenity BDD is a Java library, so you'll need a recent JDK installed. JDK 17 or higher should be fine.
* **Maven**: You will need Maven 3 or higher installed in your computer.  This acts as a build tool that also downloads the dependencies while building.
* **A Java IDE**: You'll also need a Java Development Environment such as IntelliJ or Eclipse (and a working knowledge of Java).
* **Git**: We'll be using a starter project on Github, and the sample code for this project lives on Github too, so I'll be assuming you have a basic understanding of Git.

## Creating your project

We will be using the **[Serenity BDD Junit Starter](https://github.com/serenity-bdd/serenity-junit-starter)** template project to get a simple project up and running quickly.

This project comes with a sample test based on Junit 5 already implemented for our reference.  For now, we are going to ignore that and start writing a new test from scratch.

Go to the [project template page on Github](https://github.com/serenity-bdd/serenity-junit-starter) and click on [Use This Template](https://github.com/serenity-bdd/serenity-junit-starter/generate).

## Deleting the unnecessary files

Just to make sure that the starter template's sample files do not interfere with our experience in this tutorial, **delete** the `src/test/java/starter/wikipedia` directory.

## Adding the Serenity RestAssured Dependency

Open the `pom.xml` file in the root directory and add the following lines in the `<dependencies>` section, similar to the ones already in the file. 

```xml
 <dependency>
      <groupId>net.serenity-bdd</groupId>
      <artifactId>serenity-rest-assured</artifactId>
      <version>${serenity.version}</version>
      <scope>test</scope>
  </dependency>
```

## Enabling Detailed HTML reports
When we use the template's default configuration, we get only a single-page HTML report.  We want to generate a detailed HTML report in this tutorial.  So, let us **delete** the following line from the `pom.xml` file.

```xml
  <reports>single-page-html</reports>
  <!-- DELETE the line above. Yes, delete it! -->
```
You can find this in the configuration section of `serenity-maven-plugin` plugin.

## The project directory structure
We will use some simple conventions to organise our feature files and the supporting Java classes, based on the standard Maven project structure outlined below:

```
├───src
│   ├───main
│   │   └───java
│   │       └───starter
│   └───test
│       ├───java
│       │   └───starter
│       │       └───petstore
│       └───resources
```

Here are some points to note about the directory structure.
1. Since we will test the publicly available [Pet Store API](https://petstore.swagger.io/), we will not have any code in the `src/main` directory.
2. We will re-use (from the template) the contents that are already there in the `src/test/resources/` directory.
3. We will create a new directory `petstore` under `src/test/java/starter` directory to store our test class and its helpers.

## Writing an API test
Let us start with writing our API test.  In this test, we will test the [`GET /pet/{petId}`](https://petstore.swagger.io/#/pet/getPetById) API.  This API will return a pet when you give its `id` in the URL.

However, we cannot call this API directly without any `id`.  Hence, our test needs to first create a Pet and get its `id` before it calling the `GET /pet/{petId}` API end point.

In other words, we could write our test in the `Given-When-Then` format as follows.

```Gherkin
Given Kitty is available in the pet store
When I ask for a pet using Kitty's ID
Then I get Kitty as result
```

### Basic test structure

Now we create a new test class (let's call it `WhenFetchingAlreadyAvailablePet`), and an empty test case (we can call it `fetchAlreadyAvailablePet`).

```java
package starter.petstore;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;


@ExtendWith(SerenityJUnit5Extension.class)
public class WhenFetchingAlreadyAvailablePet {

  @Test
  public void fetchAlreadyAvailablePet() {
    
  }
}
```

:::caution
There are a few things to note here:
- The `@ExtendWith` annotation tells JUnit that this test uses Serenity - don't forget this annotation or your test won't be recognised as a Serenity test
- The `@Test` annotation uses the `org.junit.jupiter.api.Test` class, from JUnit 5. Be careful not to get this mixed up with the JUnit 4 annotation of the same name (`org.junit.Test`), otherwise your test won't run.
- Note that the name of the test class starts with `When`.  This is one of the ways to make sure it is recognized as a test to be run in the Maven build process.  See the `pom.xml` file's `configuration` section for `maven-failsafe-plugin` for more details on this.

:::

### Creating Action Classes

We could simply start writing the entire test's code inside our `fetchAlreadyAvailablePet()` method. That would work fine. But keeping your test code well organised and well-structured is essential to keeping maintenance costs down. And Serenity BDD gives us a number of ways to do this.

One of the simplest ways to do this is called _Action Classes_. Action Classes are small, reusable classes with methods that encapsulate key user actions.  We will use these classes to call the HTTP APIs.

For example, we could break our `fetchAlreadyAvailablePet()` test down into three steps:
1. **Arrange (Given):** Set the stage to call the GET api by pre-loading the pet named 'Kitty' using a HTTP POST call documented [here](https://petstore.swagger.io/#/pet/addPet).
2. **Act (When):** Call the API under test using the ID of 'Kitty'
3. **Assert (Then):** Check that the API returns a pet with name 'Kitty'

Let us create an action class named `PetApiActions` with the following skeleton code, in the same `petstore` package where the test lives.

```java
package starter.petstore;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import net.serenitybdd.core.steps.UIInteractions;


public class PetApiActions extends UIInteractions {

    @Given("Kitty is available in the pet store")
    public Long givenKittyIsAvailableInPetStore() {
              
    }

    @When("I ask for a pet using Kitty's ID: {0}")
    public void whenIAskForAPetWithId(Long id) {
        
    }

    @Then("I get Kitty as result")
    public void thenISeeKittyAsResult() {
       
    }
}

```

:::caution

**Points to note**
1. Since we want to use the ID generated by the API in our upcoming step, we return the ID as a Long return value.
2. We extend the `UIInteractions` class that comes with the Serenity BDD to help us interact with APIs.

:::

Let's start with implementing the first action: Setting the stage by pre-creating a pet with name `"Kitty"` by calling the POST API.

Since we need to create a Java object to hold the `Pet`, we can create a class `Pet.java` under `starter.petstore` package with the following code.

```java
package starter.petstore;

public class Pet {
    private String name;
    private String status;
    private Long id;

    public Pet(String name, String status, Long id) {
        this.name = name;
        this.status = status;
        this.id = id;
    }

    public Pet(String name, String status) {
        this.name = name;
        this.status = status;
    }

    public String getName() {
        return this.name;
    }

    public String getStatus() {
        return this.status;
    }

    public Long getId() {
        return id;
    }

    public void setName(String name) {
        this.name = name;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    public void setId(Long id) {
        this.id = id;
    }
}
```

Now that we have a way to represent a Pet in our code, let us write our first action in function `givenKittyIsAvailableInPetStore()`  of the class `PetApiActions`.

```java
package starter.petstore;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import io.restassured.http.ContentType;
import io.restassured.mapper.ObjectMapperType;
import static net.serenitybdd.rest.SerenityRest.given;
import net.serenitybdd.core.steps.UIInteractions;


import static net.serenitybdd.rest.SerenityRest.*;

public class PetApiActions extends UIInteractions {

    @Given("Kitty is available in the pet store")
    public Long givenKittyIsAvailableInPetStore() {

        Pet pet = new Pet("Kitty", "available");

        Long newId = given()
                .baseUri("https://petstore.swagger.io")
                .basePath("/v2/pet")
                .body(pet, ObjectMapperType.GSON)
                .accept(ContentType.JSON)
                .contentType(ContentType.JSON).post().getBody().as(Pet.class, ObjectMapperType.GSON).getId();
        return newId;
    }

    @When("I ask for a pet using Kitty's ID: {0}")
    public void whenIAskForAPetWithId(Long id) {

    }

    @Then("I get Kitty as result")
    public void thenISeeKittyAsResult() {

    }
}

```

Next, let us write the implementation for the `whenIAskForAPetWithId` function.  This will include just calling the GET API that needs to be tested.

```java
    @When("I ask for a pet using Kitty's ID: {0}")
    public void whenIAskForAPetWithId(Long id) {
        when().get("/" + id);
    }
```
:::caution

**Points to note**
1. In the `get` method call above, the `baseUri` and `basePath` from the `given()` section is reused.  This is why you did not have to repeat those details in this method.
2. Since we are using the `id` as an input parameter, we are using `{0}` in the description so that it can appear in our reports.   
:::

Next, let us write the implementation for the `thenISeeKittyAsResult` method as follows.

```java
    @Then("I get Kitty as result")
    public void thenISeeKittyAsResult() {
        then().body("name", Matchers.equalTo("Kitty"));
    }

```

Putting everything together, the `PetApiActions.java` file looks as follows.

```java
package starter.petstore;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import io.restassured.http.ContentType;
import io.restassured.mapper.ObjectMapperType;
import static net.serenitybdd.rest.SerenityRest.then;
import static net.serenitybdd.rest.SerenityRest.when;
import static net.serenitybdd.rest.SerenityRest.given;
import net.serenitybdd.core.steps.UIInteractions;
import org.hamcrest.Matchers;

import static net.serenitybdd.rest.SerenityRest.*;

public class PetApiActions extends UIInteractions {

    @Given("Kitty is available in the pet store")
    public Long givenKittyIsAvailableInPetStore() {

        Pet pet = new Pet("Kitty", "available");

        Long newId = given()
                .baseUri("https://petstore.swagger.io")
                .basePath("/v2/pet")
                .body(pet, ObjectMapperType.GSON)
                .accept(ContentType.JSON)
                .contentType(ContentType.JSON).post().getBody().as(Pet.class, ObjectMapperType.GSON).getId();
        return newId;
    }

    @When("I ask for a pet using Kitty's ID: {0}")
    public void whenIAskForAPetWithId(Long id) {
        when().get("/" + id);
    }

    @Then("I get Kitty as result")
    public void thenISeeKittyAsResult() {
        then().body("name", Matchers.equalTo("Kitty"));
    }

}


```

### Completing our test case

Now that we have our Actions class ready, let us finish writing our test case in the `WhenFetchingAlreadyAvailablePet` class.

```java
package starter.petstore;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
public class WhenFetchingAlreadyAvailablePet {

    Long newPetId = null;
    PetApiActions petApi;

    @Test
    public void fetchAlreadyAvailablePet() {
        newPetId = petApi.givenKittyIsAvailableInPetStore();
        petApi.whenIAskForAPetWithId(newPetId);
        petApi.thenISeeKittyAsResult();
    }
}
```

Let us try running the Maven build to see the result.  If the API works as expected, we expect the test to pass and a detailed HTML report to be generated.

Run the following command in a terminal or command prompt.

```bash
mvn clean verify
```

Once the command completes, you can see output similar to the following.

```
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 10.009 s - in starter.petstore.WhenFetchingAlreadyAvailablePet
[INFO] 
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

...
...
...

[INFO] -----------------------------------------
[INFO]  SERENITY TESTS: SUCCESS
[INFO] -----------------------------------------
[INFO] | Test cases executed    | 1
[INFO] | Tests executed         | 1
[INFO] | Tests passed           | 1
[INFO] | Tests failed           | 0
[INFO] | Tests with errors      | 0
[INFO] | Tests compromised      | 0
[INFO] | Tests aborted          | 0
[INFO] | Tests pending          | 0
[INFO] | Tests ignored/skipped  | 0
[INFO] ------------------------ | --------------
[INFO] | Total Duration         | 9s 212ms
[INFO] | Fastest test took      | 9s 212ms
[INFO] | Slowest test took      | 9s 212ms
[INFO] -----------------------------------------
[INFO]
[INFO] SERENITY REPORTS
[INFO]   - Full Report: file:///C:/Users/calib/source-codes/temp/serenity-junit-starter/target/site/serenity/index.html
[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M5:verify (default) @ serenity-junit-starter ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  39.104 s
[INFO] Finished at: 2022-09-02T17:33:14+05:30
[INFO] ------------------------------------------------------------------------

```

Yes, the test passed and the build is successful now.  We have managed to test our API successfully 🎉

## Reporting and Living Documentation

If you notice carefully, the output of the `mvn clean verify` command informed us that a report is created in `target/site/serenity/index.html`

When you open this file in a web browser, you see a beautiful report like this.

![Report Home Page](img/rest-report-home.png)

You can also find the test-wise results detailing the steps in the `Stories` tab, detailing the REST API calls.

![Report](img/rest-report-stories.jpg)

If you want to look at the exact details used in the HTTP requests, you can click on the link circled in the above screenshot.  This will show you the details as shown below.

![Report with HTTP requests](img/rest-report-http-requests.png)

Feel free to navigate the links in this report and look around.

## Conclusion
In this tutorial, you created your own API test cases and ran them using Serenity BDD to generate a beautiful report.


---

<!-- https://serenity-bdd.github.io/docs/tutorials/rest-api-testing -->

# Comprehensive REST API Testing with Serenity BDD

This tutorial provides a complete guide to testing REST APIs with Serenity BDD, covering everything from basic requests to advanced patterns like authentication, error handling, schema validation, and hybrid UI+API testing.

All examples use real, publicly available testing APIs that you can use to practice.

## Testing APIs Used

| API | URL | Purpose |
|-----|-----|---------|
| JSONPlaceholder | https://jsonplaceholder.typicode.com | Free fake API for basic CRUD |
| ReqRes | https://reqres.in | User management with auth examples |
| Restful-Booker | https://restful-booker.herokuapp.com | Hotel bookings with token auth |

## Project Setup

### Maven Dependencies

```xml
<properties>
    <serenity.version>5.4.1</serenity.version>
</properties>

<dependencies>
    <!-- Core Serenity -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-core</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity REST Assured integration -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-rest-assured</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity Screenplay REST (for Screenplay pattern) -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay-rest</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- JUnit 5 -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-junit5</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- JSON Schema validation -->
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>json-schema-validator</artifactId>
        <version>5.3.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

### Gradle Dependencies

```groovy
dependencies {
    testImplementation "net.serenity-bdd:serenity-core:5.4.1"
    testImplementation "net.serenity-bdd:serenity-rest-assured:5.4.1"
    testImplementation "net.serenity-bdd:serenity-screenplay-rest:5.4.1"
    testImplementation "net.serenity-bdd:serenity-junit5:5.4.1"
    testImplementation "io.rest-assured:json-schema-validator:5.3.2"
}
```

### Configuration (serenity.conf)

```hocon
# Base URLs for different environments
restapi {
    jsonplaceholder = "https://jsonplaceholder.typicode.com"
    reqres = "https://reqres.in/api"
    booker = "https://restful-booker.herokuapp.com"
}

# Request logging
serenity {
    logging = VERBOSE
}

# REST Assured settings
restassured {
    # Log all requests and responses
    log.all = true
}
```

---

## Part 1: Basic REST Operations

### Simple GET Request

Let's start with the simplest possible API test - fetching a resource:

```java
package com.example.api;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.rest.SerenityRest;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import static net.serenitybdd.rest.SerenityRest.given;
import static org.hamcrest.Matchers.*;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Basic REST Operations")
class BasicRestTest {

    private static final String BASE_URL = "https://jsonplaceholder.typicode.com";

    @Test
    @DisplayName("Should fetch a single user")
    void shouldFetchSingleUser() {
        given()
            .baseUri(BASE_URL)
        .when()
            .get("/users/1")
        .then()
            .statusCode(200)
            .body("id", equalTo(1))
            .body("name", equalTo("Leanne Graham"))
            .body("email", equalTo("Sincere@april.biz"));
    }

    @Test
    @DisplayName("Should fetch all users")
    void shouldFetchAllUsers() {
        given()
            .baseUri(BASE_URL)
        .when()
            .get("/users")
        .then()
            .statusCode(200)
            .body("size()", equalTo(10))
            .body("name", hasItems("Leanne Graham", "Ervin Howell"));
    }
}
```

### POST Request - Creating Resources

```java
@Test
@DisplayName("Should create a new post")
void shouldCreateNewPost() {
    String requestBody = """
        {
            "title": "My New Post",
            "body": "This is the content of my post",
            "userId": 1
        }
        """;

    given()
        .baseUri(BASE_URL)
        .contentType("application/json")
        .body(requestBody)
    .when()
        .post("/posts")
    .then()
        .statusCode(201)
        .body("title", equalTo("My New Post"))
        .body("id", notNullValue());
}
```

### Using POJOs for Request/Response

Create model classes for cleaner code:

```java
// Post.java
public class Post {
    private Integer id;
    private String title;
    private String body;
    private Integer userId;

    // Default constructor for JSON deserialization
    public Post() {}

    public Post(String title, String body, Integer userId) {
        this.title = title;
        this.body = body;
        this.userId = userId;
    }

    // Getters and setters
    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public String getBody() { return body; }
    public void setBody(String body) { this.body = body; }
    public Integer getUserId() { return userId; }
    public void setUserId(Integer userId) { this.userId = userId; }
}
```

```java
@Test
@DisplayName("Should create post using POJO")
void shouldCreatePostUsingPojo() {
    Post newPost = new Post("POJO Title", "Content from POJO", 1);

    Post createdPost = given()
        .baseUri(BASE_URL)
        .contentType("application/json")
        .body(newPost)
    .when()
        .post("/posts")
    .then()
        .statusCode(201)
        .extract()
        .as(Post.class);

    assertThat(createdPost.getTitle()).isEqualTo("POJO Title");
    assertThat(createdPost.getId()).isNotNull();
}
```

### PUT and PATCH Requests

```java
@Test
@DisplayName("Should update entire post with PUT")
void shouldUpdatePostWithPut() {
    Post updatedPost = new Post("Updated Title", "Updated Body", 1);

    given()
        .baseUri(BASE_URL)
        .contentType("application/json")
        .body(updatedPost)
    .when()
        .put("/posts/1")
    .then()
        .statusCode(200)
        .body("title", equalTo("Updated Title"));
}

@Test
@DisplayName("Should partially update post with PATCH")
void shouldPartiallyUpdateWithPatch() {
    given()
        .baseUri(BASE_URL)
        .contentType("application/json")
        .body("{\"title\": \"Patched Title\"}")
    .when()
        .patch("/posts/1")
    .then()
        .statusCode(200)
        .body("title", equalTo("Patched Title"))
        .body("body", notNullValue()); // Original body preserved
}
```

### DELETE Request

```java
@Test
@DisplayName("Should delete a post")
void shouldDeletePost() {
    given()
        .baseUri(BASE_URL)
    .when()
        .delete("/posts/1")
    .then()
        .statusCode(200);
}
```

---

## Part 2: Screenplay Pattern for API Testing

The Screenplay pattern provides a more maintainable, actor-centric approach:

### Setting Up Actors with API Abilities

```java
package com.example.api.screenplay;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.rest.abilities.CallAnApi;
import net.serenitybdd.screenplay.rest.interactions.*;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.ExtendWith;

import static net.serenitybdd.screenplay.rest.questions.ResponseConsequence.seeThatResponse;
import static org.hamcrest.Matchers.*;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Screenplay REST API Tests")
class ScreenplayRestTest {

    private static final String BASE_URL = "https://jsonplaceholder.typicode.com";

    Actor alex;

    @BeforeEach
    void setUp() {
        alex = Actor.named("Alex the API tester")
                    .whoCan(CallAnApi.at(BASE_URL));
    }

    @Test
    @DisplayName("Should fetch user with Screenplay")
    void shouldFetchUserWithScreenplay() {
        alex.attemptsTo(
            Get.resource("/users/1")
        );

        alex.should(
            seeThatResponse("User details are correct",
                response -> response
                    .statusCode(200)
                    .body("name", equalTo("Leanne Graham"))
            )
        );
    }

    @Test
    @DisplayName("Should create post with Screenplay")
    void shouldCreatePostWithScreenplay() {
        alex.attemptsTo(
            Post.to("/posts")
                .with(request -> request
                    .contentType("application/json")
                    .body(new Post("Screenplay Post", "Content", 1))
                )
        );

        alex.should(
            seeThatResponse("Post was created",
                response -> response
                    .statusCode(201)
                    .body("title", equalTo("Screenplay Post"))
            )
        );
    }
}
```

### Creating Reusable Tasks

Encapsulate API operations in reusable tasks:

```java
// tasks/CreatePost.java
package com.example.api.tasks;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.rest.interactions.Post;
import net.serenitybdd.annotations.Step;
import com.example.api.model.Post;

import static net.serenitybdd.screenplay.Tasks.instrumented;

public class CreatePost implements Task {

    private final Post post;

    public CreatePost(Post post) {
        this.post = post;
    }

    public static CreatePost withDetails(String title, String body, int userId) {
        return instrumented(CreatePost.class, new Post(title, body, userId));
    }

    public static CreatePost withTitle(String title) {
        return instrumented(CreatePost.class, new Post(title, "Default body", 1));
    }

    @Override
    @Step("{0} creates a new post titled '#post.title'")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Post.to("/posts")
                .with(request -> request
                    .contentType("application/json")
                    .body(post)
                )
        );
    }
}
```

```java
// tasks/FetchUser.java
package com.example.api.tasks;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.rest.interactions.Get;
import net.serenitybdd.annotations.Step;

import static net.serenitybdd.screenplay.Tasks.instrumented;

public class FetchUser implements Task {

    private final int userId;

    public FetchUser(int userId) {
        this.userId = userId;
    }

    public static FetchUser withId(int userId) {
        return instrumented(FetchUser.class, userId);
    }

    @Override
    @Step("{0} fetches user with ID #userId")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Get.resource("/users/{id}")
               .with(request -> request.pathParam("id", userId))
        );
    }
}
```

Using the tasks:

```java
@Test
@DisplayName("Should use custom tasks for API operations")
void shouldUseCustomTasks() {
    alex.attemptsTo(
        CreatePost.withDetails("Task-based Post", "Content from task", 1)
    );

    alex.should(
        seeThatResponse("Post was created successfully",
            response -> response.statusCode(201)
        )
    );

    alex.attemptsTo(
        FetchUser.withId(1)
    );

    alex.should(
        seeThatResponse("User was retrieved",
            response -> response
                .statusCode(200)
                .body("name", notNullValue())
        )
    );
}
```

### Creating Reusable Questions

```java
// questions/TheUser.java
package com.example.api.questions;

import net.serenitybdd.rest.SerenityRest;
import net.serenitybdd.screenplay.Question;
import com.example.api.model.User;

public class TheUser {

    public static Question<User> details() {
        return actor -> SerenityRest.lastResponse()
                                    .jsonPath()
                                    .getObject("", User.class);
    }

    public static Question<String> name() {
        return actor -> SerenityRest.lastResponse()
                                    .jsonPath()
                                    .getString("name");
    }

    public static Question<String> email() {
        return actor -> SerenityRest.lastResponse()
                                    .jsonPath()
                                    .getString("email");
    }
}
```

```java
@Test
@DisplayName("Should use questions to query responses")
void shouldUseQuestionsToQueryResponses() {
    alex.attemptsTo(
        FetchUser.withId(1)
    );

    String userName = alex.asksFor(TheUser.name());
    assertThat(userName).isEqualTo("Leanne Graham");

    User user = alex.asksFor(TheUser.details());
    assertThat(user.getEmail()).isEqualTo("Sincere@april.biz");
}
```

---

## Part 3: Authentication Patterns

### Basic Authentication

```java
@Test
@DisplayName("Should authenticate with Basic Auth")
void shouldAuthenticateWithBasicAuth() {
    given()
        .baseUri("https://httpbin.org")
        .auth().basic("user", "passwd")
    .when()
        .get("/basic-auth/user/passwd")
    .then()
        .statusCode(200)
        .body("authenticated", equalTo(true));
}
```

### Bearer Token Authentication

Using the Restful-Booker API for token-based auth:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Token Authentication Tests")
class TokenAuthTest {

    private static final String BOOKER_URL = "https://restful-booker.herokuapp.com";
    private String authToken;

    @BeforeEach
    void authenticate() {
        // Get authentication token
        authToken = given()
            .baseUri(BOOKER_URL)
            .contentType("application/json")
            .body("""
                {
                    "username": "admin",
                    "password": "password123"
                }
                """)
        .when()
            .post("/auth")
        .then()
            .statusCode(200)
            .extract()
            .path("token");

        assertThat(authToken).isNotNull();
    }

    @Test
    @DisplayName("Should use token for authenticated requests")
    void shouldUseTokenForAuthenticatedRequests() {
        // Create a booking
        String bookingBody = """
            {
                "firstname": "John",
                "lastname": "Doe",
                "totalprice": 150,
                "depositpaid": true,
                "bookingdates": {
                    "checkin": "2024-01-01",
                    "checkout": "2024-01-05"
                },
                "additionalneeds": "Breakfast"
            }
            """;

        int bookingId = given()
            .baseUri(BOOKER_URL)
            .contentType("application/json")
            .body(bookingBody)
        .when()
            .post("/booking")
        .then()
            .statusCode(200)
            .extract()
            .path("bookingid");

        // Update booking using token
        given()
            .baseUri(BOOKER_URL)
            .contentType("application/json")
            .cookie("token", authToken)  // Token in cookie
            .body("""
                {
                    "firstname": "Jane",
                    "lastname": "Doe",
                    "totalprice": 200,
                    "depositpaid": true,
                    "bookingdates": {
                        "checkin": "2024-01-01",
                        "checkout": "2024-01-05"
                    },
                    "additionalneeds": "Dinner"
                }
                """)
        .when()
            .put("/booking/" + bookingId)
        .then()
            .statusCode(200)
            .body("firstname", equalTo("Jane"));
    }

    @Test
    @DisplayName("Should use Authorization header for token")
    void shouldUseAuthorizationHeader() {
        given()
            .baseUri(BOOKER_URL)
            .header("Authorization", "Bearer " + authToken)
        .when()
            .get("/booking")
        .then()
            .statusCode(200);
    }
}
```

### API Key Authentication

```java
@Test
@DisplayName("Should authenticate with API key in header")
void shouldAuthenticateWithApiKey() {
    given()
        .baseUri("https://api.example.com")
        .header("X-API-Key", "your-api-key-here")
    .when()
        .get("/protected-resource")
    .then()
        .statusCode(200);
}

@Test
@DisplayName("Should authenticate with API key in query parameter")
void shouldAuthenticateWithApiKeyInQuery() {
    given()
        .baseUri("https://api.example.com")
        .queryParam("api_key", "your-api-key-here")
    .when()
        .get("/protected-resource")
    .then()
        .statusCode(200);
}
```

### Screenplay Authentication Task

```java
// tasks/Authenticate.java
package com.example.api.tasks;

import net.serenitybdd.rest.SerenityRest;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.rest.interactions.Post;
import net.serenitybdd.annotations.Step;

import static net.serenitybdd.screenplay.Tasks.instrumented;

public class Authenticate implements Task {

    private final String username;
    private final String password;

    public Authenticate(String username, String password) {
        this.username = username;
        this.password = password;
    }

    public static Authenticate withCredentials(String username, String password) {
        return instrumented(Authenticate.class, username, password);
    }

    public static Authenticate asAdmin() {
        return instrumented(Authenticate.class, "admin", "password123");
    }

    @Override
    @Step("{0} authenticates as #username")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Post.to("/auth")
                .with(request -> request
                    .contentType("application/json")
                    .body(String.format("""
                        {"username": "%s", "password": "%s"}
                        """, username, password))
                )
        );

        String token = SerenityRest.lastResponse().path("token");
        actor.remember("authToken", token);
    }
}
```

Using the authentication task:

```java
@Test
@DisplayName("Should authenticate and use token in subsequent requests")
void shouldAuthenticateAndUseToken() {
    Actor admin = Actor.named("Admin")
                       .whoCan(CallAnApi.at(BOOKER_URL));

    admin.attemptsTo(
        Authenticate.asAdmin()
    );

    String token = admin.recall("authToken");
    assertThat(token).isNotNull();

    // Use token in subsequent request
    admin.attemptsTo(
        Get.resource("/booking")
           .with(request -> request.cookie("token", token))
    );

    admin.should(
        seeThatResponse(response -> response.statusCode(200))
    );
}
```

---

## Part 4: Error Handling and Validation

### Testing Error Responses

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Error Handling Tests")
class ErrorHandlingTest {

    private static final String BASE_URL = "https://jsonplaceholder.typicode.com";

    @Test
    @DisplayName("Should handle 404 Not Found")
    void shouldHandle404NotFound() {
        given()
            .baseUri(BASE_URL)
        .when()
            .get("/users/99999")
        .then()
            .statusCode(404);
    }

    @Test
    @DisplayName("Should handle invalid request body")
    void shouldHandleInvalidRequestBody() {
        given()
            .baseUri("https://reqres.in/api")
            .contentType("application/json")
            .body("{invalid json}")
        .when()
            .post("/users")
        .then()
            .statusCode(anyOf(equalTo(400), equalTo(500)));
    }

    @Test
    @DisplayName("Should verify error message content")
    void shouldVerifyErrorMessageContent() {
        given()
            .baseUri("https://reqres.in/api")
        .when()
            .post("/login")  // Missing required fields
        .then()
            .statusCode(400)
            .body("error", equalTo("Missing email or username"));
    }
}
```

### Testing Multiple Status Codes

```java
@ParameterizedTest
@CsvSource({
    "1, 200",
    "2, 200",
    "99999, 404"
})
@DisplayName("Should return correct status for user ID")
void shouldReturnCorrectStatusForUserId(int userId, int expectedStatus) {
    given()
        .baseUri("https://reqres.in/api")
    .when()
        .get("/users/" + userId)
    .then()
        .statusCode(expectedStatus);
}
```

### JSON Schema Validation

Create a schema file at `src/test/resources/schemas/user-schema.json`:

```json
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "required": ["data"],
    "properties": {
        "data": {
            "type": "object",
            "required": ["id", "email", "first_name", "last_name", "avatar"],
            "properties": {
                "id": {
                    "type": "integer"
                },
                "email": {
                    "type": "string",
                    "format": "email"
                },
                "first_name": {
                    "type": "string",
                    "minLength": 1
                },
                "last_name": {
                    "type": "string",
                    "minLength": 1
                },
                "avatar": {
                    "type": "string",
                    "format": "uri"
                }
            }
        }
    }
}
```

```java
import static io.restassured.module.jsv.JsonSchemaValidator.matchesJsonSchemaInClasspath;

@Test
@DisplayName("Should match JSON schema")
void shouldMatchJsonSchema() {
    given()
        .baseUri("https://reqres.in/api")
    .when()
        .get("/users/1")
    .then()
        .statusCode(200)
        .body(matchesJsonSchemaInClasspath("schemas/user-schema.json"));
}
```

### Response Time Validation

```java
import static java.util.concurrent.TimeUnit.SECONDS;
import static java.util.concurrent.TimeUnit.MILLISECONDS;

@Test
@DisplayName("Should respond within acceptable time")
void shouldRespondWithinAcceptableTime() {
    given()
        .baseUri(BASE_URL)
    .when()
        .get("/users")
    .then()
        .statusCode(200)
        .time(lessThan(5L), SECONDS);
}

@Test
@DisplayName("Should track response time")
void shouldTrackResponseTime() {
    long responseTime = given()
        .baseUri(BASE_URL)
    .when()
        .get("/users")
    .then()
        .extract()
        .time();

    System.out.println("Response time: " + responseTime + "ms");
    assertThat(responseTime).isLessThan(5000);
}
```

---

## Part 5: Chained API Calls

Often you need to use data from one API call in subsequent calls:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Chained API Calls")
class ChainedApiTest {

    private static final String BASE_URL = "https://jsonplaceholder.typicode.com";

    @Test
    @DisplayName("Should create post and then fetch it")
    void shouldCreatePostAndThenFetchIt() {
        // Step 1: Create a new post
        Post newPost = new Post("Chained Test", "Testing chained calls", 1);

        Integer postId = given()
            .baseUri(BASE_URL)
            .contentType("application/json")
            .body(newPost)
        .when()
            .post("/posts")
        .then()
            .statusCode(201)
            .extract()
            .path("id");

        // Step 2: Fetch the created post
        given()
            .baseUri(BASE_URL)
        .when()
            .get("/posts/" + postId)
        .then()
            .statusCode(200)
            .body("title", equalTo("Chained Test"));
    }

    @Test
    @DisplayName("Should fetch user and then their posts")
    void shouldFetchUserAndTheirPosts() {
        // Step 1: Get user
        int userId = given()
            .baseUri(BASE_URL)
        .when()
            .get("/users/1")
        .then()
            .statusCode(200)
            .extract()
            .path("id");

        // Step 2: Get posts by that user
        given()
            .baseUri(BASE_URL)
            .queryParam("userId", userId)
        .when()
            .get("/posts")
        .then()
            .statusCode(200)
            .body("size()", greaterThan(0))
            .body("userId", everyItem(equalTo(userId)));
    }

    @Test
    @DisplayName("Should perform CRUD lifecycle")
    void shouldPerformCrudLifecycle() {
        // CREATE
        Integer postId = given()
            .baseUri(BASE_URL)
            .contentType("application/json")
            .body(new Post("CRUD Test", "Initial content", 1))
        .when()
            .post("/posts")
        .then()
            .statusCode(201)
            .extract()
            .path("id");

        System.out.println("Created post with ID: " + postId);

        // READ
        given()
            .baseUri(BASE_URL)
        .when()
            .get("/posts/" + postId)
        .then()
            .statusCode(200)
            .body("title", equalTo("CRUD Test"));

        // UPDATE
        given()
            .baseUri(BASE_URL)
            .contentType("application/json")
            .body(new Post("Updated CRUD Test", "Updated content", 1))
        .when()
            .put("/posts/" + postId)
        .then()
            .statusCode(200)
            .body("title", equalTo("Updated CRUD Test"));

        // DELETE
        given()
            .baseUri(BASE_URL)
        .when()
            .delete("/posts/" + postId)
        .then()
            .statusCode(200);
    }
}
```

### Screenplay Chained Calls

```java
@Test
@DisplayName("Should chain API calls with Screenplay")
void shouldChainApiCallsWithScreenplay() {
    Actor tester = Actor.named("API Tester")
                        .whoCan(CallAnApi.at(BASE_URL));

    // Create post and remember the ID
    tester.attemptsTo(
        Post.to("/posts")
            .with(request -> request
                .contentType("application/json")
                .body(new Post("Screenplay Chain", "Content", 1))
            )
    );

    Integer postId = SerenityRest.lastResponse().path("id");
    tester.remember("postId", postId);

    // Fetch the post using remembered ID
    tester.attemptsTo(
        Get.resource("/posts/{id}")
           .with(request -> request.pathParam("id", tester.recall("postId")))
    );

    tester.should(
        seeThatResponse(response -> response
            .statusCode(200)
            .body("title", equalTo("Screenplay Chain"))
        )
    );
}
```

---

## Part 6: Data-Driven API Testing

### Parameterized Tests

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Data-Driven API Tests")
class DataDrivenApiTest {

    private static final String BASE_URL = "https://jsonplaceholder.typicode.com";

    @ParameterizedTest
    @ValueSource(ints = {1, 2, 3, 4, 5})
    @DisplayName("Should fetch user by ID")
    void shouldFetchUserById(int userId) {
        given()
            .baseUri(BASE_URL)
        .when()
            .get("/users/" + userId)
        .then()
            .statusCode(200)
            .body("id", equalTo(userId));
    }

    @ParameterizedTest
    @CsvSource({
        "1, Leanne Graham, Sincere@april.biz",
        "2, Ervin Howell, Shanna@melissa.tv",
        "3, Clementine Bauch, Nathan@yesenia.net"
    })
    @DisplayName("Should verify user details")
    void shouldVerifyUserDetails(int id, String name, String email) {
        given()
            .baseUri(BASE_URL)
        .when()
            .get("/users/" + id)
        .then()
            .statusCode(200)
            .body("name", equalTo(name))
            .body("email", equalTo(email));
    }

    @ParameterizedTest
    @MethodSource("postDataProvider")
    @DisplayName("Should create posts with various data")
    void shouldCreatePostsWithVariousData(Post post) {
        given()
            .baseUri(BASE_URL)
            .contentType("application/json")
            .body(post)
        .when()
            .post("/posts")
        .then()
            .statusCode(201)
            .body("title", equalTo(post.getTitle()));
    }

    static Stream<Post> postDataProvider() {
        return Stream.of(
            new Post("First Post", "Content 1", 1),
            new Post("Second Post", "Content 2", 2),
            new Post("Third Post", "Content 3", 3)
        );
    }
}
```

### Loading Test Data from Files

Create a test data file `src/test/resources/testdata/users.json`:

```json
[
    {"userId": 1, "expectedName": "Leanne Graham"},
    {"userId": 2, "expectedName": "Ervin Howell"},
    {"userId": 3, "expectedName": "Clementine Bauch"}
]
```

```java
@ParameterizedTest
@MethodSource("loadUsersFromFile")
@DisplayName("Should verify users from JSON file")
void shouldVerifyUsersFromFile(int userId, String expectedName) {
    given()
        .baseUri(BASE_URL)
    .when()
        .get("/users/" + userId)
    .then()
        .statusCode(200)
        .body("name", equalTo(expectedName));
}

static Stream<Arguments> loadUsersFromFile() throws Exception {
    ObjectMapper mapper = new ObjectMapper();
    List<Map<String, Object>> users = mapper.readValue(
        new File("src/test/resources/testdata/users.json"),
        new TypeReference<List<Map<String, Object>>>() {}
    );

    return users.stream()
        .map(user -> Arguments.of(
            ((Number) user.get("userId")).intValue(),
            user.get("expectedName")
        ));
}
```

---

## Part 7: File Uploads and Downloads

### File Upload (Multipart)

```java
@Test
@DisplayName("Should upload a file")
void shouldUploadFile() {
    File testFile = new File("src/test/resources/testdata/sample.txt");

    given()
        .baseUri("https://httpbin.org")
        .multiPart("file", testFile)
    .when()
        .post("/post")
    .then()
        .statusCode(200)
        .body("files.file", notNullValue());
}

@Test
@DisplayName("Should upload file with additional form data")
void shouldUploadFileWithFormData() {
    File testFile = new File("src/test/resources/testdata/sample.txt");

    given()
        .baseUri("https://httpbin.org")
        .multiPart("file", testFile)
        .formParam("description", "Test file upload")
        .formParam("category", "documents")
    .when()
        .post("/post")
    .then()
        .statusCode(200);
}
```

### File Download

```java
@Test
@DisplayName("Should download a file")
void shouldDownloadFile() {
    byte[] fileContent = given()
        .baseUri("https://httpbin.org")
    .when()
        .get("/image/png")
    .then()
        .statusCode(200)
        .contentType("image/png")
        .extract()
        .asByteArray();

    assertThat(fileContent.length).isGreaterThan(0);

    // Optionally save to file
    // Files.write(Paths.get("downloaded.png"), fileContent);
}
```

---

## Part 8: Advanced Configuration

### Request Specification (Reusable Configuration)

```java
@ExtendWith(SerenityJUnit5Extension.class)
class RequestSpecificationTest {

    private RequestSpecification baseSpec;

    @BeforeEach
    void setup() {
        baseSpec = new RequestSpecBuilder()
            .setBaseUri("https://jsonplaceholder.typicode.com")
            .setContentType("application/json")
            .addHeader("Accept", "application/json")
            .log(LogDetail.ALL)
            .build();
    }

    @Test
    @DisplayName("Should use request specification")
    void shouldUseRequestSpecification() {
        given()
            .spec(baseSpec)
        .when()
            .get("/users/1")
        .then()
            .statusCode(200);
    }
}
```

### Response Specification (Reusable Assertions)

```java
@ExtendWith(SerenityJUnit5Extension.class)
class ResponseSpecificationTest {

    private ResponseSpecification successSpec;
    private ResponseSpecification errorSpec;

    @BeforeEach
    void setup() {
        successSpec = new ResponseSpecBuilder()
            .expectStatusCode(200)
            .expectContentType("application/json")
            .expectResponseTime(lessThan(5000L))
            .build();

        errorSpec = new ResponseSpecBuilder()
            .expectStatusCode(404)
            .build();
    }

    @Test
    @DisplayName("Should use success response specification")
    void shouldUseSuccessResponseSpec() {
        given()
            .baseUri("https://jsonplaceholder.typicode.com")
        .when()
            .get("/users/1")
        .then()
            .spec(successSpec)
            .body("name", notNullValue());
    }
}
```

### Timeouts and Retries

```java
import static io.restassured.config.HttpClientConfig.httpClientConfig;

@Test
@DisplayName("Should configure connection timeout")
void shouldConfigureTimeout() {
    given()
        .baseUri("https://jsonplaceholder.typicode.com")
        .config(RestAssured.config()
            .httpClient(httpClientConfig()
                .setParam("http.connection.timeout", 5000)
                .setParam("http.socket.timeout", 5000)
            )
        )
    .when()
        .get("/users")
    .then()
        .statusCode(200);
}
```

### Logging

```java
@Test
@DisplayName("Should log request and response")
void shouldLogRequestAndResponse() {
    given()
        .baseUri("https://jsonplaceholder.typicode.com")
        .log().all()  // Log entire request
    .when()
        .get("/users/1")
    .then()
        .log().all()  // Log entire response
        .statusCode(200);
}

@Test
@DisplayName("Should log only on failure")
void shouldLogOnlyOnFailure() {
    given()
        .baseUri("https://jsonplaceholder.typicode.com")
        .log().ifValidationFails()
    .when()
        .get("/users/1")
    .then()
        .log().ifValidationFails()
        .statusCode(200);
}
```

---

## Part 9: Hybrid UI + API Testing

Combine UI and API testing for powerful end-to-end scenarios:

### Using Playwright with API Calls

```java
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import net.serenitybdd.screenplay.playwright.interactions.*;
import net.serenitybdd.screenplay.rest.abilities.CallAnApi;
import net.serenitybdd.screenplay.rest.interactions.Post;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Hybrid UI + API Tests")
class HybridTest {

    @Test
    @DisplayName("Should create data via API and verify in UI")
    void shouldCreateDataViaApiAndVerifyInUi() {
        // Actor with both abilities
        Actor tester = Actor.named("Hybrid Tester")
            .whoCan(CallAnApi.at("https://api.example.com"))
            .whoCan(BrowseTheWebWithPlaywright.usingTheDefaultConfiguration());

        // Create data via API
        tester.attemptsTo(
            Post.to("/products")
                .with(request -> request
                    .contentType("application/json")
                    .body("""
                        {"name": "New Product", "price": 99.99}
                        """)
                )
        );

        // Verify in UI
        tester.attemptsTo(
            Open.url("https://example.com/products"),
            Ensure.that(Text.of(".product-name")).contains("New Product")
        );
    }

    @Test
    @DisplayName("Should perform UI action and verify via API")
    void shouldPerformUiActionAndVerifyViaApi() {
        Actor tester = Actor.named("Hybrid Tester")
            .whoCan(CallAnApi.at("https://api.example.com"))
            .whoCan(BrowseTheWebWithPlaywright.usingTheDefaultConfiguration());

        // Perform UI action
        tester.attemptsTo(
            Open.url("https://example.com/checkout"),
            Click.on("#place-order-button")
        );

        // Verify via API
        tester.attemptsTo(
            Get.resource("/orders/latest")
        );

        tester.should(
            seeThatResponse(response -> response
                .statusCode(200)
                .body("status", equalTo("placed"))
            )
        );
    }
}
```

---

## Part 10: Best Practices

### 1. Organize by Domain

```
src/test/java/com/example/api/
├── model/
│   ├── User.java
│   ├── Post.java
│   └── Booking.java
├── tasks/
│   ├── CreateUser.java
│   ├── FetchUser.java
│   └── Authenticate.java
├── questions/
│   ├── TheUser.java
│   └── TheResponse.java
├── specs/
│   ├── RequestSpecs.java
│   └── ResponseSpecs.java
└── tests/
    ├── UserApiTest.java
    ├── PostApiTest.java
    └── AuthenticationTest.java
```

### 2. Use Meaningful Assertions

```java
// Bad
response.body("data", notNullValue());

// Good
response.body("data.id", equalTo(expectedUserId))
        .body("data.email", matchesPattern("^[\\w.-]+@[\\w.-]+\\.\\w+$"))
        .body("data.created_at", notNullValue());
```

### 3. Extract Common Setup

```java
public class ApiTestBase {

    protected static final String BASE_URL =
        System.getProperty("api.baseurl", "https://api.example.com");

    protected RequestSpecification baseRequest() {
        return given()
            .baseUri(BASE_URL)
            .contentType("application/json")
            .accept("application/json")
            .log().ifValidationFails();
    }
}
```

### 4. Use Tags for Test Categories

```java
@Tag("smoke")
@Test
void criticalEndpointTest() { }

@Tag("regression")
@Test
void detailedValidationTest() { }

@Tag("slow")
@Test
void performanceTest() { }
```

### 5. Clean Up Test Data

```java
@AfterEach
void cleanup() {
    if (createdResourceId != null) {
        given()
            .baseUri(BASE_URL)
            .header("Authorization", "Bearer " + authToken)
        .when()
            .delete("/resources/" + createdResourceId)
        .then()
            .statusCode(anyOf(equalTo(200), equalTo(204), equalTo(404)));
    }
}
```

---

## Summary

This tutorial covered:

| Topic | Description |
|-------|-------------|
| Basic Operations | GET, POST, PUT, PATCH, DELETE requests |
| Screenplay Pattern | Actor-centric API testing with tasks and questions |
| Authentication | Basic auth, bearer tokens, API keys |
| Error Handling | Testing error responses, schema validation |
| Chained Calls | Using data from one call in another |
| Data-Driven Tests | Parameterized tests with various data sources |
| File Operations | Upload and download files |
| Configuration | Request/response specs, timeouts, logging |
| Hybrid Testing | Combining UI and API tests |

## Next Steps

- Explore [Screenplay REST](/docs/screenplay/screenplay_rest) for more Screenplay patterns
- Learn about [Serenity Reports](/docs/reporting/the_serenity_reports) for API test reporting
- Check out [Cucumber Integration](/docs/cucumber/cucumber-junit5) for BDD-style API tests

## Resources

- [Rest-Assured Documentation](https://rest-assured.io/)
- [JSONPlaceholder API](https://jsonplaceholder.typicode.com/)
- [ReqRes API](https://reqres.in/)
- [Restful-Booker API](https://restful-booker.herokuapp.com/apidoc/)
- [JSON Schema](https://json-schema.org/)


---

<!-- https://serenity-bdd.github.io/docs/tutorials/cucumber-screenplay -->

# Getting Started With Cucumber using Serenity BDD and Screenplay

:::tip Comprehensive Cucumber Guide Available
This tutorial focuses on getting started with Cucumber and Screenplay. For comprehensive coverage of Cucumber configuration, JUnit 5 integration, parallel execution, and advanced topics, see the [Cucumber with JUnit 5](/docs/cucumber/cucumber-junit5) section.
:::

## Objectives
At the end of this tutorial, you would have completed the following activities.
1. Write your first **specification by example** using [Gherkin](https://cucumber.io/docs/gherkin/reference/) language in a `.feature` file for the well-known [TodoMVC](http://todomvc.com) project
2. Make the specification (the `.feature` file from Step 1 above) executable using Serenity BDD and Cucumber with Screenplay pattern
3. Create a **living documentation** that also serves as a test report and a progress report

## Pre-requisites
To run this tutorial, you will need a few things installed on your machine:
* **Java**: Serenity BDD is a Java library, so you'll need a recent JDK installed. JDK 17 or higher should be fine.
* **Maven**: You will need Maven 3 or higher installed in your computer.  This acts as a build tool that also downloads the dependencies while building.
* **A Java IDE**: You'll also need a Java Development Environment such as IntelliJ or Eclipse (and a working knowledge of Java).
* **Git**: We'll be using a starter project on Github, and the sample code for this project lives on Github too, so I'll be assuming you have a basic understanding of Git.

## Creating your project

The quickest way to start a new Serenity BDD with [Cucumber](https://cucumber.io/) project is to clone the starter project. For this tutorial, We will be using the **[Serenity BDD with Cucumber and Screenplay](https://github.com/serenity-bdd/serenity-cucumber-starter)** template project, which uses Serenity BDD and Cucumber 6.x.

This project comes with a sample feature file already implemented for our reference.  For now, we are going to ignore that and start writing a new feature file from scratch.

:::info

Just to make sure that the starter template's sample files do not interfere with our experience in this tutorial, **delete** the following files/directories.

1. Directory - `src/test/resources/features/search`
2. Directory -  `src/test/java/starter/navigation`
3. Directory -  `src/test/java/starter/search`
4. File - `src/test/java/starter/stepdefinitions/SearchStepDefinitions.java`

:::

## The project directory structure
We will use some simple conventions to organise our feature files and the supporting Java classes, based on the standard Maven project structure outlined below:

```
src
├───main
│   └───java
│       └───starter
└───test
    ├───java
    │   └───starter
    │       └───helpers
    │       └───stepdefinitions
    └───resources
        └───features
```

Here are some points to note about the directory structure.
1. Since we will test the publicly available [TodoMVC](http://todomvc.com) web application, we will not have any code in the `src/main` directory.
2. We will use the `src/test/resources/features` directory to store our `.feature` files, which are specifications that define the requirements.
3. We will use the `src/test/java/starter/stepdefinitions` directory to store the code implementing the steps mentioned in our `.feature` files.  This code is called Glue code or the Step definitions.
4. We will use the `src/test/java/starter/helpers` directory to store the code for any helper classes that are needed by our step definitions.

## Writing the first feature file
Now, let us start with writing a feature file to describe adding a new item to the to-do list.

Create a new file with name `add_new_todo.feature` in the `src/test/resources/features` directory with the following content.

```gherkin
Feature: Add new item to TODO list

Scenario: Add buying milk to the list
Given Rama is looking at his TODO list
When he adds "Buy some milk" to the list
Then he sees "Buy some milk" as an item in the TODO list
```

## Writing the step definitions skeleton
In order to translate the steps in the `add_new_todo.feature` into executable actions, we write Java classes called **Step Definitions**.

Let us create a new file named `AddItemStepDefinitions.java` in the directory `src/test/java/starter/stepdefinitions` with the following skeleton content.  Note that this is only a skeleton content. We will add flesh to this class later.

```java
package starter.stepdefinitions;

import io.cucumber.java.PendingException;
import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import net.serenitybdd.screenplay.Actor;

public class AddItemStepDefinitions {

    @Given("{actor} is looking at his TODO list")
    public void actor_is_looking_at_his_todo_list(Actor actor) {
        // Write code here that turns the phrase above into concrete actions
        throw new PendingException("Implement me");
    }
    @When("{actor} adds {string} to the list")
    public void he_adds_to_the_list(Actor actor, String itemName) {
        // Write code here that turns the phrase above into concrete actions
        throw new PendingException("Implement me");
    }
    @Then("{actor} sees {string} as an item in the TODO list")
    public void he_sees_as_an_item_in_the_todo_list(Actor actor, String expectedItemName) {
        // Write code here that turns the phrase above into concrete actions
        throw new PendingException("Implement me");
    }

}
```

The above file just throws exceptions whenever Cucumber tries to execute the steps and mark them as Pending.

Let us try running the Maven build to see the result at this stage.  We expect the build to fail stating that scenarios are pending to be implemented.

Run the following command in a terminal or command prompt.

```bash
mvn clean verify
```

Once the command completes, you can see output similar to the following.

```
[ERROR] Tests run: 1, Failures: 0, Errors: 1, Skipped: 0, Time elapsed: 7.255 s <<< FAILURE! - in starter.CucumberTestSuite
[ERROR] Add new item to TODO list.Add buying milk to the list  Time elapsed: 0.713 s  <<< ERROR!
io.cucumber.java.PendingException: TODO: implement me

[INFO] 
[INFO] Results:
[INFO]
[ERROR] Errors: 
[ERROR]   TODO: implement me
[INFO]
[ERROR] Tests run: 1, Failures: 0, Errors: 1, Skipped: 0

...
...
...

[INFO] -----------------------------------------
[INFO]  SERENITY TESTS: PENDING
[INFO] -----------------------------------------
[INFO] | Test cases executed    | 1
[INFO] | Tests executed         | 1
[INFO] | Tests passed           | 0
[INFO] | Tests failed           | 0
[INFO] | Tests with errors      | 0
[INFO] | Tests compromised      | 0
[INFO] | Tests aborted          | 0
[INFO] | Tests pending          | 1
[INFO] | Tests ignored/skipped  | 0
[INFO] ------------------------ | --------------
[INFO] | Total Duration         | 365ms
[INFO] | Fastest test took      | 365ms
[INFO] | Slowest test took      | 365ms
[INFO] -----------------------------------------

...
...
...

[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M5:verify (default) @ cucumber-starter ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  30.465 s
[INFO] Finished at: 2022-08-12T14:52:57+05:30
[INFO] ------------------------------------------------------------------------

```

The above output is as we expected.  The build is failing with a `PendingException` and the tests are marked as pending.

## Creating Helper Classes for Step Definitions
So far, we have only dummy step definitions.  Let us implement real tests now.  In order to implement the real tests, let us create a few helper classes.

#### Page Object
Let us first create a file `TodoListPage.java` in the directory `src/test/java/starter/helpers` with the following content.

```java
package starter.helpers;

import net.serenitybdd.core.pages.PageObject;
import net.serenitybdd.screenplay.targets.Target;
import net.serenitybdd.annotations.DefaultUrl;


@DefaultUrl("https://todomvc.com/examples/angularjs/#/")
public class TodoListPage extends PageObject {
    public static Target ITEM_NAME_FIELD = Target.the("item name field").locatedBy(".new-todo");

    public static Target ITEMS_LIST = Target.the(" item list").locatedBy(".todo-list li");
}
```

This class is what we call as a `PageObject`.  This contains all the information we will need to use a particular web page, the TODO app, in this case.

The `@DefaultUrl` annotation specifies the URL that needs to be typed in the browser's address bar to access this page.

There are two static fields `ITEM_NAME_FIELD` and `ITEMS_LIST` that help identify specific HTML elements on the page, which we will use later in our step definition files.

#### Navigation Helper 

Let us create a file `NavigateTo.java` in the directory `src/test/java/starter/helpers` with the following content.

```java
package starter.helpers;

import net.serenitybdd.screenplay.Performable;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.actions.Open;

public class NavigateTo {
     public static Performable theTodoListPage() {
        return Task.where("{0} opens the Todo list page",
                Open.browserOn().the(TodoListPage.class));
    }
}
```
The above class uses Serenity BDD's [Screenplay pattern](/docs/screenplay/screenplay_fundamentals) to describe the behavior in a lucid manner.  This class helps us to open the browser with the proper URL.

#### Action Definition

Next, let us create a file `AddAnItem.java` in the directory `src/test/java/starter/helpers` with the following content.

```java
package starter.helpers;

import net.serenitybdd.screenplay.Performable;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.actions.Enter;
import org.openqa.selenium.Keys;

public class AddAnItem {

    public static Performable withName(String itemName){
        return Task.where("{0} adds an item with name "+itemName,
                Enter.theValue(itemName)
                        .into(TodoListPage.ITEM_NAME_FIELD)
                        .thenHit(Keys.ENTER)
        );
    }
}
```

The above code explains the steps needed to add an item to the list, i.e., typing the item name in the text box and pressing the ENTER key.

## Adding Details to Step Definitions

Now that our helper classes are ready, we can add real details to the step definitions present in `AddItemStepDefinitions.java`

Open the `AddItemStepDefinitions.java` file (we already created this file) and edit it to have the following content.

```java
package starter.stepdefinitions;

import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.ensure.Ensure;
import starter.helpers.AddAnItem;
import starter.helpers.NavigateTo;
import starter.helpers.TodoListPage;

public class AddItemStepDefinitions {
    @Given("{actor} is looking at his TODO list")
    public void actor_is_looking_at_his_todo_list(Actor actor) {
        actor.wasAbleTo(NavigateTo.theTodoListPage());
    }
    @When("{actor} adds {string} to the list")
    public void he_adds_to_the_list(Actor actor, String itemName) {
       actor.attemptsTo(AddAnItem.withName(itemName));
    }
    @Then("{actor} sees {string} as an item in the TODO list")
    public void he_sees_as_an_item_in_the_todo_list(Actor actor, String expectedItemName) {
        actor.attemptsTo(Ensure.that(TodoListPage.ITEMS_LIST).hasText(expectedItemName));
    }

}
```

Notice how the code reads like the spoken English.  This is one of the pleasant side-effects of using Screenplay pattern in your Cucumber step definitions.

## Running the build again

Now, let us run the build again by issuing the following command from the terminal or command line.

```bash
mvn clean verify
```

Now, you will see the following output.

```
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 28.42 s - in starter.CucumberTestSuite
[INFO] 
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

...
...
...

[INFO] -----------------------------------------
[INFO]  SERENITY TESTS: SUCCESS
[INFO] -----------------------------------------
[INFO] | Test cases executed    | 1
[INFO] | Tests executed         | 1
[INFO] | Tests passed           | 1
[INFO] | Tests failed           | 0
[INFO] | Tests with errors      | 0
[INFO] | Tests compromised      | 0
[INFO] | Tests aborted          | 0
[INFO] | Tests pending          | 0
[INFO] | Tests ignored/skipped  | 0
[INFO] ------------------------ | --------------
[INFO] | Total Duration         | 20s 001ms
[INFO] | Fastest test took      | 20s 001ms
[INFO] | Slowest test took      | 20s 001ms
[INFO] -----------------------------------------
[INFO]
[INFO] SERENITY REPORTS
[INFO]   - Full Report: file:///C:/Users/calib/source-codes/temp/serenity-cucumber-starter/target/site/serenity/index.html
[INFO]
[INFO] --- maven-failsafe-plugin:3.0.0-M5:verify (default) @ cucumber-starter ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  49.894 s
[INFO] Finished at: 2022-08-12T15:28:52+05:30
[INFO] ------------------------------------------------------------------------

```

Yes, the tests passed and the build is successful now.  We have managed to test our feature successfully 🎉

## Reporting and Living Documentation

If you notice carefully, the output of the `mvn clean verify` command informed us that a report is created in `target/site/serenity/index.html`

When you open this file in a web browser, you see a beautiful report like this.

![Report Home Page](img/cucumber-test-report-home.png)

You can also find the feature-wise results detailing the scenarios in the `Features` tab.

![Report of Features](img/cucumber-report-features.png)

Feel free to navigate the links in this report and look around.

This is also called a **Living Documentation** of the product because, this is generated by actually executing the specifications, rather than just writing it as a wiki or a document stored in cloud.  As the product evolves, the scenarios will get added and this report is the single source of truth about what works and what is pending to be implemented in the product.

In some cases, teams use this document to onboard new joiners to the team.  If you are feeling adventurous, this document can also be used as a user guide.

## Next Steps
In this tutorial, we just touched the surface of using Serenity BDD with Cucumber.  There are multiple ways to customize the report, organize the feature files, implement the step definitions and so on.  Refer to the links in the user manual to know more about further possibilities.


---

<!-- https://serenity-bdd.github.io/docs/tutorials/data-driven-testing -->

# Data-Driven Testing with Serenity BDD

Data-driven testing allows you to run the same test logic with multiple sets of input data, making your tests more comprehensive and maintainable. This guide covers data-driven testing approaches with both JUnit 5 and Cucumber.

## Prerequisites

- Java 17 or higher
- Serenity BDD 5.3.1 or higher
- JUnit 5 6.0.1 or higher (for JUnit examples)
- Cucumber 7.33.0 or higher (for Cucumber examples)

## Why Data-Driven Testing?

Data-driven testing helps you:
- **Test multiple scenarios** with minimal code duplication
- **Improve test coverage** by testing edge cases and boundary values
- **Separate test logic from test data** for better maintainability
- **Make tests more readable** by clearly showing what varies between test cases

## JUnit 5 Parameterized Tests

JUnit 5 provides powerful parameterized testing capabilities through `@ParameterizedTest`.

### Basic Setup

First, add the JUnit Jupiter parameters dependency:

```xml
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-params</artifactId>
    <version>6.0.1</version>
    <scope>test</scope>
</dependency>
```

### Simple Value Sources

Use `@ValueSource` for simple data types:

```java
import net.serenitybdd.annotations.Managed;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.extension.ExtendWith;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import org.openqa.selenium.WebDriver;

@ExtendWith(SerenityJUnit5Extension.class)
class SearchTests {

    @Managed(driver = "chrome", options = "headless")
    WebDriver driver;

    @ParameterizedTest
    @ValueSource(strings = {"Selenium", "Cucumber", "JUnit 5"})
    void shouldFindSearchResults(String searchTerm) {
        // Navigate to search page
        driver.get("https://duckduckgo.com");

        // Perform search with each term
        SearchPage searchPage = new SearchPage(driver);
        searchPage.searchFor(searchTerm);

        // Verify results
        assertThat(searchPage.getResults()).isNotEmpty();
    }
}
```

**Supported types for @ValueSource:**
- `strings` - String values
- `ints` - Integer values
- `longs` - Long values
- `doubles` - Double values
- `booleans` - Boolean values

### CSV Source - Inline Data

Use `@CsvSource` for multiple parameters per test case:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class LoginTests {

    @Managed(driver = "chrome", options = "headless")
    WebDriver driver;

    @Steps
    LoginActions loginActions;

    @ParameterizedTest
    @CsvSource({
        "standard_user,     secret_sauce,  true",
        "locked_out_user,  secret_sauce,  false",
        "problem_user,     secret_sauce,  true",
        "invalid_user,     wrong_password, false"
    })
    void shouldHandleLoginScenarios(String username, String password, boolean shouldSucceed) {
        loginActions.navigateToLoginPage();
        loginActions.loginWith(username, password);

        if (shouldSucceed) {
            loginActions.shouldSeeProductsPage();
        } else {
            loginActions.shouldSeeErrorMessage();
        }
    }
}
```

**Tips for @CsvSource:**
- Values are comma-separated by default
- Use single quotes for strings containing commas: `'value, with, commas'`
- Empty values are treated as null
- Whitespace is trimmed by default

### CSV Source with Custom Delimiter

```java
@ParameterizedTest
@CsvSource(delimiter = '|', value = {
    "Alice | alice@example.com | Premium",
    "Bob   | bob@example.com   | Standard",
    "Carol | carol@example.com | Basic"
})
void shouldHandleDifferentUserTypes(String name, String email, String accountType) {
    // Test implementation
}
```

### CSV File Source - External Data

Store test data in external CSV files for better maintainability:

**src/test/resources/test-data/users.csv:**
```csv
username,password,email,expectedRole
admin,admin123,admin@example.com,ADMIN
user1,password1,user1@example.com,USER
user2,password2,user2@example.com,USER
guest,guest123,guest@example.com,GUEST
```

```java
@ExtendWith(SerenityJUnit5Extension.class)
class UserRegistrationTests {

    @Steps
    RegistrationActions registration;

    @ParameterizedTest
    @CsvFileSource(resources = "/test-data/users.csv", numLinesToSkip = 1)
    void shouldRegisterUsers(String username, String password, String email, String expectedRole) {
        registration.registerNewUser(username, password, email);
        registration.shouldHaveRole(expectedRole);
    }
}
```

**@CsvFileSource options:**
- `resources` - Path to CSV file (relative to src/test/resources)
- `numLinesToSkip` - Skip header row (typically 1)
- `delimiter` - Custom delimiter (default is comma)
- `encoding` - File encoding (default is UTF-8)

### Method Source - Complex Objects

Use `@MethodSource` for complex test data or when you need more control:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class ProductTests {

    @Steps
    ShoppingActions shopping;

    @ParameterizedTest
    @MethodSource("productTestData")
    void shouldAddProductToCart(Product product, int quantity, double expectedTotal) {
        shopping.addToCart(product, quantity);
        shopping.shouldShowTotal(expectedTotal);
    }

    static Stream<Arguments> productTestData() {
        return Stream.of(
            Arguments.of(new Product("Laptop", 999.99), 1, 999.99),
            Arguments.of(new Product("Mouse", 29.99), 2, 59.98),
            Arguments.of(new Product("Keyboard", 79.99), 3, 239.97)
        );
    }
}
```

### Method Source from External Class

Organize test data in separate classes:

```java
class TestDataProviders {

    static Stream<Arguments> loginScenarios() {
        return Stream.of(
            Arguments.of("admin", "admin123", true, "Dashboard"),
            Arguments.of("user", "user123", true, "Home"),
            Arguments.of("invalid", "wrong", false, "Login Error")
        );
    }

    static Stream<Arguments> searchQueries() {
        return Stream.of(
            Arguments.of("Selenium", 10),
            Arguments.of("Cucumber", 8),
            Arguments.of("JUnit", 15)
        );
    }
}

@ExtendWith(SerenityJUnit5Extension.class)
class LoginTests {

    @ParameterizedTest
    @MethodSource("com.example.TestDataProviders#loginScenarios")
    void shouldHandleLoginScenarios(String username, String password,
                                   boolean shouldSucceed, String expectedPage) {
        // Test implementation
    }
}
```

### Enum Source

Test with enum values:

```java
enum UserRole {
    ADMIN, MANAGER, USER, GUEST
}

@ExtendWith(SerenityJUnit5Extension.class)
class RoleBasedTests {

    @ParameterizedTest
    @EnumSource(UserRole.class)
    void shouldHandleAllUserRoles(UserRole role) {
        // Test each role
    }

    @ParameterizedTest
    @EnumSource(value = UserRole.class, names = {"ADMIN", "MANAGER"})
    void shouldAllowAdminActions(UserRole role) {
        // Test only admin and manager roles
    }
}
```

### Custom Display Names

Make test reports more readable:

```java
@ParameterizedTest(name = "Search for ''{0}'' should return at least {1} results")
@CsvSource({
    "Selenium, 10",
    "Cucumber, 5",
    "JUnit,    8"
})
void searchTests(String term, int minimumResults) {
    // Test implementation
}
```

The `{0}`, `{1}` placeholders correspond to parameter positions.

## Cucumber Scenario Outlines

Cucumber provides Scenario Outlines for data-driven BDD tests.

### Basic Scenario Outline

**features/login.feature:**
```gherkin
Feature: User Login

  Scenario Outline: Login with different credentials
    Given the user is on the login page
    When the user logs in with username "<username>" and password "<password>"
    Then the login should <result>
    And the user should see the "<page>" page

    Examples:
      | username      | password     | result  | page      |
      | standard_user | secret_sauce | succeed | Products  |
      | locked_user   | secret_sauce | fail    | Login     |
      | invalid_user  | wrong_pass   | fail    | Login     |
```

### Step Definitions with Screenplay

```java
import io.cucumber.java.en.*;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.abilities.BrowseTheWeb;
import net.serenitybdd.screenplay.actions.Open;
import static net.serenitybdd.screenplay.GivenWhenThen.*;

public class LoginStepDefinitions {

    @Given("{actor} is on the login page")
    public void userIsOnLoginPage(Actor actor) {
        actor.attemptsTo(
            Open.url("https://www.saucedemo.com")
        );
    }

    @When("{actor} logs in with username {string} and password {string}")
    public void userLogsIn(Actor actor, String username, String password) {
        actor.attemptsTo(
            Login.withCredentials(username, password)
        );
    }

    @Then("the login should {word}")
    public void verifyLoginResult(String result) {
        // Verification based on result
    }

    @Then("{actor} should see the {string} page")
    public void verifiesPage(Actor actor, String expectedPage) {
        actor.should(
            seeThat(TheCurrentPage.title(), containsString(expectedPage))
        );
    }
}
```

### Multiple Examples Tables

Use multiple Examples tables to organize different test scenarios:

```gherkin
Feature: Shopping Cart

  Scenario Outline: Add products to cart
    Given the user is logged in
    When the user adds "<product>" with quantity <quantity>
    Then the cart total should be <total>

    Examples: Single items
      | product  | quantity | total   |
      | Laptop   | 1        | 999.99  |
      | Mouse    | 1        | 29.99   |
      | Keyboard | 1        | 79.99   |

    Examples: Multiple quantities
      | product  | quantity | total   |
      | Mouse    | 3        | 89.97   |
      | Keyboard | 2        | 159.98  |
```

### Data Tables

For more complex data structures, use Data Tables:

```gherkin
Feature: Bulk User Registration

  Scenario: Register multiple users
    Given the admin is logged in
    When the admin registers the following users:
      | username | email              | role    |
      | alice    | alice@example.com  | Admin   |
      | bob      | bob@example.com    | User    |
      | charlie  | charlie@example.com| Manager |
    Then all users should be created successfully
```

Step definition:

```java
@When("the admin registers the following users:")
public void registerUsers(DataTable dataTable) {
    List<Map<String, String>> users = dataTable.asMaps();

    for (Map<String, String> user : users) {
        String username = user.get("username");
        String email = user.get("email");
        String role = user.get("role");

        actor.attemptsTo(
            RegisterUser.withDetails(username, email, role)
        );
    }
}
```

### External Data Files with Cucumber

Load data from external files:

```gherkin
Scenario: Register users from CSV
  Given the admin is logged in
  When the admin imports users from "test-data/users.csv"
  Then all users should be registered
```

```java
@When("the admin imports users from {string}")
public void importUsersFromFile(String filePath) {
    List<User> users = UserDataLoader.fromCsv(filePath);

    users.forEach(user ->
        actor.attemptsTo(RegisterUser.with(user))
    );
}
```

## External Data Sources

### Reading from CSV Files

Create a reusable CSV reader:

```java
public class CsvDataReader {

    public static List<Map<String, String>> readCsv(String filePath) {
        List<Map<String, String>> data = new ArrayList<>();

        try (BufferedReader reader = new BufferedReader(
                new FileReader(filePath))) {

            String headerLine = reader.readLine();
            String[] headers = headerLine.split(",");

            String line;
            while ((line = reader.readLine()) != null) {
                String[] values = line.split(",");
                Map<String, String> row = new HashMap<>();

                for (int i = 0; i < headers.length; i++) {
                    row.put(headers[i].trim(), values[i].trim());
                }
                data.add(row);
            }
        } catch (IOException e) {
            throw new RuntimeException("Failed to read CSV file: " + filePath, e);
        }

        return data;
    }
}
```

### Reading from JSON Files

Use Jackson or Gson to read JSON test data:

**src/test/resources/test-data/products.json:**
```json
[
  {
    "name": "Laptop",
    "price": 999.99,
    "category": "Electronics",
    "inStock": true
  },
  {
    "name": "Mouse",
    "price": 29.99,
    "category": "Accessories",
    "inStock": true
  }
]
```

```java
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.type.TypeReference;

public class JsonDataReader {

    private static final ObjectMapper mapper = new ObjectMapper();

    public static <T> List<T> readJson(String filePath, Class<T> type) {
        try {
            InputStream stream = JsonDataReader.class
                .getResourceAsStream(filePath);
            return mapper.readValue(stream,
                mapper.getTypeFactory().constructCollectionType(List.class, type));
        } catch (IOException e) {
            throw new RuntimeException("Failed to read JSON file: " + filePath, e);
        }
    }
}

// Usage
@MethodSource("productData")
static Stream<Product> productData() {
    List<Product> products = JsonDataReader.readJson(
        "/test-data/products.json",
        Product.class
    );
    return products.stream();
}
```

### Reading from Excel Files

Use Apache POI for Excel files:

```xml
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.2.3</version>
    <scope>test</scope>
</dependency>
```

```java
import org.apache.poi.ss.usermodel.*;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;

public class ExcelDataReader {

    public static List<Map<String, String>> readExcel(String filePath, String sheetName) {
        List<Map<String, String>> data = new ArrayList<>();

        try (FileInputStream fis = new FileInputStream(filePath);
             Workbook workbook = new XSSFWorkbook(fis)) {

            Sheet sheet = workbook.getSheet(sheetName);
            Row headerRow = sheet.getRow(0);

            for (int i = 1; i <= sheet.getLastRowNum(); i++) {
                Row row = sheet.getRow(i);
                Map<String, String> rowData = new HashMap<>();

                for (int j = 0; j < headerRow.getLastCellNum(); j++) {
                    String header = headerRow.getCell(j).getStringCellValue();
                    String value = getCellValueAsString(row.getCell(j));
                    rowData.put(header, value);
                }
                data.add(rowData);
            }
        } catch (IOException e) {
            throw new RuntimeException("Failed to read Excel file", e);
        }

        return data;
    }

    private static String getCellValueAsString(Cell cell) {
        if (cell == null) return "";

        switch (cell.getCellType()) {
            case STRING: return cell.getStringCellValue();
            case NUMERIC: return String.valueOf(cell.getNumericCellValue());
            case BOOLEAN: return String.valueOf(cell.getBooleanCellValue());
            default: return "";
        }
    }
}
```

## Test Data Builders

Use the Builder pattern for complex test data:

```java
public class UserBuilder {
    private String username;
    private String email;
    private String password;
    private String role = "USER";
    private boolean active = true;

    public static UserBuilder aUser() {
        return new UserBuilder();
    }

    public UserBuilder withUsername(String username) {
        this.username = username;
        return this;
    }

    public UserBuilder withEmail(String email) {
        this.email = email;
        return this;
    }

    public UserBuilder withPassword(String password) {
        this.password = password;
        return this;
    }

    public UserBuilder withRole(String role) {
        this.role = role;
        return this;
    }

    public UserBuilder inactive() {
        this.active = false;
        return this;
    }

    public User build() {
        return new User(username, email, password, role, active);
    }
}

// Usage
@MethodSource("userTestData")
static Stream<User> userTestData() {
    return Stream.of(
        aUser().withUsername("admin").withRole("ADMIN").build(),
        aUser().withUsername("user1").withEmail("user1@example.com").build(),
        aUser().withUsername("inactive").inactive().build()
    );
}
```

## Using Faker for Random Data

Generate realistic random test data:

```xml
<dependency>
    <groupId>com.github.javafaker</groupId>
    <artifactId>javafaker</artifactId>
    <version>1.0.2</version>
    <scope>test</scope>
</dependency>
```

```java
import com.github.javafaker.Faker;

public class TestDataGenerator {
    private static final Faker faker = new Faker();

    public static User randomUser() {
        return aUser()
            .withUsername(faker.name().username())
            .withEmail(faker.internet().emailAddress())
            .withPassword(faker.internet().password(8, 16))
            .build();
    }

    public static Product randomProduct() {
        return new Product(
            faker.commerce().productName(),
            Double.parseDouble(faker.commerce().price()),
            faker.commerce().department()
        );
    }
}

// Usage in tests
@ParameterizedTest
@MethodSource("randomUsers")
void shouldRegisterRandomUsers(User user) {
    registration.registerUser(user);
    registration.shouldSucceed();
}

static Stream<User> randomUsers() {
    return Stream.generate(TestDataGenerator::randomUser).limit(10);
}
```

## Best Practices

### 1. Keep Test Data Close to Tests

```
src/test/resources/
├── test-data/
│   ├── users/
│   │   ├── valid-users.csv
│   │   └── invalid-users.csv
│   ├── products/
│   │   └── products.json
│   └── shared/
│       └── countries.csv
```

### 2. Use Meaningful Test Names

```java
@ParameterizedTest(name = "User ''{0}'' with role ''{1}'' should access ''{2}''")
@CsvSource({
    "admin, ADMIN, dashboard",
    "user,  USER,  homepage"
})
void accessControlTests(String username, String role, String page) {
    // Test implementation
}
```

### 3. Validate Test Data

```java
@MethodSource("userData")
static Stream<User> userData() {
    return loadUsersFromCsv("/test-data/users.csv")
        .stream()
        .peek(user -> {
            assertThat(user.getEmail()).contains("@");
            assertThat(user.getPassword()).hasSizeGreaterThan(8);
        });
}
```

### 4. Isolate Test Data

Ensure each test has its own independent data:

```java
@BeforeEach
void setUp() {
    // Clean up any existing test data
    testDataCleanup.deleteTestUsers();
}

@ParameterizedTest
@MethodSource("userTestData")
void userTests(User user) {
    // Each test gets fresh data
    String uniqueUsername = user.getUsername() + "_" + UUID.randomUUID();
    User isolatedUser = user.withUsername(uniqueUsername);
    // Test with isolated data
}
```

### 5. Document Data Requirements

```java
/**
 * Tests user registration with various valid inputs.
 *
 * Test data requirements:
 * - Username: 3-20 characters, alphanumeric
 * - Email: Valid email format
 * - Password: Minimum 8 characters
 * - Role: One of [USER, ADMIN, MANAGER]
 */
@ParameterizedTest
@CsvFileSource(resources = "/test-data/valid-users.csv")
void shouldRegisterValidUsers(String username, String email,
                              String password, String role) {
    // Test implementation
}
```

### 6. Separate Valid and Invalid Data

```java
// Valid data tests
@ParameterizedTest
@CsvFileSource(resources = "/test-data/valid-users.csv")
void shouldAcceptValidUsers(User user) {
    // Expect success
}

// Invalid data tests
@ParameterizedTest
@CsvFileSource(resources = "/test-data/invalid-users.csv")
void shouldRejectInvalidUsers(User user, String expectedError) {
    // Expect specific error
}
```

## Complete Example: E-Commerce Testing

Here's a complete example combining multiple techniques:

**Product.java:**
```java
public class Product {
    private final String name;
    private final double price;
    private final String category;
    private final boolean inStock;

    // Constructor, getters, builder...
}
```

**test-data/products.csv:**
```csv
name,price,category,inStock,expectedInCart
Laptop,999.99,Electronics,true,true
Headphones,79.99,Audio,true,true
Out of Stock Item,49.99,Misc,false,false
```

**ShoppingTests.java:**
```java
@ExtendWith(SerenityJUnit5Extension.class)
class ShoppingTests {

    @Steps
    ShoppingActions shopping;

    @ParameterizedTest(name = "Adding {0} (${1}) should {4}")
    @CsvFileSource(resources = "/test-data/products.csv", numLinesToSkip = 1)
    void shouldHandleProductAddition(String name, double price, String category,
                                     boolean inStock, boolean expectedInCart) {
        Product product = new Product(name, price, category, inStock);

        shopping.addProductToCart(product);

        if (expectedInCart) {
            shopping.shouldSeeProductInCart(product);
            shopping.cartTotalShouldBe(price);
        } else {
            shopping.shouldSeeOutOfStockMessage();
        }
    }
}
```

## Troubleshooting

### Issue: Parameterized tests not running

**Solution:** Ensure you have the junit-jupiter-params dependency and use `@ParameterizedTest` not `@Test`.

### Issue: CSV data not loading

**Solution:**
- Check file path is relative to `src/test/resources`
- Verify `numLinesToSkip` is set correctly
- Check for proper CSV formatting

### Issue: Data appearing in wrong order

**Solution:** JUnit doesn't guarantee execution order. Use `@TestMethodOrder` if needed:

```java
@TestMethodOrder(OrderAnnotation.class)
class OrderedTests {
    @ParameterizedTest
    @Order(1)
    @ValueSource(strings = {"first"})
    void test1(String value) { }
}
```

## Next Steps

- Explore [Screenplay Pattern](/docs/screenplay/screenplay_fundamentals) for better test organization
- Learn about [Parallel Execution](/docs/junit5/parallel-execution) to speed up data-driven tests
- Check out [Serenity Reports](/docs/reporting/the_serenity_reports) to see how parameterized tests appear in reports

## Additional Resources

- [JUnit 5 Parameterized Tests Guide](https://junit.org/junit5/docs/current/user-guide/#writing-tests-parameterized-tests)
- [Cucumber Scenario Outlines](https://cucumber.io/docs/gherkin/reference/#scenario-outline)
- [JavaFaker Documentation](https://github.com/DiUS/java-faker)


---

<!-- https://serenity-bdd.github.io/docs/tutorials/migrating_to_serenity_4 -->

# Migrating From Serenity BDD 3.x to Serenity BDD 4.x

## Introduction
Serenity BDD 4.0.0 is a significant update that aligns with modern testing libraries by supporting JDK 17. This major release includes changes to package structures, reflecting adjustments in the module structure for JDK 17. If you are migrating from Serenity 3.x to Serenity 4.x, this tutorial will guide you through the necessary steps to make your project compatible with the latest version.

## Step 1: Ensure JDK 17 Compatibility
Make sure your project is compatible with JDK 17, as Serenity BDD 4.x requires it as a minimum version. If you are using Maven, update your project's `pom.xml` file to include the `maven-compiler-plugin` configured for JDK 17. Here's an example:

```xml
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.8.1</version>
  <configuration>
    <source>11</source>
    <target>11</target>
  </configuration>
</plugin>
```

If your project uses Gradle, you'll need to specify the Java version in your `build.gradle` file to ensure compatibility with JDK 17. Here's an example:

```groovy
plugins {
  id 'java'
}

sourceCompatibility = '11'
targetCompatibility = '11'
```

## Step 2: Update Serenity Dependencies
Update the Serenity BDD dependencies in your project's build file to the latest 4.x version, e.g.

```xml
    <properties>
        <serenity.version>4.0.0</serenity.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-core</artifactId>
            <version>${serenity.version}</version>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-junit</artifactId>
            <version>${serenity.version}</version>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay</artifactId>
            <version>${serenity.version}</version>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay-webdriver</artifactId>
            <version>${serenity.version}</version>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-ensure</artifactId>
            <version>${serenity.version}</version>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-cucumber</artifactId>
            <version>${serenity.version}</version>
        </dependency>
    </dependencies>

```

## Step 3: Modify Annotations
Because of Java 9 module constraints, some of the packages have changed places in the new version. Most importantly, all of the main Serenity annotations can now be found in the `net.serenitybdd.annotations` package.

In your project, replace the main Serenity annotations, such as `@Step`, to the new package `net.serenitybdd.annotations` from the old package `net.thucydides.core.annotations`. If your project is large, you can update all of your annotations in one go like this:

![](img/replace-serenity-annotations.png)

## Step 4: Update Package References
If you are using internal Serenity classes, you may need to modify the relevant package references in your code based on the following table:

| Module                        | Old packages                                 | New Packages |
| --------                      | ------------                                 | ------------ |
| serenity-screenplay-webdriver | net.serenity.screenplay.*                    | net.serenity.screenplay.webdriver.* |
|                               | net.serenitybdd.screenplay.webtest.actions.* | net.serenitybdd.screenplay.webdriver.actions.* |
| serenity-model                | net.serenitybdd.core.*                       | net.serenitybdd.model.* |
|                               | net.thucydides.core.annotations.*            | net.serenitybdd.annotations.* |
|                               | Other net.thucydides.core.*                  | net.thucydides.model.*  |

For example, you may need to replace `net.thucydides.core.util.EnvironmentVariables` with `net.thucydides.model.util.EnvironmentVariables`


## Step 5: Test Your Changes
After making these changes, run your test suite to verify that everything is working correctly with the new Serenity BDD version. Pay particular attention to the following:
- **Requirements Hierarchy:** Ensure that the requirements hierarchy is displaying correctly in your reports.
- **Test Execution:** Confirm that all your tests are being executed as expected, without any missing or failing tests that previously succeeded.

## Conclusion
Migrating to Serenity BDD 4.x involves updating package references to align with the new JDK 17 module structure. Follow the steps above, and consult the official Serenity BDD documentation for additional information or support.

Remember to thoroughly test your updated project, particularly focusing on the requirements hierarchy and test execution, to ensure that the migration has been successful.


---

<!-- https://serenity-bdd.github.io/docs/tutorials/cicd-integration -->

# CI/CD Integration with Serenity BDD

This guide shows you how to integrate Serenity BDD tests into popular CI/CD platforms, including GitHub Actions, Jenkins, and GitLab CI. Learn how to run tests automatically, publish reports, and get fast feedback on your code changes.

## Prerequisites

- Serenity BDD project configured with Maven or Gradle
- Version control repository (Git)
- Access to a CI/CD platform

## Quick Start Checklist

Before setting up CI/CD, ensure your project:
- ✅ Runs successfully locally with `mvn clean verify` or `gradle clean test`
- ✅ Has all dependencies properly configured
- ✅ Uses headless browser mode for web tests
- ✅ Has reasonable test execution timeouts
- ✅ Generates Serenity reports in `target/site/serenity` (Maven) or `build/reports/serenity` (Gradle)

## GitHub Actions

GitHub Actions is the easiest way to set up CI/CD for projects hosted on GitHub.

### Basic Setup

Create `.github/workflows/serenity-tests.yml` in your repository:

```yaml
name: Serenity BDD Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: 'maven'

    - name: Run Serenity tests
      run: mvn clean verify

    - name: Publish Serenity Report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: serenity-report
        path: target/site/serenity
        retention-days: 30
```

### Gradle Version

For Gradle projects:

```yaml
name: Serenity BDD Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: 'gradle'

    - name: Run Serenity tests
      run: ./gradlew clean test aggregate

    - name: Publish Serenity Report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: serenity-report
        path: build/reports/serenity
        retention-days: 30
```

### Publishing Reports to GitHub Pages

Automatically publish Serenity reports as a website:

```yaml
name: Serenity Tests with GitHub Pages

on:
  push:
    branches: [ main ]

permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: 'maven'

    - name: Run Serenity tests
      run: mvn clean verify

    - name: Deploy to GitHub Pages
      if: always()
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./target/site/serenity
        destination_dir: reports/${{ github.run_number }}
```

**Access your reports at:** `https://<username>.github.io/<repository>/reports/<run-number>`

### Parallel Execution in GitHub Actions

Run tests in parallel using a matrix strategy:

```yaml
name: Serenity Parallel Tests

on:
  push:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        browser: [chrome, firefox, edge]
        test-suite: [smoke, regression]
      fail-fast: false

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: 'maven'

    - name: Run tests
      run: mvn verify -Dwebdriver.driver=${{ matrix.browser }} -Dtags=${{ matrix.test-suite }}

    - name: Upload Report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: report-${{ matrix.browser }}-${{ matrix.test-suite }}
        path: target/site/serenity
```

### Advanced Configuration with Environment Variables

```yaml
name: Serenity Tests - All Environments

on:
  push:
    branches: [ main ]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to test'
        required: true
        type: choice
        options:
          - dev
          - staging
          - production

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: 'maven'

    - name: Run tests
      env:
        BASE_URL: ${{ secrets[format('{0}_BASE_URL', github.event.inputs.environment || 'dev')] }}
        API_KEY: ${{ secrets[format('{0}_API_KEY', github.event.inputs.environment || 'dev')] }}
        TEST_USER: ${{ secrets.TEST_USER }}
        TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
      run: |
        mvn clean verify \
          -Dwebdriver.base.url=$BASE_URL \
          -Dapi.key=$API_KEY \
          -Dtest.user=$TEST_USER \
          -Dtest.password=$TEST_PASSWORD

    - name: Upload Report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: serenity-report-${{ github.event.inputs.environment || 'dev' }}
        path: target/site/serenity
```

### Notifications

Send Slack notifications on test results:

```yaml
    - name: Notify Slack on Success
      if: success()
      uses: slackapi/slack-github-action@v1
      with:
        webhook-url: ${{ secrets.SLACK_WEBHOOK }}
        payload: |
          {
            "text": "✅ Serenity Tests Passed - Build #${{ github.run_number }}"
          }

    - name: Notify Slack on Failure
      if: failure()
      uses: slackapi/slack-github-action@v1
      with:
        webhook-url: ${{ secrets.SLACK_WEBHOOK }}
        payload: |
          {
            "text": "❌ Serenity Tests Failed - Build #${{ github.run_number }}\nView: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          }
```

## Jenkins

Jenkins is a popular self-hosted CI/CD platform with extensive plugin support.

### Declarative Pipeline

Create a `Jenkinsfile` in your repository root:

```groovy
pipeline {
    agent any

    tools {
        maven 'Maven-3.9'
        jdk 'JDK-17'
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build and Test') {
            steps {
                sh 'mvn clean verify'
            }
        }

        stage('Publish Reports') {
            steps {
                publishHTML([
                    reportDir: 'target/site/serenity',
                    reportFiles: 'index.html',
                    reportName: 'Serenity Report',
                    keepAll: true,
                    alwaysLinkToLastBuild: true,
                    allowMissing: false
                ])
            }
        }
    }

    post {
        always {
            junit '**/target/failsafe-reports/*.xml'
            archiveArtifacts artifacts: 'target/site/serenity/**/*', allowEmptyArchive: true
        }
        failure {
            emailext(
                subject: "Failed: ${currentBuild.fullDisplayName}",
                body: "Test execution failed. Check console output at ${env.BUILD_URL}",
                to: 'team@example.com'
            )
        }
    }
}
```

### Gradle Pipeline

```groovy
pipeline {
    agent any

    tools {
        gradle 'Gradle-8'
        jdk 'JDK-17'
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build and Test') {
            steps {
                sh './gradlew clean test aggregate'
            }
        }

        stage('Publish Reports') {
            steps {
                publishHTML([
                    reportDir: 'build/reports/serenity',
                    reportFiles: 'index.html',
                    reportName: 'Serenity Report',
                    keepAll: true,
                    alwaysLinkToLastBuild: true
                ])
            }
        }
    }

    post {
        always {
            junit '**/build/test-results/test/*.xml'
        }
    }
}
```

### Parallel Execution in Jenkins

Run tests in parallel across multiple nodes:

```groovy
pipeline {
    agent none

    stages {
        stage('Parallel Tests') {
            parallel {
                stage('Chrome Tests') {
                    agent { label 'chrome' }
                    steps {
                        sh 'mvn verify -Dwebdriver.driver=chrome'
                    }
                }
                stage('Firefox Tests') {
                    agent { label 'firefox' }
                    steps {
                        sh 'mvn verify -Dwebdriver.driver=firefox'
                    }
                }
                stage('Edge Tests') {
                    agent { label 'edge' }
                    steps {
                        sh 'mvn verify -Dwebdriver.driver=edge'
                    }
                }
            }
        }

        stage('Aggregate Reports') {
            agent any
            steps {
                publishHTML([
                    reportDir: 'target/site/serenity',
                    reportFiles: 'index.html',
                    reportName: 'Consolidated Serenity Report'
                ])
            }
        }
    }
}
```

### Jenkins Configuration with Parameters

```groovy
pipeline {
    agent any

    parameters {
        choice(
            name: 'ENVIRONMENT',
            choices: ['dev', 'staging', 'production'],
            description: 'Environment to test'
        )
        choice(
            name: 'BROWSER',
            choices: ['chrome', 'firefox', 'edge'],
            description: 'Browser to use'
        )
        string(
            name: 'TAGS',
            defaultValue: '',
            description: 'Tags to filter tests (e.g., @smoke, @regression)'
        )
    }

    stages {
        stage('Test') {
            steps {
                script {
                    def baseUrl = ""
                    switch(params.ENVIRONMENT) {
                        case 'dev':
                            baseUrl = 'https://dev.example.com'
                            break
                        case 'staging':
                            baseUrl = 'https://staging.example.com'
                            break
                        case 'production':
                            baseUrl = 'https://www.example.com'
                            break
                    }

                    sh """
                        mvn clean verify \
                        -Dwebdriver.driver=${params.BROWSER} \
                        -Dwebdriver.base.url=${baseUrl} \
                        -Dcucumber.filter.tags='${params.TAGS}'
                    """
                }
            }
        }
    }
}
```

### Installing Jenkins Plugins

Required plugins:
```bash
# Install via Jenkins CLI or UI
- HTML Publisher Plugin
- JUnit Plugin
- Pipeline Plugin
- Git Plugin
- Email Extension Plugin
```

## GitLab CI

GitLab CI is integrated directly into GitLab repositories.

### Basic Configuration

Create `.gitlab-ci.yml` in your repository root:

```yaml
image: maven:3.9-eclipse-temurin-17

stages:
  - test
  - report

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"

cache:
  paths:
    - .m2/repository

test:
  stage: test
  script:
    - mvn clean verify
  artifacts:
    when: always
    paths:
      - target/site/serenity
    expire_in: 30 days
    reports:
      junit:
        - target/failsafe-reports/TEST-*.xml

pages:
  stage: report
  script:
    - mkdir -p public
    - cp -r target/site/serenity/* public/
  artifacts:
    paths:
      - public
  only:
    - main
```

**Reports will be available at:** `https://<username>.gitlab.io/<project>/`

### Gradle Version

```yaml
image: gradle:8-jdk17

stages:
  - test
  - report

variables:
  GRADLE_OPTS: "-Dorg.gradle.daemon=false"

cache:
  paths:
    - .gradle

test:
  stage: test
  script:
    - gradle clean test aggregate
  artifacts:
    when: always
    paths:
      - build/reports/serenity
    expire_in: 30 days
    reports:
      junit:
        - build/test-results/test/TEST-*.xml

pages:
  stage: report
  script:
    - mkdir -p public
    - cp -r build/reports/serenity/* public/
  artifacts:
    paths:
      - public
  only:
    - main
```

### Multiple Environments

```yaml
stages:
  - test

.test_template:
  image: maven:3.9-eclipse-temurin-17
  script:
    - mvn clean verify -Dwebdriver.base.url=$BASE_URL
  artifacts:
    when: always
    paths:
      - target/site/serenity
    expire_in: 7 days

test:dev:
  extends: .test_template
  variables:
    BASE_URL: "https://dev.example.com"
  only:
    - develop

test:staging:
  extends: .test_template
  variables:
    BASE_URL: "https://staging.example.com"
  only:
    - staging

test:production:
  extends: .test_template
  variables:
    BASE_URL: "https://www.example.com"
  only:
    - main
  when: manual
```

### Parallel Jobs

```yaml
test:
  stage: test
  parallel:
    matrix:
      - BROWSER: [chrome, firefox]
        SUITE: [smoke, regression]
  script:
    - mvn verify -Dwebdriver.driver=$BROWSER -Dtags=@$SUITE
  artifacts:
    when: always
    paths:
      - target/site/serenity
    reports:
      junit:
        - target/failsafe-reports/TEST-*.xml
```

## Azure Pipelines

For projects hosted on Azure DevOps:

Create `azure-pipelines.yml`:

```yaml
trigger:
  - main
  - develop

pool:
  vmImage: 'ubuntu-latest'

variables:
  MAVEN_CACHE_FOLDER: $(Pipeline.Workspace)/.m2/repository
  MAVEN_OPTS: '-Dmaven.repo.local=$(MAVEN_CACHE_FOLDER)'

steps:
- task: JavaToolInstaller@0
  inputs:
    versionSpec: '17'
    jdkArchitectureOption: 'x64'
    jdkSourceOption: 'PreInstalled'

- task: Cache@2
  inputs:
    key: 'maven | "$(Agent.OS)" | **/pom.xml'
    path: $(MAVEN_CACHE_FOLDER)
  displayName: Cache Maven packages

- task: Maven@3
  inputs:
    mavenPomFile: 'pom.xml'
    goals: 'clean verify'
    options: '-B'
  displayName: 'Run Serenity Tests'

- task: PublishTestResults@2
  condition: always()
  inputs:
    testResultsFormat: 'JUnit'
    testResultsFiles: '**/target/failsafe-reports/TEST-*.xml'
    testRunTitle: 'Serenity Test Results'

- task: PublishBuildArtifacts@1
  condition: always()
  inputs:
    PathtoPublish: 'target/site/serenity'
    ArtifactName: 'serenity-report'
  displayName: 'Publish Serenity Report'
```

## Docker Integration

Run tests in Docker containers for consistency.

### Dockerfile for Tests

```dockerfile
FROM maven:3.9-eclipse-temurin-17

# Install Chrome
RUN wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && echo "deb http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list \
    && apt-get update \
    && apt-get install -y google-chrome-stable \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY pom.xml .
RUN mvn dependency:go-offline

COPY src ./src

CMD ["mvn", "clean", "verify"]
```

### Docker Compose

```yaml
version: '3.8'

services:
  serenity-tests:
    build: .
    volumes:
      - ./target:/app/target
    environment:
      - WEBDRIVER_DRIVER=chrome
      - WEBDRIVER_BASE_URL=https://example.com
```

### GitHub Actions with Docker

```yaml
- name: Build and run tests in Docker
  run: |
    docker build -t serenity-tests .
    docker run --rm -v $PWD/target:/app/target serenity-tests
```

## Best Practices

### 1. Use Headless Browsers

Configure headless mode for CI environments:

**serenity.conf:**
```hocon
webdriver {
  driver = chrome
  capabilities {
    browserName = "chrome"
    "goog:chromeOptions" {
      args = ["--headless", "--no-sandbox", "--disable-dev-shm-usage", "--disable-gpu"]
    }
  }
}
```

### 2. Optimize Build Times

**Cache dependencies:**
```yaml
# GitHub Actions
- uses: actions/cache@v3
  with:
    path: ~/.m2/repository
    key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}

# GitLab CI
cache:
  paths:
    - .m2/repository
```

**Skip unnecessary phases:**
```bash
mvn verify -DskipTests  # Skip test execution
mvn verify -Dmaven.test.skip=true  # Skip test compilation
```

### 3. Fail Fast

Configure builds to fail fast on critical errors:

```yaml
strategy:
  fail-fast: true  # Stop all jobs if one fails
```

### 4. Tag-Based Execution

Run different test suites in different pipelines:

```bash
# Smoke tests on every commit
mvn verify -Dcucumber.filter.tags="@smoke"

# Full regression on main branch
mvn verify -Dcucumber.filter.tags="@regression"
```

### 5. Separate Test Stages

```yaml
stages:
  - unit-tests
  - integration-tests
  - smoke-tests
  - regression-tests
```

### 6. Manage Secrets Securely

Never commit credentials:
```yaml
# GitHub Actions
env:
  API_KEY: ${{ secrets.API_KEY }}

# GitLab CI
variables:
  API_KEY: ${{ secrets.API_KEY }}
```

### 7. Retry Flaky Tests

```groovy
// Jenkins
retry(3) {
    sh 'mvn verify'
}
```

```yaml
# GitLab CI
test:
  retry:
    max: 2
    when: runner_system_failure
```

### 8. Generate Build Badges

Add status badges to your README:

**GitHub Actions:**
```markdown
![Tests](https://github.com/username/repo/actions/workflows/serenity-tests.yml/badge.svg)
```

**GitLab CI:**
```markdown
![pipeline status](https://gitlab.com/username/project/badges/main/pipeline.svg)
```

## Troubleshooting

### Issue: Tests fail only in CI

**Common causes:**
- Browser not installed or incompatible version
- Missing display server (X11)
- Insufficient memory
- Network/firewall issues

**Solutions:**
```yaml
# Add display server for Linux
before_script:
  - export DISPLAY=:99
  - Xvfb :99 -screen 0 1920x1080x24 &

# Increase memory
env:
  MAVEN_OPTS: "-Xmx2g"
```

### Issue: Reports not publishing

**Check:**
- Correct path to report directory
- `if: always()` condition is set
- Sufficient permissions

### Issue: Slow builds

**Solutions:**
- Cache dependencies
- Use parallel execution
- Run subset of tests (smoke tests first)
- Use Docker layer caching

## Complete Example: GitHub Actions with All Features

```yaml
name: Serenity BDD - Production Ready

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM
  workflow_dispatch:

env:
  JAVA_VERSION: '17'
  MAVEN_OPTS: '-Xmx2g'

jobs:
  smoke-tests:
    name: Smoke Tests
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Set up JDK
      uses: actions/setup-java@v4
      with:
        java-version: ${{ env.JAVA_VERSION }}
        distribution: 'temurin'
        cache: 'maven'

    - name: Run smoke tests
      run: mvn verify -Dcucumber.filter.tags="@smoke"

    - name: Upload smoke test report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: smoke-test-report
        path: target/site/serenity

  regression-tests:
    name: Regression Tests
    runs-on: ubuntu-latest
    needs: smoke-tests
    if: github.ref == 'refs/heads/main'

    strategy:
      matrix:
        browser: [chrome, firefox]
      fail-fast: false

    steps:
    - uses: actions/checkout@v4

    - name: Set up JDK
      uses: actions/setup-java@v4
      with:
        java-version: ${{ env.JAVA_VERSION }}
        distribution: 'temurin'
        cache: 'maven'

    - name: Run regression tests
      run: mvn verify -Dwebdriver.driver=${{ matrix.browser }}

    - name: Upload report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: report-${{ matrix.browser }}
        path: target/site/serenity

  publish-report:
    name: Publish Report to GitHub Pages
    runs-on: ubuntu-latest
    needs: [smoke-tests, regression-tests]
    if: always() && github.ref == 'refs/heads/main'

    permissions:
      contents: write
      pages: write

    steps:
    - uses: actions/download-artifact@v4
      with:
        name: smoke-test-report
        path: reports/smoke

    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./reports
```

## Next Steps

- Learn about [Parallel Execution](/docs/junit5/parallel-execution) to speed up CI builds
- Explore [Data-Driven Testing](/docs/tutorials/data-driven-testing) for comprehensive test coverage
- Check [Serenity Configuration](/docs/reference/serenity-properties) for optimizing CI performance

## Additional Resources

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [Jenkins Pipeline Documentation](https://www.jenkins.io/doc/book/pipeline/)
- [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)
- [Serenity BDD on Docker Hub](https://hub.docker.com/r/serenity)


---

<!-- https://serenity-bdd.github.io/docs/tutorials/running_cucumber_scenarios_in_parallel -->

# How to Do Parallel Test Execution in Cucumber with Serenity

Cucumber 7 has introduced native support for parallel execution at both the feature and scenario levels. This parallel execution can provide significant performance improvements in test runs. If you want to harness these performance improvements and run your Serenity BDD features and scenarios in parallel, you will need to upgrade to JUnit 5.

## Pre-requisites

- **Cucumber 7.x**
- **Serenity BDD 3.9.8 or 4.0.x**
- **Maven 3.x** for building the project

Now, let's get started with the detailed step-by-step guide.

## Step 1: Update Serenity BDD to a Recent Version

Before proceeding, make sure that you have a recent version of Serenity BDD. Versions 3.9.8 or 4.0.x are recommended for best results.

You can check your current version in your `pom.xml` file or update it to the latest version.

## Step 2: Update to JUnit 5 in Your Maven Project

JUnit 5 provides the foundation for running tests in parallel with Cucumber and Serenity. Here's how you can update to JUnit 5 in your `pom.xml` file:

1. Open the `pom.xml` file in your Maven project.
2. Add the following dependencies for JUnit 5 and Cucumber 7.

    ```xml
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.junit</groupId>
                <artifactId>junit-bom</artifactId>
                <version>5.10.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        ...
        <!-- JUNIT 5 Dependencies -->
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-launcher</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-suite</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-junit-platform-engine</artifactId>
            <version>7.2.3</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
    ```

More details on JUnit 5 and Maven can be found in the [JUnit 5 User Guide](https://junit.org/junit5/docs/current/user-guide/#running-tests-build-maven).

## Step 3: Create a `junit-platform.properties` File

Create a new file named `junit-platform.properties` in your `src/test/resources` folder. This file enables and configures parallel execution.

Add the following content to the file:

```properties
cucumber.execution.parallel.enabled=true
cucumber.execution.parallel.config.strategy=dynamic
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel
```

:::note Breaking Change in Serenity 5.0.0
The Cucumber plugin path changed from `io.cucumber.core.plugin.*` to `net.serenitybdd.cucumber.core.plugin.*` in Serenity 5.0.0. Make sure to use the updated path shown above.
:::

These properties enable parallel execution and configure it to use a dynamic strategy, along with the Serenity reporter for parallel execution.

## Step 4: Create a `cucumber.properties` File

Create a new file named `cucumber.properties` in your `src/test/resources` folder. This file will contain the Cucumber options for your Cucumber tests.

Add the following content to the file:

```properties
cucumber.execution.order = random
cucumber.plugin=pretty,json:target/cucumber.json,timeline:target/test-results/timeline
cucumber.snippet-type=camelcase
```

You can find more details on Cucumber configuration options in the [Cucumber documentation](https://cucumber.io/docs/cucumber/api/?lang=java#list-configuration-options).

## Step 5: Update Your Cucumber Runner Class

You should have a single runner class for your whole test suite. Update it as follows:

```java
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectClasspathResource;
import org.junit.platform.suite.api.Suite;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("/features")
public class AcceptanceTestSuite {}
```

This runner class will include all the features in the `/features` directory and run them using the Cucumber engine.

## Conclusion

That's it! By following these steps, you can leverage the power of parallel execution with Cucumber and Serenity BDD. This will significantly reduce the execution time of your test suite, leading to faster feedback and more efficient development cycles.

Happy testing! 🚀


---

<!-- https://serenity-bdd.github.io/docs/tutorials/streamlining_your_serenity_reports -->

# Three Strategies to Optimize Your Serenity BDD Reports

Serenity BDD stands out for its ability to produce detailed and informative reports. These reports offer insights not just on executed tests, but also on the fulfillment of business requirements. But like all tools, getting the most out of Serenity BDD involves a few tweaks and optimizations.

Here are three strategies to make your Serenity BDD reports more efficient:

1. **Stay Updated!**

   Ensure you're working with the latest version of Serenity BDD, ideally 4.0.12 or newer. With each update, you'll find several optimizations to enhance report performance and minimize generated files. For instance, standard report generation in version 4.0.11 is up to 10 times faster than in 3.9.8.

2. **Opt Out of Duration Reporting**

   By default, Serenity BDD generates in-depth reports detailing the runtime for each test. While these reports are richer in information, they consume more disk space. For substantial projects where disk space becomes an issue, consider turning off duration reporting. This can be done by setting the `serenity.report.test.durations` flag to false. As a testament to its efficacy, one project with over 11,000 tests witnessed its report size shrink from 397M to 250M, and the generation time was halved.

3. **Limit Screenshots to Failed Tests**

   When conducting web tests, a useful approach to conserve space is by capturing screenshots exclusively for failed tests. Achieve this by adjusting the `serenity.take.screenshots` property to FOR_FAILURES. This tweak not only accelerates the tests but also trims down the report size. Keep in mind, however, that this might slightly reduce the detail in your reporting.

Harness the power of Serenity BDD more effectively by applying these strategies and enjoy a streamlined testing report experience.


---

<!-- https://serenity-bdd.github.io/docs/guide/user_guide_intro -->

# Introduction

Serenity BDD is an open source library that aims to make the idea of living documentation a reality.

Serenity BDD helps you write cleaner and more maintainable automated acceptance and regression tests faster. Serenity also uses the test results to produce illustrated, narrative reports that document and describe what your application does and how it works. Serenity tells you not only what tests have been executed, but more importantly, what requirements have been tested.

![](img/intro-functional-coverage.png)

One key advantage of using Serenity BDD is that you do not have to invest time in building and maintaining your own automation framework. Serenity BDD provides strong support for different types of automated acceptance testing, including:
- Web testing with Selenium.
- REST API testing with RestAssured.
- Highly readable, maintainable and scalable automated testing with the Screenplay pattern.
- BDD-style executable specifications with Cucumber

Serenity not only reports on what requirements were tested, it also reports on _how_ they were tested. It includes step-by-step details of how a test played out, including optional screenshots, so your tests truly document what your application does.

![](img/intro-step-details.png)

But Serenity is not just about reporting. The underlying aim of Serenity is to make it easy to quickly write well-structured, maintainable automated acceptance criteria, using your favourite BDD or conventional testing library. You can work with Behaviour-Driven-Development tools like Cucumber, or simply use JUnit (4 or 5). You can integrate with requirements stored in an external source (such as JIRA or any other test cases management tool), or just use a simple directory-based approach to organise your requirements.

![](img/intro-scenario.png)

Serenity also provides a host of built-in features that make coding your test automation faster and more reliable. Testers working with Serenity typically report automating tests with less than half the code they would need for a conventional Selenium test.

:::info
Up until November 2014, Serenity went by the name of Thucydides. Thucydides was an Ancient Greek historian who wrote about the Peloponnesian War in the late 5th Century BCE. He was the first historian to write about events that he actually participated in, and in many cases, he wrote down the events that he directly witnessed.

In a similar way Serenity BDD not only reports on test outcomes, but also records and documents how each scenario plays out, giving a particularly rich form of test reporting and living documentation.
:::
:::tip Using an AI coding assistant
Serenity has several equally valid ways of writing tests, and AI coding assistants often guess a package name or mix two of them. See [Using Serenity BDD with AI Coding Assistants](/docs/ai/ai_using_assistants) for pages with verified packages and idioms, `AGENTS.md` files for each style, an agent skill and `llms.txt`.
:::

![](img/intro-hoplites.jpeg)


---

<!-- https://serenity-bdd.github.io/docs/guide/getting_started -->

# Getting Started

## Creating A New Project With The Serenity BDD Templates

The quickest way to get started with a Serenity BDD project is to use one of the starter projects. These are template projects available on Github, that contain a basic Serenity BDD skeleton project and a single test implementation. These template projects are kept up-to-date with the most recent stable version of Serenity BDD.

The main available starter projects are the following:

| Template | Description | Get Started |
| -------- | ----------- | ------------|
| [Serenity BDD with JUnit](https://github.com/serenity-bdd/serenity-junit-starter) | A simple project structure using Serenity BDD, JUnit 5 and an Action Classes/Page Objects architecture. | **[Use This Template](https://github.com/serenity-bdd/serenity-junit-starter/generate)** |
| [Serenity BDD with JUnit and Screenplay](https://github.com/serenity-bdd/serenity-junit-screenplay-starter) | A project built around the Screenplay Pattern using Serenity BDD, JUnit 5 and Serenity Screenplay |  **[Use This Template](https://github.com/serenity-bdd/serenity-junit-screenplay-starter/generate)** |
| [Serenity BDD with Cucumber and Screenplay](https://github.com/serenity-bdd/serenity-cucumber-starter) | A BDD-style test suite using Cucumber and Serenity Screenplay | **[Use This Template](https://github.com/serenity-bdd/serenity-cucumber-starter/generate)** |

To create a new project, go to the project template you want to use, and click on the "Use this template" button. This will allow you to create a new project in your own Github repository.

![](img/use-this-template.png)

If you are working on an internal project, you can also download the template project by clicking on the "Code" button.


---

<!-- https://serenity-bdd.github.io/docs/guide/maven -->

# Integrating Serenity BDD into a Maven project

Maven is the recommended build tool for Serenity BDD.

You can add Serenity BDD to an existing Maven project by adding the corresponding dependencies to your `pom.xml` file.

## Using the Serenity BDD BOM (Recommended)

The simplest way to manage Serenity BDD dependencies is to use the **Bill of Materials (BOM)**. The BOM ensures that all Serenity modules use the same version, so you don't need to specify version numbers on each individual dependency.

Add the BOM to your `<dependencyManagement>` section:

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-bom</artifactId>
            <version>5.4.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

Then declare your Serenity dependencies **without version tags**:

```xml
<dependencies>
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-core</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-junit5</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay-webdriver</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-ensure</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

:::tip Upgrading
When a new version of Serenity BDD is released, you only need to update the single version number in the BOM import. All module versions will be updated automatically.
:::

## Managing Versions Manually

If you prefer not to use the BOM, you can manage versions manually by defining them in your properties section:

```xml
<properties>
    <serenity.version>5.4.1</serenity.version>
    <junit5.version>6.0.3</junit5.version>
    <cucumber.version>7.34.2</cucumber.version>
</properties>
```

## Core Dependencies

All Serenity BDD projects need the following core dependency:

```
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-core</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
```

You will also need a test runner, which will usually be either JUnit 5 (recommended) or Cucumber. Note that JUnit 4 is deprecated as of Serenity 5.0.0.

## Serenity JUnit 5 Dependencies (Recommended)
To use JUnit 5 you will need the following dependency:

```
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-junit5</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
```

You will also need the JUnit 5 dependencies, e.g.
```
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <version>${junit5.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>${junit5.version}</version>
    <scope>test</scope>
</dependency>
```

## Serenity JUnit 4 Dependencies (Deprecated)

:::warning JUnit 4 Deprecated
JUnit 4 support is deprecated as of Serenity 5.0.0 and will be removed in Serenity 6.0.0. Please migrate to JUnit 5 (see above).
:::

If you're still using JUnit 4, you will need the following dependency:

```
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-junit</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
```

## Serenity Cucumber Dependencies

For Cucumber you will need the following dependency:

```
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-cucumber</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
```

Since Serenity relies on a specific version of the Cucumber APIs, we recommend using the same version of the Cucumber libraries.

Cucumber requires a test runner, preferably JUnit 5 (JUnit 4 is deprecated).

## Cucumber with JUnit 5 Dependencies (Recommended)
To use JUnit 5 you will need the following dependency:

```
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit-platform-engine</artifactId>
    <version>${cucumber.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-suite</artifactId>
    <version>${junit-platform.version}</version>
    <scope>test</scope>
</dependency>
```

See cucumber-junit-platform-engine documentation on using junit-platform-suite to pilot cucumber: https://github.com/cucumber/cucumber-jvm/tree/main/junit-platform-engine#suites-with-different-configurations, and https://github.com/serenity-bdd/serenity-cucumber-starter for a running example.

## Cucumber with JUnit 4 Dependencies (Deprecated)

:::warning JUnit 4 Deprecated
JUnit 4 Cucumber runners are deprecated as of Serenity 5.0.0 and will be removed in Serenity 6.0.0. Please migrate to JUnit 5 (see above).
:::

If you're still using JUnit 4 with Cucumber, you will need the following dependency:

```
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit</artifactId>
    <version>${cucumber.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <version>${junit5.version}</version>
    <scope>test</scope>
</dependency>
```

## Screenplay
If you are using the Screenplay pattern, you will also need the Screenplay dependencies:
```
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-screenplay</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-rest-assured</artifactId>
    <version>${serenity.version}</version>
</dependency>
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-ensure</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-screenplay-webdriver</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
```

## Running Tests with Maven Failsafe

Serenity tests are integration tests and should be run using the Maven Failsafe plugin. The basic configuration is straightforward:

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>3.5.2</version>
    <configuration>
        <includes>
            <include>**/*Test.java</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

### Running JUnit 5 and Cucumber Tests Together

If your project contains both JUnit 5 tests and Cucumber tests, you may encounter a problem where only Cucumber tests are discovered and run. This happens because when Cucumber uses the `cucumber.features` property (either via `@ConfigurationParameter` or `junit-platform.properties`), it causes other JUnit Platform discovery selectors to be ignored.

You'll see a warning like this:

```
WARNING: TestEngine with ID 'cucumber' encountered a non-critical issue during test discovery:
Discovering tests using the cucumber.features property. Other discovery selectors are ignored!
```

**The solution** is to configure separate Failsafe executions for JUnit 5 and Cucumber tests:

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>3.5.2</version>
    <executions>
        <!-- Execution for JUnit Jupiter tests (excludes Cucumber) -->
        <execution>
            <id>junit-tests</id>
            <goals>
                <goal>integration-test</goal>
            </goals>
            <configuration>
                <includes>
                    <include>**/*Test.java</include>
                </includes>
                <excludes>
                    <exclude>**/CucumberTestSuite.java</exclude>
                </excludes>
            </configuration>
        </execution>
        <!-- Execution for Cucumber tests -->
        <execution>
            <id>cucumber-tests</id>
            <goals>
                <goal>integration-test</goal>
            </goals>
            <configuration>
                <includes>
                    <include>**/CucumberTestSuite.java</include>
                </includes>
            </configuration>
        </execution>
        <!-- Verify phase (runs once after all tests) -->
        <execution>
            <id>verify</id>
            <goals>
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

This configuration:
- Runs JUnit Jupiter tests first (all `*Test.java` files except the Cucumber suite)
- Runs Cucumber tests separately via the `CucumberTestSuite` class
- Runs the verify goal once at the end to check for failures

:::tip Naming Convention
Adjust the `<include>` and `<exclude>` patterns to match your test class naming conventions. For example, if your Cucumber suite is named `CucumberIT.java`, update the patterns accordingly.
:::

## The Serenity Maven Plugin

If you want to generate the Serenity reports whenever you run `mvn verify`, you can use the `serenity-maven-plugin` to do that:
```
<plugin>
    <groupId>net.serenity-bdd.maven.plugins</groupId>
    <artifactId>serenity-maven-plugin</artifactId>
    <version>${serenity.version}</version>
    <configuration>
      <tags>${tags}</tags>
    </configuration>
    <executions>
        <execution>
            <id>serenity-reports</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>aggregate</goal>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

By default, the `aggregate` goal will NOT fail the build if there are test failures - it will simply generate the reports. This way you can aggregate multiple report sets and then check for failures at the end using `mvn serenity:check`.

:::note When tests fail, `mvn verify` does not build the report
The `aggregate` goal is bound to the `post-integration-test` phase, which Maven never reaches when the tests fail. The per-test JSON files are still written to `target/site/serenity`, but there is no `index.html`. Either run the report goal after the failed build:

```
mvn net.serenity-bdd.maven.plugins:serenity-maven-plugin:aggregate
```

or let the build continue past test failures with `-Dmaven.test.failure.ignore=true` (the exit code is then 0 even when tests fail, so check the results another way on a CI server).
:::

:::note Old results are counted
Serenity reports every outcome file it finds in `target/site/serenity`, including files left by earlier runs. Use `mvn clean verify`, or delete that directory, so the report only covers the latest run.
:::

## Checking Gherkin feature files

Some errors in Gherkin feature files can cause the Serenity reports to behave unpredictably. For this reason, the following rules should be followed when working with Cucumber and Serenity:
  - Scenario names should be unique within a feature file
  - Scenario, Rule and Feature names should not be blank
  - Feature names should be unique wherever possible. In particular features with the same name, inside directories with identical names, will not appear correctly in the Serenity reports.

  You can check these rules before you run the full test by calling the `check-gherkin` goal, e.g.

```
mvn serenity:check-gherkin  
```

You can ensure that your feature files are correctly configured before kicking off your tests by binding the `check-gherkin` goal to the `process-test-resources` lifecycle phase, as shown here:

```
<plugin>
    <groupId>net.serenity-bdd.maven.plugins</groupId>
    <artifactId>serenity-maven-plugin</artifactId>
    <version>${serenity.version}</version>
    <configuration>
      <tags>${tags}</tags>
    </configuration>
    <executions>
        <execution>
            <id>check-feature-files</id>
            <phase>process-test-resources</phase>
            <goals>
                <goal>check-gherkin</goal>
            </goals>
        </execution>
        <execution>
            <id>serenity-reports</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

## Complete Example: JUnit 5 with BOM

Here is a complete `pom.xml` for a Serenity BDD project using JUnit 5, the Screenplay pattern, and the BOM:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>my-serenity-project</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <serenity.version>5.4.1</serenity.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>net.serenity-bdd</groupId>
                <artifactId>serenity-bom</artifactId>
                <version>${serenity.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Serenity core and JUnit 5 runner -->
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-core</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-junit5</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- Screenplay pattern -->
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay-webdriver</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-ensure</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-failsafe-plugin</artifactId>
                <version>3.5.2</version>
                <configuration>
                    <includes>
                        <include>**/*Test.java</include>
                    </includes>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>integration-test</goal>
                            <goal>verify</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>net.serenity-bdd.maven.plugins</groupId>
                <artifactId>serenity-maven-plugin</artifactId>
                <version>${serenity.version}</version>
                <executions>
                    <execution>
                        <id>serenity-reports</id>
                        <phase>post-integration-test</phase>
                        <goals>
                            <goal>aggregate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>
```

## Complete Example: Cucumber with BOM

Here is a complete `pom.xml` for a Serenity BDD project using Cucumber, JUnit 5, and the BOM:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>my-serenity-cucumber-project</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <serenity.version>5.4.1</serenity.version>
        <cucumber.version>7.34.2</cucumber.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>net.serenity-bdd</groupId>
                <artifactId>serenity-bom</artifactId>
                <version>${serenity.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Serenity core and Cucumber integration -->
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-core</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-cucumber</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- Screenplay pattern -->
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay-webdriver</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-ensure</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- Cucumber JUnit 5 runner -->
        <dependency>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-junit-platform-engine</artifactId>
            <version>${cucumber.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-suite</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-failsafe-plugin</artifactId>
                <version>3.5.2</version>
                <configuration>
                    <includes>
                        <include>**/CucumberTestSuite.java</include>
                    </includes>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>integration-test</goal>
                            <goal>verify</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>net.serenity-bdd.maven.plugins</groupId>
                <artifactId>serenity-maven-plugin</artifactId>
                <version>${serenity.version}</version>
                <executions>
                    <execution>
                        <id>serenity-reports</id>
                        <phase>post-integration-test</phase>
                        <goals>
                            <goal>aggregate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>
```

## Available BOM Modules

The `serenity-bom` includes version-managed entries for all published Serenity BDD modules:

| Category | Modules |
| -------- | ------- |
| **Core** | `serenity-core`, `serenity-model`, `serenity-report-resources` |
| **Test Runners** | `serenity-junit5`, `serenity-junit` (deprecated), `serenity-cucumber` |
| **Screenplay** | `serenity-screenplay`, `serenity-screenplay-webdriver`, `serenity-screenplay-rest`, `serenity-screenplay-playwright` |
| **Assertions** | `serenity-ensure`, `serenity-assertions` |
| **REST** | `serenity-rest-assured` |
| **Reporting** | `serenity-reports`, `serenity-single-page-report`, `serenity-json-summary-report`, `serenity-navigator-report` |
| **Integrations** | `serenity-spring`, `serenity-playwright` |
| **Cloud Providers** | `serenity-browserstack`, `serenity-saucelabs`, `serenity-lambdatest`, `serenity-selenoid`, `serenity-bitbar`, `serenity-zalenium`, `serenity-crossbrowsertesting` |
| **Tools** | `serenity-browsermob-plugin`, `serenity-shutterbug`, `serenity-cli`, `serenity-ant-task` |
| **JIRA** | `serenity-jira-plugin`, `serenity-jira-requirements-provider` |


---

<!-- https://serenity-bdd.github.io/docs/guide/step_libraries -->

# Serenity Step Libraries
In Serenity, tests are broken down into reusable steps. An important principle behind Serenity is the idea that it is easier to maintain a test that uses several layers of abstraction to hide the complexity behind different parts of a test.

In an automated acceptance test, test steps represent the level of abstraction between the code that interacts with your application (for example, Page Component Objects in an automated web test, which model parts of the user interface, or API endpoints for web services you need to interact with) and higher-level stories (sequences of more business-focused actions that illustrate how a given user story has been implemented). If your automated test is not UI-oriented (for example, if it calls a web service), steps orchestrate other more technical components such as REST clients. Steps can contain other steps, and are included in the Serenity reports. Whenever a UI step is executed, a screenshot is stored and displayed in the report.

## Breaking down tests into steps
Suppose we are testing a Frequent Flyer programme, and need to illustrate the following business rules:

- Members should start with Bronze status
- Members should earn Silver status after flying 10,000 km.

Each of these can be broken down further into business tasks and verifications. For example, the first rule could be broken into two steps:
- Create a new Frequent Flyer member
- Check that the member has a status of Bronze

And the second can be broken into three steps:
- Create a new Frequent Flyer member
- Make the member fly 10000 km
- Check that the member has a status of Silver

We could express these tests using Serenity in JUnit 5 as follows:

```java
package flyer;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.annotations.Steps;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import flyer.steps.TravellerEarningStatusPoints;

import static flyer.Status.Bronze;
import static flyer.Status.Silver;

@ExtendWith(SerenityJUnit5Extension.class)
class WhenEarningFrequentFlyerPoints {

    @Steps
    TravellerEarningStatusPoints tracy;

    @Test
    void members_should_start_with_Bronze_status() {
        // GIVEN
        tracy.joins_the_frequent_flyer_program();

        // THEN
        tracy.should_have_a_status_of(Bronze);
    }

    @Test
    void earn_silver_after_10000_kilometers() {
        // GIVEN
        tracy.joins_the_frequent_flyer_program();

        // WHEN
        tracy.flies(10000);

        // THEN
        tracy.should_have_a_status_of(Silver);
    }
}
```

:::note JUnit 4 Deprecated
If you're still using JUnit 4 with `@RunWith(SerenityRunner.class)`, note that JUnit 4 support is deprecated as of Serenity 5.0.0 and will be removed in Serenity 6.0.0. Please migrate to JUnit 5 using `@ExtendWith(SerenityJUnit5Extension.class)` as shown above.
:::

Notice how the second test reuses step methods used in the first to perform a slightly different test. This is a typical example of the way we reuse steps in similar tests, in order to avoid duplicated code and make the code easier to maintain.

## Implementing Simple Step Libraries
The `TravellerEarningStatusPoints` class is what we call a step library. We use the `@Steps` class as shown above to indicate a step library in our test code: this annotation tells Serenity to instantiate and instrument this field, so that methods you call in this library also appear in the test reports.

Step libraries contain the business tasks or actions that a user performs during a test. There are many ways to organise your step libraries, but a convenient way is to group methods in slices of business behaviour for a given type of user. In this case a traveller who is earning status points.

Notice that it was not necessary to explicitly instantiate the Steps class `TravellerEarningStatusPoints`. When you annotated a member variable of this class with the `@Steps` annotation, Serenity BDD will automatically instantiate it for you.

You should never create instances of step libraries using the `new` keyword, as Serenity will not be able to instrument the step library correctly, and the methods called will not appear in the reports.

For example, suppose we want to test a simple calculator UI. In this class, we use the `CalculatorSteps` step library, which we annotate with the `@Steps` annotation:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class WhenDoingSums {

    @Steps
    CalculatorSteps calulate;

    @Nested
    class ABasicCalculator {

        @BeforeEach
        void openTheCalculator() {
            calulate.openTheCalculatorApp();
        }

        @Test
        void shouldCalculateAdditions() {
            int result = calulate.theAnswerTo("1","+","2");
            assertThat(result).isEqualTo(3);
        }

        @Test
        void shouldCalculateSubtractions() {
            int result = calulate.theAnswerTo("7","-","3");
            assertThat(result).isEqualTo(4);
        }

        @Test
        void shouldCalculateMultiplications() {
            int result = calulate.theAnswerTo("3","*","2");
            assertThat(result).isEqualTo(6);
        }

        @Test
        void shouldCalculateDivisions() {
            int result = calulate.theAnswerTo("10","/","2");
            assertThat(result).isEqualTo(5);
        }
    }
}
```

The `CalculatorSteps` class defines the steps a user needs to perform - in this case, perform a calculation on the calculator app:

```java
public class CalculatorSteps {

    @Step("Calculate the answer to {0} {1} {2}")
    public int theAnswerTo(String a, String operator, String b) {
        // Interact with the the calculator to perform the calculation
    }
}
```

Step methods are annotated with the `@Step` annotation, which tells Serenity to include this method in the Serenity test reports. The value we include in the `@Step` annotation is the text that will appear in the Serenity reports when this step is executed. The numbers in curly brackets (`{0}`,`{1}` and `{2}`) represent placeholders the method parameters, if we want them to appear in the reports.

When we run this test case, Serenity will document the steps that get executed during each test, producing a living documentation of the test execution:

![](img/calculator-steps.png)

### UI Interaction Classes

Suppose our calculator test needs to interact with a web UI, such as the one on https://juliemr.github.io/protractor-demo/ shown here:

![](img/calculator-app.png)

We can access the powerful Serenity BDD Selenium integration in our step libraries by extending the `net.serenitybdd.core.steps.UIInteractions` class. A very simple implementation might look like this:

```java
public class CalculatorSteps extends UIInteractions {

     @Step
    public void openTheCalculatorApp() {
        openUrl("https://juliemr.github.io/protractor-demo/");
    }

   @Step("Calculate the answer to {0} {1} {2}")
    public int theAnswerTo(String firstValue, String operator, String secondValue) {

        $("[ng-model=first]").sendKeys(firstValue);
        $("[ng-model=operator]").selectByVisibleText(operator);
        $("[ng-model=second]").sendKeys(secondValue);
        $("#gobutton").click();
        waitForAngularRequestsToFinish();

        return Integer.parseInt($("css:h2").getText());
    }
}
```

:::caution Do not declare `@Managed WebDriver` in a step library
`@Managed` is only filled in on the test class. In a step library the field stays `null`, and the first use fails with a `NullPointerException: Cannot invoke "org.openqa.selenium.WebDriver.get(String)" because "this.driver" is null`, which does not mention `@Managed`. Extend `UIInteractions` and use `getDriver()`, or use a page object, which gets the driver by itself. In releases after 5.4.1, Serenity also logs a warning when it finds a `@Managed` field in a step library.
:::

A more readable, refactored implementation might look like this:

```java
public class CalculatorSteps extends UIInteractions {

    private static final By FIRST_VALUE_FIELD = By.cssSelector("[ng-model=first]");
    private static final By SECOND_VALUE_FIELD = By.cssSelector("[ng-model=second]");
    private static final By OPERATOR_DROPDOWN = By.cssSelector("[ng-model=operator]");
    private static final By GO_BUTTON = By.id("gobutton");
    private static final By RESULT_FIELD = By.tagName("h2");
    private static final Pattern A_VALID_NUMBER = Pattern.compile("-?\\d\\.?d*");

    @Step
    public void openTheCalculatorApp() {
        openUrl("https://juliemr.github.io/protractor-demo/");
    }

    @Step("Calculate the answer to {0} {1} {2}")
    public int theAnswerTo(String firstValue, String operator, String secondValue) {

        $(FIRST_VALUE_FIELD).sendKeys(firstValue);
        $(OPERATOR_DROPDOWN).selectByVisibleText(operator);
        $(SECOND_VALUE_FIELD).sendKeys(secondValue);
        $(GO_BUTTON).click();
        waitFor(ExpectedConditions.textMatches(RESULT_FIELD,A_VALID_NUMBER));

        return Integer.parseInt($(RESULT_FIELD).getText());
    }
}
```

The tests will now interact with the user interface, report on both the steps executed, and (if configured to do so) record screenshots for each step:

![](img/calculator-step-screenshots.png)


### Persona Step Libraries

Another approach to modeling step libraries revolves around actors and roles. Let's return to our original example: Tracy, the traveller, who earns points when she travels.

```java
public class TravellerEarningStatusPoints {

    private String actor;

    private FrequentFlyer frequentFlyer;

    @Step("#actor joins the frequent flyer program")   
    public void joins_the_frequent_flyer_program() {
        frequentFlyer = FrequentFlyer.withInitialBalanceOf(0);
    }

    @Step("#actor flies {0} km")
    public void flies(int distance) {
        frequentFlyer.recordFlightDistanceInKilometers(distance);
    }

    @Step("#actor should have a status of {0}")
    public void should_have_a_status_of(Status expectedStatus) {
        assertThat(frequentFlyer.getStatus()).isEqualTo(expectedStatus);
    }

    @Step("#actor transfers {0} points to {1}")
    public void transfers_points(int points, TravellerEarningStatusPoints otherFrequentFlier) {
        // Left as an exercise
    }

    @Override
    public String toString() {
        return actor;
    }

    @Step("#actor should have {0} points")
    public void should_have_points(int expectedPoints) {
        // Left as an exercise
    }
}
```

This approach uses the concept of _persona_ step libraries, where a step library represents the actions of a specific user performing a specific task (Tracy the traveller who is earning points.) In this case, Serenity will automatically instantiate the _actor_ field with the name of the step library variable (`tracy`), allowing it to appear in the test reports to make them more readable:

![](img/persona-steps.png)


## Shared Instances of Step Libraries
There are some cases where we want to reuse the same step library instance in different places across a test. For example, suppose we have a step library that interacts with a backend API, and that maintains some internal state and caching to improve performance. We might want to reuse a single instance of this step library, rather than having a separate instance for each variable.

We can do this by declaring the step library to be shared, like this:

```java
@Steps(shared = true)
CustomerAPIStepLibrary customerAPI;
```

Now, any other step libraries of type `CustomerAPIStepLibrary`, that have the shared attribute set to true will refer to the same instance.

In older versions of Serenity, sharing instances was the default behaviour, and you used the uniqueInstance attribute to indicate that a step library should not be shared. If you need to force this behaviour for legacy test suites, set the step.creation.strategy property to legacy in your serenity.properties file:

```javascript
step.creation.strategy = legacy
```


---

<!-- https://serenity-bdd.github.io/docs/guide/page_objects -->

# Interacting with Web Pages

Serenity integrates smoothly with Selenium WebDriver and manages details such as setting up the driver and maintaining the driver instance. It also provides a number of enhancements to standard Selenium.

## Page Objects

If you are working with WebDriver web tests, you will be familiar with the concept of Page Objects. Page Objects are a way of isolating the implementation details of a web page inside a class, exposing only business-focused methods related to that page. They are an excellent way of making your web tests more maintainable.

In Serenity, page objects are just ordinary classes that extend the `PageObject` class. Serenity automatically injects a WebDriver instance into the page object that you can access via the `getDriver()` method, although you rarely need to use the WebDriver directly. The Serenity `PageObject` class provides a number of convenient methods that make accessing and manipulating web elements much easier than with conventional WebDriver test scripts.

Here is a simple example:

```java
...
import net.serenitybdd.core.pages.WebElementFacade;
import net.thucydides.core.pages.PageObject;
...

@DefaultUrl("http://localhost:9000/somepage")
public class FindAJobPage extends PageObject {

    WebElementFacade keywords;
    WebElementFacade searchButton;

    public void look_for_jobs_with_keywords(String values) {
        typeInto(keywords, values);
        searchButton.click();
    }

    public List<String> getJobTabs() {
        return findAll("//div[@id='tabs']//a").stream()
            .map(WebElementFacade::getText)
            .collect(Collectors.toList());
    }
}
```

The `typeInto` method is a shorthand that simply clears a field and enters the specified text.
If you prefer a more fluent-API style, you can also do something like this:

```java
@DefaultUrl("http://localhost:9000/somepage")
public class FindAJobPage extends PageObject {
	WebElementFacade keywordsField;
	WebElementFacade searchButton;

	public FindAJobPage(WebDriver driver) {
	    super(driver);
	}

	public void look_for_jobs_with_keywords(String values) {
	    enter(values).into(keywordsField);
	    searchButton.click();
	}

	public List<String> getJobTabs() {
	     return findAll("//div[@id='tabs']//a").stream()
            .map(WebElementFacade::getText)
            .collect(Collectors.toList());
	}
}
```

You can use an even more fluent style of expressing the implementation steps by using methods like `find`, `findBy` and `then`.

For example, you can use webdriver `By` finders with element name, id, css selector or xpath selector as follows:

```java
find(By.name("demo")).then(By.name("specialField")).getValue();

find(By.cssSelector(".foo")).getValue();

find(By.xpath("//th")).getValue();
```

The `findBy` method lets you pass the css or xpath selector directly to WebDriver. For example,

```java
findBy("#demo").then("#specialField").getValue(); //css selectors

findBy("//div[@id='dataTable']").getValue(); //xpath selector
```

## Using pages in a step library

When you need to use a page object in one of your steps, you just need to declare a variable of type PageObject in your step library, e.g.

```java
FindAJobPage page;
```

If you want to make sure you are on the right page, you can use the `currentPageAt()` method. This will check the page class for any `@At` annotations present in the PageObject class and, if present, check that the current URL corresponds to the URL pattern specified in the annotation. For example, when you invoke it using `currentPageAt()+, the following Page Object will check that the current URL is precisely `http://www.apache.org`.

```java
@At("http://www.apache.org")
public class ApacheHomePage extends PageObject {
    ...
}
```

The `@At` annotation also supports wildcards and regular expressions. The following page object will match any Apache sub-domain:

```java
@At("http://.*.apache.org")
public class AnyApachePage extends PageObject {
    ...
}
```

More generally, however, you are more interested in what comes after the host name. You can use the special `#HOST` token to match any server name. So the following Page Object will match both `http://localhost:8080/app/action/login.form` and `http://staging.acme.com/app/action/login.form`. It will also ignore parameters, so `http://staging.acme.com/app/action/login.form?username=toto&password=oz` will work fine too.

```java
@At(urls={"#HOST/app/action/login.form"})
public class LoginPage extends PageObject {
   ...
}
```

## Opening the page

A page object is usually designed to work with a particular web page. When the `open()` method is invoked, the browser will be opened to the default URL for the page.

The `@DefaultUrl` annotation indicates the URL that this test should use when run in isolation (e.g. from within your IDE).
Generally, however, the host part of the default URL will be overridden by the `webdriver.base.url` property, as this allows you to set the base URL across the board for all of your tests,
and so makes it easier to run your tests on different environments by simply changing this property value.
For example, in the test class above, setting the `webdriver.base.url` to 'https://staging.mycompany.com' would result in the page being opened at the URL of 'https://staging.mycompany.com/somepage'.

You can also define named URLs that can be used to open the web page, optionally with parameters. For example, in the following code, we define a URL called 'open.issue', that accepts a single parameter:

```java
@DefaultUrl("http://jira.mycompany.org")
@NamedUrls(
  {
    @NamedUrl(name = "open.issue", url = "http://jira.mycompany.org/issues/{1}")
  }
)
public class JiraIssuePage extends PageObject {
    ...
}
```

You could then open this page to the http://jira.mycompany.org/issues/ISSUE-1 URL as shown here:

```java
page.open("open.issue", withParameters("ISSUE-1"));
```

You could also dispense entirely with the base URL in the named URL definition, and rely on the default values:

```java
@DefaultUrl("http://jira.mycompany.org")
@NamedUrls(
  {
    @NamedUrl(name = "open.issue", url = "/issues/{1}")
  }
)
public class JiraIssuePage extends PageObject {
    ...
}
```

And naturally you can define more than one definition:

```java
@NamedUrls(
  {
          @NamedUrl(name = "open.issue", url = "/issues/{1}"),
          @NamedUrl(name = "close.issue", url = "/issues/close/{1}")
  }
)
```

You should never try to implement the `open()` method yourself. In fact, it is final. If you need your page to do something upon loading, such as waiting for a dynamic element to appear, you can use the @WhenPageOpens annotation.
Methods in the PageObject with this annotation will be invoked (in an unspecified order) after the URL has been opened. In this example, the `open()` method will not return until
the `dataSection` web element is visible:

```java
@DefaultUrl("http://localhost:8080/client/list")
    public class ClientList extends PageObject {

     @FindBy(id="data-section");
     WebElementFacade dataSection;
     ...

     @WhenPageOpens
     public void waitUntilTitleAppears() {
         element(dataSection).waitUntilVisible();
     }
}
```

## Working with web elements

### Checking whether elements are visible

The `WebElementFacade` class contains convenient fluent API for dealing with web elements, providing some commonly-used extra features that are not provided out-of-the-box by the WebDriver API.
`WebElementFacades` are largely interchangeable with WebElements: you just declare a variable of type `WebElementFacade` instead of type `WebElement`. For example, you can check that an element is visible as shown here:

```java
public class FindAJobPage extends PageObject {

    WebElementFacade searchButton;

    public boolean searchButtonIsVisible() {
        return searchButton.isVisible();
    }
    ...
}
```

If the button is not present on the screen, the test will wait for a short period in case it appears due to some Ajax magic. If you don't want the test to do this, you can use the faster version:

```java
public boolean searchButtonIsVisibleNow() {
    return searchButton.isCurrentlyVisible();
}
```

You can turn this into an assert by using the `shouldBeVisible()` method instead:

```java
public void checkThatSearchButtonIsVisible() {
    searchButton.shouldBeVisible();
}
```

This method will throw an assertion error if the search button is not visible to the end user.

### Checking whether elements are enabled

You can also check whether an element is enabled or not:

```java
searchButton.isEnabled()
searchButton.shouldBeEnabled()
```

There are also equivalent negative methods:

```java
searchButton.shouldNotBeVisible();
searchButton.shouldNotBeCurrentlyVisible();
searchButton.shouldNotBeEnabled()
```

You can also check for elements that are present on the page but not visible, e.g:

```java
searchButton.isPresent();
searchButton.isNotPresent();
searchButton.shouldBePresent();
searchButton.shouldNotBePresent();
```

### Manipulating select lists

There are also helper methods available for drop-down lists. Suppose you have the following dropdown on your page:

```xml
<select id="color">
    <option value="red">Red</option>
    <option value="blue">Blue</option>
    <option value="green">Green</option>
</select>
```

You could write a page object to manipulate this dropdown as shown here:

```java
public class FindAJobPage extends PageObject {

	@FindBy(id="color")
	WebElementFacade colorDropdown;

	public selectDropdownValues() {
	    colorDropdown.selectByVisibleText("Blue");
	    assertThat(colorDropdown.getSelectedVisibleTextValue(), is("Blue"));

	    colorDropdown.selectByValue("blue");
	    assertThat(colorDropdown.getSelectedValue(), is("blue"));

	    colorDropdown.selectByIndex(2);
	    assertThat(colorDropdown.getSelectedValue(), is("green"));

	}
	...
}
```

### Determining focus

You can determine whether a given field has the focus as follows:

```java
firstName.hasFocus()
```

You can also wait for elements to appear, disappear, or become enabled or disabled:

```java
button.waitUntilEnabled()
button.waitUntilDisabled()
```

or

```java
field.waitUntilVisible()
button.waitUntilNotVisible()
```

### Using direct XPath and CSS selectors

Another way to access a web element is to use an XPath or CSS expression. You can use the `$()` method with an XPath expression to do this more simply. For example, imagine your web application needs to click on a list item containing a given post code. One way would be as shown here:

```java
WebElement selectedSuburb = getDriver().findElement(By.xpath("//li/a[contains(.,'" ` postcode ` "')]"));
selectedSuburb.click();
```

However, a simpler option would be to do this:

```java
$("//li/a[contains(.,'" ` postcode ` "')]").click();
```

## Working with Asynchronous Pages

Asynchronous pages are those whose fields or data is not all displayed when the page is loaded. Sometimes, you need to wait for certain elements to appear, or to disappear, before being able to proceed with your tests. Serenity provides some handy methods in the PageObject base class to help with these scenarios. They are primarily designed to be used as part of your business methods in your page objects, though in the examples we will show them used as external calls on a PageObject instance for clarity.

### Checking whether an element is visible

In WebDriver terms, there is a distinction between when an element is present on the screen (i.e. in the HTML source code), and when it is rendered (i.e. visible to the user). You may also need to check whether an element is visible on the screen. You can do this in two ways. Your first option is to use the isElementVisible method, which returns a boolean value based on whether the element is rendered (visible to the user) or not:

```java
isElementVisible(By.xpath("//h2[.='A visible title']"))
```

Your second option is to actively assert that the element should be visible:

```java
shouldBeVisible(By.xpath("//h2[.='An invisible title']"));
```

If the element does not appear immediately, you can wait for it to appear:

```java
waitForRenderedElements(By.xpath("//h2[.='A title that is not immediately visible']"));
```

An alternative to the above syntax is to use the more fluid `waitFor` method which takes a css or xpath selector as argument:

```java
waitFor("#popup"); //css selector

waitFor("//h2[.='A title that is not immediately visible']"); //xpath selector
```

If you just want to check if the element is present though not necessarily visible, you can use `waitForRenderedElementsToBePresent` :

```java
waitForRenderedElementsToBePresent(By.xpath("//h2[.='A title that is not immediately visible']"));
```

or its more expressive flavour, `waitForPresenceOf` which takes a css or xpath selector as argument.

```java
waitForPresenceOf("#popup"); //css

waitForPresenceOf("//h2[.='A title that is not immediately visible']"); //xpath
```

You can also wait for an element to disappear by using `waitForRenderedElementsToDisappear` or `waitForAbsenceOf` :

```java
waitForRenderedElementsToDisappear(By.xpath("//h2[.='A title that will soon disappear']"));

waitForAbsenceOf("#popup");

waitForAbsenceOf("//h2[.='A title that will soon disappear']");
```

For simplicity, you can also use the `waitForTextToAppear` and `waitForTextToDisappear` methods:

```java
waitForTextToDisappear("A visible bit of text");
```

If several possible texts may appear, you can use `waitForAnyTextToAppear` or `waitForAllTextToAppear+:

```java
waitForAnyTextToAppear("this might appear","or this", "or even this");
```

If you need to wait for one of several possible elements to appear, you can also use the `waitForAnyRenderedElementOf` method:

```java
waitForAnyRenderedElementOf(By.id("color"), By.id("taste"), By.id("sound"));
```

### Working with Shadow DOM elements

Selenium 4 introduced support for Shadow DOM elements, and Serenity BDD adds enhanced support for these elements. Suppose we have the following HTML structure containing shadow DOM elements.

```html
<pre>
    <div id="shadow-host">
      #shadow-root
      <input id="shadowedInput"/>

      <div id="nested-shadow-host">
          #shadow-root
          <input id="nestedShadowedInput"/>
      </div>
    </div>
```

To find the first input element inside a single-level shadow DOM, you need to provide the locator for the nested element and the locator for the shadow host element:

```java
 ByShadow.cssSelector("#shadowedInput","#shadow-host")
```

To find the input element inside the nested shadow DOM, you need to provide the locator for the shadowed element, as well as the list of parent shadow dom locators, from top to bottom:

```java
ByShadow.cssSelector("#nestedShadowedInput","#shadow-host", "#nested-shadow-host")
```

## Working with timeouts

Modern AJAX-based web applications add a great deal of complexity to web testing. The basic problem is, when you access a web element on a page, it may not be available yet. So you need to wait a bit. Indeed, many tests contain hard-coded pauses scattered through the code to cater for this sort of thing.

But hard-coded waits are evil. They slow down your test suite, and cause them to fail randomly if they are not long enough. Rather, you need to wait for a particular state or event. Selenium provides great support for this, and Serenity builds on this support to make it easier to use.

### Implicit Waits

The first way you can manage how WebDriver handles tardy fields is to use the `webdriver.timeouts.implicitlywait` property. This determines how long, in milliseconds, WebDriver will wait if an element it tries to access is not present on the page. To quote the WebDriver documentation:

“An implicit wait is to tell WebDriver to poll the DOM for a certain amount of time when trying to find an element or elements if they are not immediately available.”

The default value in Serenity for this property is currently 2 seconds. This is different from standard WebDriver, where the default is zero.

Let’s look at an example. Suppose we have a PageObject with a field defined like this:

```java
@FindBy(id="slow-loader")
public WebElementFacade slowLoadingField;
```

This field takes a little while to load, so won’t be ready immediately on the page.

Now suppose we set the `webdriver.timeouts.implicitlywait` value to 5000, and that our test uses the slowLoadingField:

```java
boolean loadingFinished = slowLoadingField.isDisplayed()
```

When we access this field, two things can happen. If the field takes less than 5 seconds to load, all will be good. But if it takes more than 5 seconds, a NoSuchElementException (or something similar) will be thrown.

That this timeout also applies for lists. Suppose we have defined a field like this, which takes some time to dynamically load:

```java
@FindBy(css="#elements option")
public List<WebElementFacade> elementItems;
```

Now suppose we count the values of the element like this:

```java
int itemCount = elementItems.size()
```

The number of items returned will depend on the implicit wait value. If we set the `webdriver.timeouts.implicitlywait` value to a very small value, WebDriver may only load some of the values. But if we give the list enough time to load completely, we will get the full list.

The implicit wait value is set globally for each WebDriver instance, but you can override the value yourself. The simplest way to do this from within a Serenity PageObject is to use the setImplicitTimeout() method:

```java
setImplicitTimeout(5, SECONDS)
```

But remember this is a global configuration, so will also affect other page objects. So once you are done, you should always reset the implicit timeout to its previous value. Serenity gives you a handy method to do this:

```java
resetImplicitTimeout()
```

See http://docs.seleniumhq.org/docs/04_webdriver_advanced.jsp#implicit-waits[Selenium Documentation] for more details on how the WebDriver implicit waits work.

### Using custom locator factories

Internally, Selenium uses the concept of Locator Factories
Normally, Serenity uses `SmartElementLocatorFactory`, an extension of the WebDriver `AjaxElementLocatorFactory`, when instantiating page objects. Among other things, this helps ensure that web elements are available and usable before they are used, allows field-by-field timeouts, and avoids long unnecessary waits on web elements after a step has failed.

The `SmartElementLocatorFactory` uses the default implicit wait, or the `timeoutInSeconds` attribute of the `@FindBy` annotation if this value has been specified (see below), or the default implicit wait value specified by the `webdriver.timeouts.implicitlywait` property.

In rare cases, you may need to customise this behaviour. To do this, you can use the `serenity.locator.factory` property to use one of the following alternative locator factories:

- `AjaxElementLocatorFactory`: A WebDriver locator factory more suitable for Ajax applications. According to the WebDriver docs, this locator factory will return _an element locator that will wait for the specified number of seconds for an element to appear, rather than failing instantly if it's not present. This works by polling the UI on a regular basis. The element returned will be present on the DOM, but may not actually be visible._

- `DefaultElementLocatorFactory`: the default WebDriver locator factory

If you use the `AjaxElementLocatorFactory`, you can use the `webdriver.timeouts.implicitlywait` parameter is to specify the number of seconds to wait. If no value is specified, the default wait will be 5 seconds.

### Explicit Timeouts

You can also programatically wait until an element is in a particular state. This is more flexible and useful when you need to wait for extra time in a specific situation. For example, we could wait until a field becomes visible:

```java
slowLoadingField.waitUntilVisible()
```

You can also wait for more arbitrary conditions, e.g.

```java
waitFor(ExpectedConditions.alertIsPresent())
```

The default time that Serenity will wait is determined by the `webdriver.wait.for.timeout` property. The default value for this property is 5 seconds.

Sometimes you want to give WebDriver some more time for a specific operation. From within a PageObject, you can override or extend the explicit timeout by using the withTimeoutOf() method. For example, you could wait for the #elements list to load for up to 5 seconds like this:

```java
withTimeoutOf(5, SECONDS).waitForPresenceOf(By.cssSelector("#elements option"))
```

You can also specify the timeout for a field. For example, if you wanted to wait for up to 5 seconds for a button to become clickable before clicking on it, you could do the following:

```java
someButton.withTimeoutOf(5, SECONDS).waitUntilClickable().click()
```

You can also use this approach to retrieve elements:

```java
elements = withTimeoutOf(5, SECONDS).findAll("#elements option")
```

Finally, if a specific element a PageObject needs to have a bit more time to load, you can use the timeoutInSeconds attribute in the Serenity @FindBy annotation, e.g.

```java
import net.serenitybdd.core.annotations.findby.FindBy;
...
@FindBy(name = "country", timeoutInSeconds="10")
public WebElementFacade country;
```

You can also wait for an element to be in a particular state, and then perform an action on the element. Here we wait for an element to be clickable before clicking on the element:

```java
addToCartButton.withTimeoutOf(5, SECONDS).waitUntilClickable().click()
```

Or, you can wait directly on a web element:

```java
@FindBy(id="share1-fb-like")
WebElementFacade facebookIcon;
  ...
public WebElementState facebookIcon() {
    return withTimeoutOf(5, TimeUnit.SECONDS).waitFor(facebookIcon);
}
```

Or even:

```java
List<WebElementFacade> currencies = withTimeoutOf(5, TimeUnit.SECONDS)
                              .waitFor(currencyTab)
                              .thenFindAll(".currency-code");
```

## Executing Javascript

There are times when you may find it useful to execute a little Javascript directly within the browser to get the job done. You can use the `evaluateJavascript()` method of the `PageObject` class to do this. For example, you might need to evaluate an expression and use the result in your tests. The following command will evaluate the document title and return it to the calling Java code:

```java
String result = (String) evaluateJavascript("return document.title");
```

Alternatively, you may just want to execute a Javascript command locally in the browser. In the following code, for example, we set the focus to the 'firstname' input field:

```java
	evaluateJavascript("document.getElementById('firstname').focus()");
```

And, if you are familiar with JQuery, you can also invoke JQuery expressions:

```java
	evaluateJavascript("$('#firstname').focus()");
```

This is often a useful strategy if you need to trigger events such as mouse-overs that are not currently supported by the WebDriver API.

## Uploading files

Uploading files is easy. Files to be uploaded can be either placed in a hard-coded location (bad) or stored on the classpath (better). Here is a simple example:

```java
public class NewCompanyPage extends PageObject {
    ...
    @FindBy(id="object_logo")
    WebElementFacade logoField;

    public NewCompanyPage(WebDriver driver) {
        super(driver);
    }

    public void loadLogoFrom(String filename) {
        upload(filename).to(logoField);
    }
}
```

## Using Fluent Matcher expressions

When writing acceptance tests, you often find yourself expressing expectations about individual domain objects or collections of domain objects. For example, if you are testing a multi-criteria search feature, you will want to know that the application finds the records you expected. You might be able to do this in a very precise manner (for example, knowing exactly what field values you expect), or you might want to make your tests more flexible by expressing the ranges of values that would be acceptable. Serenity provides a few features that make it easier to write acceptance tests for this sort of case.

In the rest of this section, we will study some examples based on tests for the Maven Central search site. This site lets you search the Maven repository for Maven artifacts, and view the details of a particular artifact.

We will use some imaginary regression tests for this site to illustrate how the Serenity matchers can be used to write more expressive tests. The first scenario we will consider is simply searching for an artifact by name, and making sure that only artifacts matching this name appear in the results list. We might express this acceptance criteria informally in the following way:

- Give that the developer is on the search page,
- And the developer searches for artifacts called 'Serenity'
- Then the developer should see at least 16 Serenity artifacts, each with a unique artifact Id

In JUnit 5, a Serenity test for this scenario might look like the one:

```java
...
import static net.thucydides.core.matchers.BeanMatchers.the_count;
import static net.thucydides.core.matchers.BeanMatchers.each;
import static net.thucydides.core.matchers.BeanMatchers.the;
import static org.hamcrest.Matchers.greaterThanOrEqualTo;
import static org.hamcrest.Matchers.is;
import static org.hamcrest.Matchers.startsWith;

@ExtendWith(SerenityJUnit5Extension.class)
class WhenSearchingForArtifacts {

    @Managed
    WebDriver driver;

    @Steps
    DeveloperSteps developer;

    @Test
    void should_find_the_right_number_of_artifacts() {
        developer.opens_the_search_page();
        developer.searches_for("Serenity");
        developer.should_see_artifacts_where(the("GroupId", startsWith("net.thucydides")),
                                             each("ArtifactId").isDifferent(),
                                             the_count(is(greaterThanOrEqualTo(16))));

    }
}
```

:::note JUnit 4 Deprecated
If you're still using JUnit 4 with `@RunWith(SerenityRunner.class)`, note that JUnit 4 support is deprecated as of Serenity 5.0.0 and will be removed in Serenity 6.0.0. Please migrate to JUnit 5 using `@ExtendWith(SerenityJUnit5Extension.class)`.
:::

Let's see how the test in this class is implemented. The `should_find_the_right_number_of_artifacts()` test could be expressed as follows:

. When we open the search page

. And we search for artifacts containing the word 'Serenity'

. Then we should see a list of artifacts where each Group ID starts with "net.Serenity", each Artifact ID is unique, and that there are at least 16 such entries displayed.

The implementation of these steps is illustrated here:

```java
...
import static net.thucydides.core.matchers.BeanMatcherAsserts.shouldMatch;

public class DeveloperSteps {

    @Step
    public void opens_the_search_page() {
        onSearchPage().open();
    }

    @Step
    public void searches_for(String search_terms) {
        onSearchPage().enter_search_terms(search_terms);
        onSearchPage().starts_search();
    }

    @Step
    public void should_see_artifacts_where(BeanMatcher... matchers) {
        shouldMatch(onSearchResultsPage().getSearchResults(), matchers);
    }

    private SearchPage onSearchPage() {
        return getPages().get(SearchPage.class);
    }

    private SearchResultsPage onSearchResultsPage() {
        return getPages().get(SearchResultsPage.class);
    }
}
```

The first two steps are implemented by relatively simple methods. However the third step is more interesting. Let's look at it more closely:

```java
    @Step
    public void should_see_artifacts_where(BeanMatcher... matchers) {
        shouldMatch(onSearchResultsPage().getSearchResults(), matchers);
    }
```

Here, we are passing an arbitrary number of expressions into the method. These expressions actually 'matchers', instances of the BeanMatcher class. Not that you usually have to worry about that level of detail - you create these matcher expressions using a set of static methods provided in the BeanMatchers class. So you typically would pass fairly readable expressions like `the("GroupId", startsWith("net.Serenity"))` or `each("ArtifactId").isDifferent()+.

The `shouldMatch()` method from the BeanMatcherAsserts class takes either a single Java object, or a collection of Java objects, and checks that at least some of the objects match the constraints specified by the matchers. In the context of web testing, these objects are typically POJOs provided by the Page Object to represent the domain object or objects displayed on a screen.

There are a number of different matcher expressions to choose from. The most commonly used matcher just checks the value of a field in an object. For example, suppose you are using the domain object shown here:

```java
     public class Person {
        private final String firstName;
        private final String lastName;

        Person(String firstName, String lastName) {
            this.firstName = firstName;
            this.lastName = lastName;
        }

        public String getFirstName() {...}

        public String getLastName() {...}
    }
```

You could write a test to ensure that a list of Persons contained at least one person named "Bill" by using the "the" static method, as shown here:

```java
    List<Person> persons = Arrays.asList(new Person("Bill", "Oddie"), new Person("Tim", "Brooke-Taylor"));

    shouldMatch(persons, the("firstName", is("Bill"))
```

The second parameter in the the() method is a Hamcrest matcher, which gives you a great deal of flexibility with your expressions. For example, you could also write the following:

```java
    List<Person> persons = Arrays.asList(new Person("Bill", "Oddie"), new Person("Tim", "Brooke-Taylor"));

    shouldMatch(persons, the("firstName", is(not("Tim"))));
    shouldMatch(persons, the("firstName", startsWith("B")));
```

You can also pass in multiple conditions:

```java
    List<Person> persons = Arrays.asList(new Person("Bill", "Oddie"), new Person("Tim", "Brooke-Taylor"));

    shouldMatch(persons, the("firstName", is("Bill"), the("lastName", is("Oddie"));
```

Serenity also provides the DateMatchers class, which lets you apply Hamcrest matches to standard java Dates and `JodaTime` DateTimes. The following code samples illustrate how these might be used:

```java
    DateTime january1st2010 = new DateTime(2010,01,01,12,0).toDate();
    DateTime may31st2010 = new DateTime(2010,05,31,12,0).toDate();

    the("purchaseDate", isBefore(january1st2010))
    the("purchaseDate", isAfter(january1st2010))
    the("purchaseDate", isSameAs(january1st2010))
    the("purchaseDate", isBetween(january1st2010, may31st2010))
```

You sometimes also need to check constraints that apply to all of the elements under consideration. The simplest of these is to check that all of the field values for a particular field are unique. You can do this using the `each()` method:

```java
    shouldMatch(persons, each("lastName").isDifferent())
```

You can also check that the number of matching elements corresponds to what you are expecting. For example, to check that there is only one person named Bill, you could do this:

```java
     shouldMatch(persons, the("firstName", is("Bill"), the_count(is(1)));
```

You can also check the minimum and maximum values using the max() and min() methods. For example, if the Person class had a `getAge()` method, we could ensure that every person is over 21 and under 65 by doing the following:

```java
     shouldMatch(persons, min("age", greaterThanOrEqualTo(21)),
                          max("age", lessThanOrEqualTo(65)));
```

These methods work with normal Java objects, but also with Maps. So the following code will also work:

```java
    Map<String, String> person = new HashMap<String, String>();
    person.put("firstName", "Bill");
    person.put("lastName", "Oddie");

    List<Map<String,String>> persons = Arrays.asList(person);
    shouldMatch(persons, the("firstName", is("Bill"))
```

The other nice thing about this approach is that the matchers play nicely with the Serenity reports. So when you use the BeanMatcher class as a parameter in your test steps, the conditions expressed in the step will be displayed in the test report.

There are two common usage patterns when building Page Objects and steps that use this sort of matcher. The first is to write a Page Object method that returns the list of domain objects (for example, Persons) displayed on the table. For example, the getSearchResults() method used in the should_see_artifacts_where() step could be implemented as follows:

```java
    public List<Artifact> getSearchResults() {
        List<WebElement> rows = resultTable.findElements(By.xpath(".//tr[td]"));
        List<Artifact> artifacts = new ArrayList<Artifact>();
        for (WebElement row : rows) {
            List<WebElement> cells = row.findElements(By.tagName("td"));
            artifacts.add(new Artifact(cells.get(0).getText(),
                                       cells.get(1).getText(),
                                       cells.get(2).getText()));

        }
        return artifacts;
    }
```

The second is to access the HTML table contents directly, without explicitly modelling the data contained in the table. This approach is faster and more effective if you don't expect to reuse the domain object in other pages. We will see how to do this next.

### Working with HTML Tables

Since HTML tables are still widely used to represent sets of data on web applications, Serenity comes the HtmlTable class, which provides a number of useful methods that make it easier to write Page Objects that contain tables. For example, the rowsFrom method returns the contents of an HTML table as a list of Maps, where each map contains the cell values for a row indexed by the corresponding heading, as shown here:

```java
...
import static net.thucydides.core.pages.components.HtmlTable.rowsFrom;

public class SearchResultsPage extends PageObject {

    WebElement resultTable;

    public SearchResultsPage(WebDriver driver) {
        super(driver);
    }

    public List<Map<String, String>> getSearchResults() {
        return rowsFrom(resultTable);
    }

}
```

This saves a lot of typing - our `getSearchResults()` method now looks like this:

```java
    public List<Map<String, String>> getSearchResults() {
        return rowsFrom(resultTable);
    }
```

And since the Serenity matchers work with both Java objects and Maps, the matcher expressions will be very similar. The only difference is that the Maps returned are indexed by the text values contained in the table headings, rather than by java-friendly property names.

You can also read tables without headers (i.e., `<th>` elements) by specifying your own headings using the `withColumns` method. For example:

```java
    List<Map<Object, String>> tableRows =
                    HtmlTable.withColumns("First Name","Last Name", "Favorite Colour")
                             .readRowsFrom(page.table_with_no_headings);
```

You can also use the HtmlTable class to select particular rows within a table to work with. For example, another test scenario for the Maven Search page involves clicking on an artifact and displaying the details for that artifact. The test for this might look something like this:

```java
    @Test
    public void clicking_on_artifact_should_display_details_page() {
        developer.opens_the_search_page();
        developer.searches_for("Serenity");
        developer.open_artifact_where(the("ArtifactId", is("Serenity")),
                                      the("GroupId", is("net.Serenity")));

        developer.should_see_artifact_details_where(the("artifactId", is("Serenity")),
                                                    the("groupId", is("net.Serenity")));
    }
```

Now the open_artifact_where() method needs to click on a particular row in the table. This step looks like this:

```java
    @Step
    public void open_artifact_where(BeanMatcher... matchers) {
        onSearchResultsPage().clickOnFirstRowMatching(matchers);
    }
```

So we are effectively delegating to the Page Object, who does the real work. The corresponding Page Object method looks like this:

```java
import static net.thucydides.core.pages.components.HtmlTable.filterRows;
...
    public void clickOnFirstRowMatching(BeanMatcher... matchers) {
        List<WebElement> matchingRows = filterRows(resultTable, matchers);
        WebElement targetRow = matchingRows.get(0);
        WebElement detailsLink = targetRow.findElement(By.xpath(".//a[contains(@href,'artifactdetails')]"));
        detailsLink.click();
    }
```

The interesting part here is the first line of the method, where we use the filterRows() method. This method will return a list of WebElements that match the matchers you have passed in. This method makes it fairly easy to select the rows you are interested in for special treatment.

## Switching to another page

A method, switchToPage() is provided in PageObject class to make it convenient to return a new PageObject after navigation from within a method of a PageObject class. For example,

```java
@DefaultUrl("http://mail.acme.com/login.html")
public class EmailLoginPage extends PageObject {

    ...
    public void forgotPassword() {
        ...
        forgotPassword.click();
        ForgotPasswordPage forgotPasswordPage = this.switchToPage(ForgotPasswordPage.class);
        forgotPasswordPage.open();
        ...
    }
    ...
}
```

## WebElement collection loading strategies

Selenium lets you use the `@FindBy` and `@FindAll` annotations to load collections of web elements, as illustrated here:

```java
@FindBy(css='#colors a')
List<WebElement> options
```

If you are working with an asynchronous application, these lists may take time to load, so Selenium may give you an empty list because the elements have not loaded yet.

Serenity lets you find-tune this behaviour in two ways. The first is to use the wait DSL to load the elements directly, e.g.:

```java
withTimeoutOf(5, SECONDS).waitForPresenceOf(By.cssSelector("#colors a"))
```

Alternatively, you can use the `serenity.webdriver.collection_loading_strategy` property to define how Serenity loads collections of web elements when using the `@FindBy` and `@FindAll` annotations. There are three options:

- Optimistic
- Pessimistic (default)
- Paranoid

Optimistic will only wait until the field is defined. This is the native Selenium behaviour.

Pessimistic will wait until at least the first element is displayed. This is currently the default.

Paranoid will wait until all of the elements are displayed. This can be slow for long lists.

## Working with fixture methods

When a UI step fails in a Serenity test, the WebDriver instance is disabled for the rest of the test. This avoids unnecessary waits as the test steps through the subsequent steps (which it needs to do to document the test steps). The exception to this rule is in the case of fixture methods, such as methods annotated with the `@AfterEach` annotation in JUnit 5 (or `@After` in JUnit 4) or Cucumber.

In these methods, the WebDriver instance can be used normally. In addition to the known JUnit and Cucumber annotations, any annotation starting with the word `After` will be considered a fixture method.

For example, suppose you need to delete the customer accounts via the UI at the end of each test. You already have an `AdminSteps` step library with a `deleteAllCustomerAccounts()` method that performs this task. You could ensure that all of the customer accounts are deleted like this:

```java
@Steps
AdminSteps asAdministrator;

...

@AfterEach
void deleteUserAccounts() {
    asAdministrator.deleteAllCustomerAccounts();
}
```

This makes it easy to perform teardown or cleanup operations that use the user interface, potentially reusing steps or tasks that are used elsewhere in the tests.

You can also override this behaviour at any point by calling the `reenableDrivers()` method, as shown here:

```java
Serenity.webdriver().reenableDrivers();
```

## Extending Serenity WebDriver Integration

Serenity offers a simple way to extend the default WebDriver capabilities and customise the driver creation and teardown activities. Simply implement the `BeforeAWebdriverScenario` and/or the `AfterAWebDriverScenario` interfaces (both are in the `net.serenitybdd.core.webdriver.enhancers` package). Serenity will execute `BeforeAWebdriverScenario` classes just before a driver instance is created, allowing you to add customised options to the driver capabilities. Any `AfterAWebDriverScenario` are executed at the end of a test, just before the driver is closed.

### The BeforeAWebdriverScenario interface

The `BeforeAWebdriverScenario` is used to enhance the `Capabilities` object that will be passed to the WebDriver instance when a new driver is created. The method call passes in the requested driver and the `TestOutcome` object, which contains information about the name and tags used for this test. It also passes in the `EnvironmentVariables`, which gives you access to the current environment configuration. An example of a simple `BeforeAWebdriverScenario` is shown below:

```java
public class MyCapabilityEnhancer implements BeforeAWebdriverScenario {

    @Override
    public DesiredCapabilities apply(EnvironmentVariables environmentVariables,
                                     SupportedWebDriver driver,
                                     TestOutcome testOutcome,
                                     MutableCapabilities capabilities) {
        capabilities.setCapability("name", testOutcome.getStoryTitle() + " - " + testOutcome.getTitle());
        return capabilities;
    }
}
```

### The AfterAWebdriverScenario interface

The `AfterAWebdriverScenario` is called at the end of a test, just before the driver is closed, and once the result of the test is known. The test result (and other details) can be obtained from the `TestOutcome` parameter. This allows any last manipulations or checks to be performed on the driver, before the end of the test. The following example checks the result of the test that has just finished, and adds a cookie with a value depending on the test outcome:

```java
public class MyTestResultUpdater implements AfterAWebdriverScenario {
    void apply(EnvironmentVariables environmentVariables,
               TestOutcome testOutcome,
               WebDriver driver) {
       if ((driver == null) || (!RemoteDriver.isARemoteDriver(driver))) {
           return;
       }

       Cookie cookie = new Cookie("testPassed",
                                   testOutcome.isFailure() || testOutcome.isError() || testOutcome.isCompromised() ? "false" : "true");
       driver.manage().addCookie(cookie);
    }
}
```

### Driver Enhancers

If you need to perform some action on the driver instance before each test, you can implement the `CustomDriverEnhancer` class. Note that this will be called immediately after the driver is created, and before any page is opened, so the number of actions is relatively limited.

### Configuring the extension packages

The last thing you need to do is to tell Serenity what package it needs to look for your extension classes. Add the package, or a parent package to your Serenity configuration using the `serenity.extension.packages`.

`serenity.extension.packages=com.acme.myserenityextensions`

You can find an example of how these classes are implemented in a real-world use case in the [serenity-browserstack](https://github.com/serenity-bdd/serenity-core/tree/master/serenity-browserstack/src/main/java/net/serenitybdd/browserstack) module on Github.

### Custom WebDriver implementations

You can add your own custom WebDriver provider by implementing the DriverSource interface. First, you need to set up the following system properties (e.g. in your `serenity.properties` file):

```
webdriver.driver = provided
webdriver.provided.type = mydriver
webdriver.provided.mydriver = com.acme.MyPhantomJSDriver
thucydides.driver.capabilities = mydriver
```

Your custom driver must implement the DriverSource interface, as shown here:

```java
public class MyPhantomJSDriver implements DriverSource {

    @Override
    public WebDriver newDriver() {
        try {
            DesiredCapabilities capabilities = DesiredCapabilities.phantomjs();
            // Add
            return new PhantomJSDriver(ResolvingPhantomJSDriverService.createDefaultService(), capabilities);
        }
        catch (IOException e) {
            throw new Error(e);
        }
    }

	@Override
    public boolean takesScreenshots() {
        return true;
    }
}
```

Note that if you use custom drivers you will be entirely responsible for configuring and instantiating the browser instance, and the driver-related Serenity configuration options will not apply. We generally recommend using custom drivers only for very exceptional circumstances, and using `BeforeAWebdriverScenario` classes for most custom configuration requirements.

## Using the HasAuthentication interface

Selenium 4 supports the `HasAuthentication` interface, which indicates that a driver supports authenticating to a website in some way. Serenity drivers integrate seemlessly with the `HasAuthentication` interface, so you can use it in the same way as you would in Selenium 4. For example, to register a username and password to use on all pages, you could add the following code before opening a site:

```java
    getDriver().register(UsernameAndPassword.of("scott", "tiger")
```

If authentication is only required on certain pages, you can also use a predicate:

```java
        Predicate<URI> onlyAuthenticateOnTheLoginPage = uri -> uri.getPath().endsWith("/login");
        getDriver().register(onlyAuthenticateOnTheLoginPage, UsernameAndPassword.of("scott", "tiger"));
```


---

<!-- https://serenity-bdd.github.io/docs/guide/annotation-requirements -->

# Defining Requirements with Annotations

Serenity BDD organises test results into a _requirements hierarchy_, which provides the structure for the Living Documentation reports. By default, this hierarchy is derived from the package structure (for JUnit tests) or from the directory structure (for Cucumber feature files).

Starting with Serenity 5.3.1, you can define the requirements hierarchy directly using **annotations** on your test classes. This provides a simple, explicit, and declarative way to organise your tests into a meaningful structure, without having to rely on package naming conventions.

## The Requirements Hierarchy

Serenity supports a three-level requirements hierarchy:

```
Epic > Feature > Story
```

Each level is represented by an annotation:

| Annotation | Level | Purpose |
|---|---|---|
| `@Epic` | Highest | A large body of work, spanning multiple features |
| `@Feature` | Middle | A coherent piece of functionality that users value |
| `@Story` | Lowest | A specific user story or scenario group within a feature |

You can use any combination of these levels. Not all three are required &mdash; a two-level structure (`@Feature` > `@Story`) or even a single level (`@Feature` alone) works just as well.

## Basic Usage

### Feature and Story

The most common pattern is to annotate a test class with `@Feature` and `@Story`:

```java
import net.serenitybdd.annotations.Feature;
import net.serenitybdd.annotations.Story;

@Feature("Managing Todos")
@Story("Complete todo items")
class WhenCompletingTodosTest extends SerenityPlaywrightTest {

    @Test
    void shouldMarkTodoAsCompleted() {
        // ...
    }

    @Test
    void shouldToggleAllTodosToCompleted() {
        // ...
    }
}
```

This produces the following hierarchy in the requirements report:

```
Managing Todos (feature)
└── Complete todo items (story)
    ├── Should mark todo as completed
    └── Should toggle all todos to completed
```

### Multiple Stories Under the Same Feature

Several test classes can share the same feature while defining different stories:

```java
@Feature("Managing Todos")
@Story("Complete todo items")
class WhenCompletingTodosTest { /* ... */ }

@Feature("Managing Todos")
@Story("Delete todo items")
class WhenDeletingTodosTest { /* ... */ }

@Feature("Managing Todos")
@Story("Filter todo items")
class WhenFilteringTodosTest { /* ... */ }
```

This creates a single feature in the report with three child stories:

```
Managing Todos (feature)
├── Complete todo items (story)
├── Delete todo items (story)
└── Filter todo items (story)
```

### Multiple Features

Different test classes can belong to different features:

```java
@Feature("Creating Todos")
@Story("Add todo items")
class WhenAddingTodosTest { /* ... */ }

@Feature("Managing Todos")
@Story("Complete todo items")
class WhenCompletingTodosTest { /* ... */ }
```

This produces two separate features in the report:

```
Creating Todos (feature)
└── Add todo items (story)

Managing Todos (feature)
└── Complete todo items (story)
```

## The Full Three-Level Hierarchy

For larger projects, you can use `@Epic` to group related features:

```java
import net.serenitybdd.annotations.Epic;
import net.serenitybdd.annotations.Feature;
import net.serenitybdd.annotations.Story;

@Epic("E-Commerce Platform")
@Feature("Shopping Cart")
@Story("Add item to cart")
class WhenAddingItemsToCartTest { /* ... */ }

@Epic("E-Commerce Platform")
@Feature("Shopping Cart")
@Story("Remove item from cart")
class WhenRemovingItemsFromCartTest { /* ... */ }

@Epic("E-Commerce Platform")
@Feature("Checkout")
@Story("Pay with credit card")
class WhenPayingWithCreditCardTest { /* ... */ }
```

This produces a three-level hierarchy:

```
E-Commerce Platform (epic)
├── Shopping Cart (feature)
│   ├── Add item to cart (story)
│   └── Remove item from cart (story)
└── Checkout (feature)
    └── Pay with credit card (story)
```

## Using @DisplayName as the Story Name

When a test class has `@Feature` (or `@Epic`) but no `@Story` annotation, Serenity uses the JUnit 5 `@DisplayName` value as the story name. This is convenient when you want the display name in JUnit and the story name in Serenity to be the same:

```java
@Feature("Managing Todos")
@DisplayName("Complete todo items")
class WhenCompletingTodosTest {

    @Test
    @DisplayName("should mark a todo as completed")
    void shouldMarkTodoAsCompleted() {
        // ...
    }
}
```

This produces the same hierarchy as if you had written `@Story("Complete todo items")`:

```
Managing Todos (feature)
└── Complete todo items (story)
    └── should mark a todo as completed
```

When both `@Story` and `@DisplayName` are present, `@Story` takes precedence for the requirements hierarchy, and `@DisplayName` is used only for the JUnit test runner display:

```java
@Feature("Managing Todos")
@Story("Complete todo items")
@DisplayName("When completing todos")
class WhenCompletingTodosTest { /* ... */ }
```

Here, the story name in the report is "Complete todo items" (from `@Story`), not "When completing todos" (from `@DisplayName`).

:::tip When to use @Story vs @DisplayName

Use `@Story` when you want the requirements hierarchy name to differ from the JUnit display name. For example, you might want a business-oriented name in the report ("Complete todo items") while using a BDD-style name in the test runner ("When completing todos").

Use `@DisplayName` alone (without `@Story`) when the same name works for both purposes.
:::

## Using @Feature Without @Story or @DisplayName

If a test class has only `@Feature` with no `@Story` and no `@DisplayName`, the test class is placed directly under the feature. The humanised class name is used as the story name:

```java
@Feature("Managing Todos")
class WhenCompletingTodos {
    // Story name in report: "When completing todos" (from class name)
}
```

## Partial Hierarchies

You don't need to use all three levels. Any subset works:

### Feature Only

```java
@Feature("User Authentication")
@Story("Login with valid credentials")
class WhenLoggingInTest { /* ... */ }
```

```
User Authentication (feature)
└── Login with valid credentials (story)
```

### Epic and Feature (No Story)

```java
@Epic("Security")
@Feature("User Authentication")
@DisplayName("Login with valid credentials")
class WhenLoggingInTest { /* ... */ }
```

```
Security (epic)
└── User Authentication (feature)
    └── Login with valid credentials (story)
```

### Epic Only

```java
@Epic("Security")
@DisplayName("Login with valid credentials")
class WhenLoggingInTest { /* ... */ }
```

```
Security (epic)
└── Login with valid credentials (story)
```

## Inheriting Annotations from Superclasses

Annotations are inherited from parent classes. This is useful when you have a common base class for a group of tests:

```java
@Epic("TodoMVC Application")
@Feature("Managing Todos")
abstract class TodoManagementTest extends SerenityPlaywrightTest {
    // Common setup and utilities
}

@Story("Complete todo items")
class WhenCompletingTodosTest extends TodoManagementTest {
    // Inherits @Epic and @Feature from parent
}

@Story("Delete todo items")
class WhenDeletingTodosTest extends TodoManagementTest {
    // Inherits @Epic and @Feature from parent
}
```

The most specific annotation wins. If a subclass redefines an annotation that is already present on the parent, the subclass annotation takes precedence:

```java
@Feature("General Feature")
abstract class BaseTest { }

@Feature("Specific Feature")  // Overrides parent's @Feature
@Story("My Story")
class SpecificTest extends BaseTest { }
```

## Inheriting Annotations in JUnit 5 @Nested Classes

When using JUnit 5 `@Nested` inner classes, annotations on the enclosing (outer) class are inherited by the nested class. This is a natural way to define the feature or epic once on the outer class and then define individual stories in each nested class:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@Feature("Product Catalog")
class ProductCatalogTests {

    @Nested
    @Story("Searching by keyword")
    class WhenSearchingByKeyword {

        @Test
        void shouldFindProductsByName() { /* ... */ }

        @Test
        void shouldReturnEmptyResultsForUnknownKeyword() { /* ... */ }
    }

    @Nested
    @Story("Browsing by category")
    class WhenBrowsingByCategory {

        @Test
        void shouldListProductsInCategory() { /* ... */ }
    }
}
```

This produces the following hierarchy in the requirements report:

```
Product Catalog (feature)
├── Searching by keyword (story)
│   ├── Should find products by name
│   └── Should return empty results for unknown keyword
└── Browsing by category (story)
    └── Should list products in category
```

### Full Three-Level Hierarchy with Nested Classes

You can combine `@Epic` and `@Feature` on the outer class with `@Story` on nested classes for the full hierarchy:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@Epic("E-Commerce Platform")
@Feature("Shopping Cart")
class ShoppingCartTests {

    @Nested
    @Story("Add item to cart")
    class WhenAddingItems {
        @Test
        void shouldAddSingleItem() { /* ... */ }
    }

    @Nested
    @Story("Remove item from cart")
    class WhenRemovingItems {
        @Test
        void shouldRemoveSelectedItem() { /* ... */ }
    }
}
```

This produces:

```
E-Commerce Platform (epic)
└── Shopping Cart (feature)
    ├── Add item to cart (story)
    │   └── Should add single item
    └── Remove item from cart (story)
        └── Should remove selected item
```

### Overriding Annotations in Nested Classes

If a nested class redefines an annotation that is already present on the outer class, the nested class annotation takes precedence:

```java
@Feature("Product Catalog")
class ProductTests {

    @Nested
    @Feature("Checkout")  // Overrides "Product Catalog"
    @Story("Express checkout")
    class WhenUsingExpressCheckout { /* ... */ }
}
```

### Using @DisplayName as Story Name in Nested Classes

When a nested class has no `@Story` annotation, its `@DisplayName` is used as the story name, just as it is for top-level classes:

```java
@Feature("Product Catalog")
class ProductCatalogTests {

    @Nested
    @DisplayName("Searching by keyword")  // Used as the story name
    class WhenSearchingByKeyword { /* ... */ }
}
```

:::tip Nested classes vs separate test classes
Use `@Nested` classes when you want to group related stories under a single outer class and share setup code. Use separate top-level test classes when the stories are more independent. Both approaches produce the same requirements hierarchy in the reports.
:::

## Annotations vs Package-Based Requirements

Annotation-based requirements **override** the default package-based hierarchy for the annotated test class. This means you can mix both approaches in the same project:

- Test classes with `@Feature`, `@Story`, or `@Epic` annotations use the annotation-based hierarchy
- Test classes without these annotations fall back to the package-based hierarchy

:::info

When annotation-based and package-based hierarchies coexist in the same project, they appear as separate branches in the requirements tree. There is no merging between the two.

:::

## Annotations and Cucumber

If you use both JUnit tests and Cucumber feature files in the same project, each group will have its own place in the requirements hierarchy:

- **JUnit tests** with `@Feature`/`@Story` annotations create requirements based on the annotation values
- **Cucumber features** create requirements based on the directory structure and feature file names

To avoid confusion, use distinct names for annotation-based features and Cucumber features, or organise them into separate sections of your requirements hierarchy using `@Epic`.

## Working with the Screenplay Pattern

The annotations work the same way with Screenplay-based tests:

```java
import net.serenitybdd.annotations.Feature;
import net.serenitybdd.annotations.Story;
import net.serenitybdd.screenplay.ensure.Ensure;

@Feature("Managing Todos")
@Story("Filter todo items")
@DisplayName("When filtering todos (Screenplay)")
class WhenFilteringTodosScreenplayTest extends ScreenplayPlaywrightTest {

    @Test
    @DisplayName("should filter to show only active todos")
    void shouldFilterToShowOnlyActiveTodos() {
        toby.attemptsTo(
            FilterTodos.toShowActive(),
            Ensure.that(TheCurrentFilter.selected()).isEqualTo("Active"),
            Ensure.that(TheVisibleTodos.displayed())
                .containsExactly("Buy milk", "Do laundry")
        );
    }
}
```

## Tags

In addition to organising the requirements hierarchy, the `@Epic`, `@Feature`, and `@Story` annotations also generate tags in the Serenity reports. A test annotated with:

```java
@Epic("E-Commerce Platform")
@Feature("Shopping Cart")
@Story("Add item to cart")
```

will have the following tags in the report:
- `epic:E-Commerce Platform`
- `feature:Shopping Cart`
- `story:Add item to cart`

These tags can be used for filtering test results in the Serenity reports.

## Summary of Annotation Behaviour

| Annotations Present | Story Name in Report | Requirements Path |
|---|---|---|
| `@Feature` + `@Story` | `@Story` value | Feature / Story |
| `@Feature` + `@DisplayName` (no `@Story`) | `@DisplayName` value | Feature / DisplayName |
| `@Feature` only | Humanised class name | Feature / class name |
| `@Epic` + `@Feature` + `@Story` | `@Story` value | Epic / Feature / Story |
| `@Epic` + `@Feature` + `@DisplayName` | `@DisplayName` value | Epic / Feature / DisplayName |
| `@Epic` + `@Story` | `@Story` value | Epic / Story |
| `@Epic` + `@DisplayName` | `@DisplayName` value | Epic / DisplayName |
| `@Story` only | `@Story` value | Story |
| No annotations + `@DisplayName` | `@DisplayName` value | Package-based path |

## Migration from Class-Based Annotations

In earlier versions of Serenity, the `@Story` annotation required a class reference to define the requirements hierarchy:

```java
// Legacy approach (still supported)
public class MyApp {
    @Feature
    public class ShoppingCart {
        public class AddItem {}
    }
}

@Story(storyClass = MyApp.ShoppingCart.AddItem.class)
class WhenAddingItemsTest { /* ... */ }
```

This approach required creating boilerplate marker classes and only supported a two-level hierarchy (Feature > Story).

The new string-based annotations replace this with a simpler, more flexible approach:

```java
// New approach
@Feature("Shopping Cart")
@Story("Add item to cart")
class WhenAddingItemsTest { /* ... */ }
```

The legacy `@Story(storyClass = ...)` syntax is still supported for backwards compatibility.


---

<!-- https://serenity-bdd.github.io/docs/guide/page_elements -->

# Serenity Page Elements

## Introduction
In most Selenium-based test automation frameworks, CSS or XPath selectors are commonly used to locate elements on a page.
Serenity BDD provides a simpler way of interacting with common UI components, which can avoid needing to use XPath or CSS expressions.

For example, the following HTML code illustrates a few different ways to represent a button:
```html
<button type="button" class="btn btn-primary">Login</button>
<input type="submit" value="Login">
```

In Serenity, we could interact with these using XPath or CSS, e.g.
```java
$("css:input[value='Login']").click()
```
or
```java
$("xpath://button[.='Login']").click()
```

However, if the UI implementation switched from one to another, the test would break.

Serenity Page Elements provide a more intuitive way to identify many common UI elements. Using Serenity Page Elements, we can use a more expression like this:

```java
import net.serenitybdd.screenplay.ui.Button;
.
.
.
$(Button.withText("Login")).click();
```

Or for a Screenplay test, you could do the following:

```java
actor.attemptsTo(
    Click.on(Button.withText("Login"))
);
```

Under the hood, Serenity will look for either `<button>` elements, or `<input>` elements of type `submit`, that display the "Login" text. 

Another common location strategy is to use attributes like `id` or `name`, or test-specific attributes like `data-test`. 

Suppose we have the following HTML code:

```html
<button type="button" class="btn btn-primary" data-test="login-button">Login</button>
```

We could click on this button with the following code:

```java
$(Button.withNameOrId("login-button")).click();
```

Or in Screenplay, we could do the following:
```java
actor.attemptsTo(
    Click.on(Button.withNameOrId("login-button"))
);
```

In this case, Serenity will look for `<button>` elements, or `<input>` elements of type `submit`, with a _value_, _id_, _data-test_ or _aria-label_ attribute of "login-button".

This means that, in many cases, you can use the `Button` class directly in your code, without having to inspect the page structure first.

Serenity Page Elements are found in the `serenity-screenplay-webdriver` module, but they can be used in both Screenplay and Action Class-based tests.

There are many different types of page elements available. All of them have the `withNameOrId()` method, but some have other methods for more specific locator strategies, such as `withLabel()` for checkboxes. 

The following table gives an overview of the different types of PageElement available:

| Element type     | Example     |
| ---------------- | ----------- |
| Buttons          | Button.withText("A Button")             |
| Checkboxes       | Checkbox.withValue("Ferrari")          |
| Dropdowns        | Dropdown.withLabel("---Pick Your Car---")          |
| Images           | Image.withAltText("Girl in a jacket")          |
| Input Fields     | InputField.withPlaceholder("Enter the customer name")         |
| Link             | Link.withIcon("glyphicon-cloud")       |
| PageElement      | PageElement.locatedBy(".item").containingText("Item 1")      |
| RadioButton      | RadioButton.withNameOrId("red-button")      |


Let's look at each type of page element in more detail.

## Buttons

The `Button` page element locates a `<button>` element with a specific tect, or an `<input>` element of type `submit` with a specific value.

Suppose we have the following HTML code:
```
<button type="button">A Button</button>
<input type="submit" value="Submit Me!" name="submit-button" data-test="submit-the-button">
<input type="button" value="Press Here">
<button type="button"><i class="glyphicon glyphicon-home"></i>Home</button>
```


We could use the following expressions to identify these elements:

| Strategy    | Example     |
| ----------- | ----------- |
| By text     | Button.withText("A Button")             |
| By value    | Button.withText("Press Here")           |
| By name     | Button.withNameOrId("submit-button")                           |
| By data-test attribute     | Button.withNameOrId("submit-the-button")        |
| By icon     | Button.withIcon("glyphicon-home")        |

:::tip
The `withNameOrId()` method will match the `id`, `name`, `data-test` or `aria-label` attribute for any kind of Page Element, so we won't always repeat them everywhere in the following sections.
:::

## Checkbox
This element will match an `<input>` element of type "checkbox", with a specified _value_,
_data-test_, or _class_ attribute value.

Suppose we have the following HTML:
```html
<input type="checkbox" id="vehicle1" value="Bike" class="vehicule-option">
<label for="vehicle1"> I have a bike</label><br>
<input type="checkbox" id="vehicle2" value="Car" class="vehicule-option">
<label for="vehicle2"> I have a car</label><br>
<input type="checkbox" id="vehicle3" value="Boat" class="vehicule-option" checked>
<label for="vehicle3"> I have a boat</label><br>
```

We could use the following expressions to identify these elements:

| Strategy    | Example     |
| ----------- | ----------- |
| By id       | Checkbox.withNameOrId("vehicle1")           |
| By value    | Checkbox.withValue("Bike")            |
| By label    | Checkbox.withLabel("I have a bike")   |

## Dropdown

The `Dropdown` page element lets us work with a `<select>` dropdown list. Suppose we had the following HTML:
```html
<label for="cars">Choose a car:</label>
<select name="cars" id="cars">
    <option value="">---Pick Your Car---</option>
    <option value="volvo">Volvo</option>
    <option value="saab">Saab</option>
    <option value="mercedes">Mercedes</option>
    <option value="audi">Audi</option>
</select>
```

We could use the following expressions to identify these elements:

| Strategy              | Example     |
| -----------           | ----------- |
| By name or id         | Dropdown.withNameOrId("cars")           |
| By label         | Dropdown.withLabel("Choose a car:")          |
| By default option         | Dropdown.withLabel("---Pick Your Car---")          |

## Image

The `Image` page element lets us interact with `<img>` elements. For example, suppose we had the following HTML code:

```html
<img src="img_girl.jpg" alt="Girl in a jacket" width="500" height="600">
```

We could use the following expressions to identify these elements:

| Strategy        | Example     |
| -----------     | ----------- |
| By alt text     | Image.withAltText("Girl in a jacket")           |
| By src          | Image.withSrc("img_girl.jpg")             |
| By src (starting with) | Image.withSrcStartingWith("img_")             |
| By src (ending with) | Image.withSrcEndingWith("girl.jpg")             |


## InputField

The `InputField` page element represents an `<input>` element in a form, with or without a `<label>`. For example, suppose we had the following HTML code:

```html
<label for="customer_name">Customer Name</label>
<input type="text" id="customer_name" name="customername" placeholder="Enter the customer name" />
```

We could use the following expressions to identify these elements:

| Strategy        | Example     |
| -----------     | ----------- |
| By name         | InputField.withNameOrId("customername")           |
| By id           | InputField.withNameOrId("customer_name")           |
| By placeholder  | InputField.withPlaceholder("Enter the customer name")              |
| By label        | InputField.withLabel("Customer Name")   |

## Link

The `Link` page element interacts with HTML `<a>` elements. For example, suppose we have the following HTML code:

```html
<!-- A simple link --->
<a href="...">Link 1</a><br/>
<!-- A link with a title -->
<a href="..." title="Link Number 2">Link 2</a><br/>
<!-- A link with an icon and a text-->
<a href="#" onclick="update('Link 3')"><i class="glyphicon glyphicon-cloud"></i>Link 3</a><br/>
```

We could use the following expressions to identify these elements:

| Strategy              | Example     |
| -----------           | ----------- |
| By link text          | Link.withText("Link 1")           |
| By link title         | Link.withTitle("Link Number 2")          |
| By partial link text  | Link.containing("ink")              |
| By starting text      | Link.startingWith("Link")    |
| By icon               | Link.withIcon("glyphicon-cloud")    |


## PageElement

The `PageElement` page element represents any element on a page. For example, suppose we have the following HTML code:

```html
<div id="container" data-test="the-container" class="a-container">
    <div class="item">
        <h2>Item 1 heading</h2>
        <div>
            <span class="description">Item 1 description</span>
        </div>
    </div>
    <div class="item">
        <h2>Item 2 heading</h2>
        <div>
            <span class="description">Item 2 description</span>
        </div>
    </div>
</div>
```

We could use the following expressions to identify elements in this code:

| Strategy                    | Example     |
| -----------                 | ----------- |
| By id                       | PageElement.withNameOrId("container")           |
| By data-test value          | PageElement.withNameOrId("the-container")           |
| Containing a text value           | PageElement.withNameOrId("item").containingText("Item 1")         |
| Containing a text value (with a CSS locator)          | PageElement.locatedBy(".item").containingText("Item 1")         |

## RadioButton

The `RadioButton` page element represents a set of radio buttons. For example, suppose we have the following HTML code:


```html
<input type="radio" id="html" name="fav_language" value="HTML" class="html-radio">
<label for="html">Choose HTML</label><br>
<input type="radio" id="css" name="fav_language" value="CSS">
<label for="css">Choose CSS</label><br>
<input type="radio" id="javascript" name="fav_language" value="JavaScript">
<label for="javascript">Choose JavaScript</label><br><br>
```

We could use the following expressions to identify these elements:

| Strategy              | Example     |
| -----------           | ----------- |
| By id          | RadioButton.withNameOrId("html")           |
| By label         | RadioButton.withLabel("Choose CSS")         |
| By value  |RadioButton.withValue("JavaScript")            |


# Using Page Elements in Action Classes

You can also use Page Elements in your normal (non-Screenplay) tests, simply by using the Page Element expression as a locator. For example:

```java
public class LoginActions extends UIInteractionSteps {

    @Step("Login as a standard user")
    public void asAStandardUser() {
        $(InputField.withPlaceholder("Username")).type("standard_user");
        $(InputField.withPlaceholder("Password")).type("secret_sauce");
        $(Button.withText("Login")).click();
    }
}
```

Page Elements can be used with all of the usual methods for locating elements in a UI Interaction class, including:

| Method              | Example     |
| -----------         | ----------- |
| $                   | $(Button.withText("Login")).click();          |
| find                | find(Button.withText("Login")).click();       |
| $$                  | $$(Checkbox.withNameOrId("vehicle-option")).forEach(WebElementFacade::click);       |
| findAll             | findAll(Checkbox.withNameOrId("vehicle-option")).forEach(WebElementFacade::click);       |


---

<!-- https://serenity-bdd.github.io/docs/guide/driver_config -->

Selenium WebDriver lets you run your tests in a variety of browsers, each with a variety of configuration options. In this section we will look at how to configure your WebDriver driver in Serenity.

The simplest way to configure the driver you want to use is in your project's `serenity.conf` file (which you will find in `src/test/resources` folder).

Basic configuration options go in the `webdriver` section. For example, to run your tests with Chrome, you set the `webdriver.driver` property to "chrome":

```hocon
webdriver {
    driver = "chrome"
}
```

All of the standard WebDriver browsers are supported:

| Browser           | Value       | Example                       |
| -----------       | ----------- | ----------------------------  |
| Chrome            | chrome      | webdriver.driver = "chrome"   |
| Firefox           | firefox     | webdriver.driver = "firefox"  |
| Microsoft Edge    | edge        | webdriver.driver = "edge"     |
| Internet Explorer | IE          | webdriver.driver = "IE"       |
| Safari            | safari      | webdriver.driver = "safari"   |

## Configuring the WebDriver drivers

When you run a WebDriver test against almost any driver, you need an OS-specific binary file to act as an intermediary between your test and the browser you want to manipulate. The main drivers, and where you can download them from, are listed below:

| Browser | Driver | Location | System Property |
| ------- | ------ | -------- | --------------- |
| Chrome | chromedriver | http://chromedriver.chromium.org | webdriver.chrome.driver |
| Firefox | geckodriver | https://github.com/mozilla/geckodriver/releases | webdriver.gecko.driver |
| Microsoft Edge | msedgedriver | https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ | webdriver.edge.driver |
| Internet Explorer | IEDriverServer | https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver | webdriver.ie.driver |


### Automatic driver downloads

By default, Selenium automatically downloads and installs the appropriate driver binaries for the specified driver.

### Configuring driver binaries by hand

If you cannot or do not want to download the WebDriver binaries automatically using WebDriverManager (for example, if you are in a corporate network which does not have access to the WebDriverManager binaries), you can download the binaries and configure them directly in the `serenity.conf` file.

In this case you need to either have the correct driver binary on your system path, or provide the path to the binary using the system property shown in the table above. For example, your serenity.conf file might contain the following:

```hocon
webdriver.gecko.driver=/path/to/my/geckodriver
```

However, adding a system path to your serenity.properties file is poor practice, as it means your tests will only run if the specified directory and binary exists, and that you are running the tests on the correct operating system. This obviously makes little sense if you are running your tests both locally, and on a CI environment.

A more robust approach is to have your drivers in your source code, but have different drivers per OS. Serenity allows you to pass driver-specific properties to a driver, as long as they are prefixed with drivers._os_. For example, the following line will configure the webdriver.chrome.driver if you are running your tests under windows.

```hocon
drivers {
  windows {
    webdriver.chrome.driver = src/test/resources/webdriver/windows/chromedriver.exe
  }
```

You can easily configure different binaries for different operating systems like this:

```hocon
drivers {
  windows {
    webdriver.chrome.driver = src/test/resources/webdriver/windows/chromedriver.exe
  }
  mac {
    webdriver.chrome.driver = src/test/resources/webdriver/mac/chromedriver
  }
  linux {
    webdriver.chrome.driver = src/test/resources/webdriver/linux/chromedriver
  }
}
```

This approach also works when you have more than one driver to configure. Suppose you need to run tests on three environments, using Firefox or Windows. One convenient approach is to store your drivers in a directory structure under src/test/resources similar to the following:

```
src/test/resources
└── webdriver
    ├── linux
    │   ├── chromedriver
    │   └── geckodriver
    ├── mac
    │   ├── chromedriver
    │   └── geckkodriver
    └── windows
        ├── chromedriver.exe
        └── geckodriver.exe
```

This means that your tests will not need the webdriver binaries to be installed on every machine.

The corresponding `serenity.conf` configuration for both browsers and each operating system would look like this:

```hocon
drivers {
  windows {
    webdriver.chrome.driver = src/test/resources/webdriver/windows/chromedriver.exe
    webdriver.gecko.driver = src/test/resources/webdriver/windows/geckodriver.exe
  }
  mac {
    webdriver.chrome.driver = src/test/resources/webdriver/mac/chromedriver
    webdriver.gecko.driver = src/test/resources/webdriver/mac/geckodriver
  }
  linux {
    webdriver.chrome.driver = src/test/resources/webdriver/linux/chromedriver
    webdriver.gecko.driver = src/test/resources/webdriver/linux/geckodriver
  }
}
```

## Specifying W3C properties

[W3C capabilities](https://www.w3.org/TR/webdriver/#capabilities) are a standard set of driver features that every drive implementation must support. You can configure W3C capabilities in the `wenbdriver.capabilities` section of your `serenity.conf` file, as shown here:

```hocon
webdriver {
  capabilities {
    browserName = "Chrome"
    browserVersion = "103.0"
    platformName = "Windows 11"
    acceptInsecureCerts = true
  }
}
```

You can define timeouts in a dedicated subsection like this:

```hocon
webdriver {
  capabilities {
    browserName = "Chrome"
    browserVersion = "103.0"
    platformName = "Windows 11"
    timeouts {
      script = 30000
      pageLoad = 300000
      implicit = 2000
    }
  }
}
```

You can also define proxy configuration details in the `proxy` section:
```hocon
webdriver {
  capabilities {
    browserName = "Chrome"
    browserVersion = "103.0"
    platformName = "Windows 11"
    proxy {
      proxyType = "30000"
      httpProxy = "myproxy.myorgcom:3128"
    }
  }
}
```

## Configuring Chrome

# Configuring Selenium WebDriver

[Previous content unchanged until Chrome configuration section...]

## Configuring Chrome

You can use the special `"goog:chromeOptions"` capability to define any of the [ChromeDriver options](https://chromedriver.chromium.org/capabilities)
```hocon
webdriver {
  capabilities {
    browserName = "Chrome"
    browserVersion = "103.0"
    platformName = "Windows 11"
    screenResolution = "1280x1024"

    "goog:chromeOptions" {
      args = [ "window-size=1000,800", "headless" ]
      binary = ${HOME}/path/to/chromedriver
      detach = true
      localState = {
        cart-contents = [1,2,3]
      }
    }
  }
}
```

### Configuring Chromedriver arguments

### Configuring proxy settings

Chrome supports various proxy configurations that can be specified in your `serenity.conf` file. You can configure proxies in either the general capabilities section or within the Chrome-specific options:

#### Basic Proxy Configuration
```hocon
webdriver {
  capabilities {
    "goog:chromeOptions" {
      proxy {
        proxyType = "MANUAL"
        httpProxy = "proxy.example.com:8080"
        sslProxy = "proxy.example.com:8443"
        noProxy = "localhost,127.0.0.1,.example.com"
      }
    }
  }
}
```

#### Proxy Types
Serenity supports several proxy types:

1. Manual Proxy Configuration
```hocon
"goog:chromeOptions" {
  proxy {
    proxyType = "MANUAL"
    httpProxy = "proxy.example.com:8080"    # HTTP proxy
    sslProxy = "proxy.example.com:8443"     # HTTPS proxy
    socksProxy = "socks.example.com:1080"   # SOCKS proxy
    socksVersion = 5                        # SOCKS version (4 or 5)
    noProxy = "localhost,127.0.0.1"         # Bypass proxy for these addresses
  }
}
```

2. PAC (Proxy Auto-Configuration)
```hocon
"goog:chromeOptions" {
  proxy {
    proxyType = "PAC"
    proxyAutoconfigUrl = "http://proxy.example.com/proxy.pac"
  }
}
```

3. System Proxy
```hocon
"goog:chromeOptions" {
  proxy {
    proxyType = "SYSTEM"  # Use system's proxy settings
  }
}
```

4. Direct Connection
```hocon
"goog:chromeOptions" {
  proxy {
    proxyType = "DIRECT"  # No proxy (direct connection)
  }
}
```

5. Auto-detect
```hocon
"goog:chromeOptions" {
  proxy {
    proxyType = "AUTODETECT"  # Auto-detect proxy settings
  }
}
```

#### Proxy Authentication
For proxies requiring authentication, include the credentials in the proxy URL:
```hocon
"goog:chromeOptions" {
  proxy {
    proxyType = "MANUAL"
    httpProxy = "username:password@proxy.example.com:8080"
  }
}
```

#### Environment-Specific Proxy Configuration
You can configure different proxy settings for different environments:
```hocon
environments {
  dev {
    webdriver.capabilities {
      "goog:chromeOptions" {
        proxy {
          proxyType = "DIRECT"
        }
      }
    }
  }
  qa {
    webdriver.capabilities {
      "goog:chromeOptions" {
        proxy {
          proxyType = "MANUAL"
          httpProxy = "proxy.qa.example.com:8080"
          sslProxy = "proxy.qa.example.com:8443"
          noProxy = "*.qa.example.com,localhost"
        }
      }
    }
  }
}
```

## Configuring Microsoft Edge

Microsoft Edge is a Chromium driver, so the configuration is very similar to Chrome. The main difference is the use of `"ms:edgeOptions'"` instead of `"goog:chromeOptions"`. A typical configuration is shown below:

```hocon
webdriver {
  capabilities {
    browserName = "MicrosoftEdge"
    "ms:edgeOptions" {
      args = ["test-type", "ignore-certificate-errors", "headless",
        "incognito", "disable-infobars", "disable-gpu", "disable-default-apps", "disable-popup-blocking"]
    }
  }
}

```

## Configuring Firefox

Firefox uses the `"moz:firefoxOptions"` capability to define browser-specific option. A sample configuration is shown below:

```hocon
webdriver {
  capabilities {
    browserName = "firefox"

    timeouts {
      implicit = 1000
      script = 1000
      pageLoad = 1000
    }
    pageLoadStrategy = "normal"
    acceptInsecureCerts = true
    unhandledPromptBehavior = "dismiss"
    strictFileInteractability = true

    "moz:firefoxOptions" {
      args = ["-headless"],
      prefs {
        "javascript.options.showInConsole": false
      },
      log {"level": "info"},
    }
  }
}
```

# Configuring multiple environments

You can configure multiple driver configurations by using the `environments` section, as shown below. Then simply set the `environment` system property to the corresponding environment to use these settings, e.g.

```
mvn clean verify -Denvironment=chrome
```

A sample environments section is shown here:

```
environments {
  chrome {
    webdriver {
      driver = chrome
      autodownload = true
      capabilities {
        browserName = "chrome"
        acceptInsecureCerts = true
        "goog:chromeOptions" {
          args = ["test-type", "ignore-certificate-errors", "headless", "--window-size=1000,800"
            "incognito", "disable-infobars", "disable-gpu", "disable-default-apps", "disable-popup-blocking"]
        }
      }
    }
  }
  edge {
    webdriver {
      capabilities {
        browserName = "MicrosoftEdge"
        "ms:edgeOptions" {
          args = ["test-type", "ignore-certificate-errors", "headless",
            "incognito", "disable-infobars", "disable-gpu", "disable-default-apps", "disable-popup-blocking"]
        }
      }
    }
  }
  firefox {
    webdriver {
      capabilities {
        browserName = "firefox"
        pageLoadStrategy = "normal"
        acceptInsecureCerts = true
        unhandledPromptBehavior = "dismiss"
        strictFileInteractability = true

        "moz:firefoxOptions" {
          args = ["-headless"],
          prefs {
            "javascript.options.showInConsole": false
          },
          log {"level": "info"},
        }
      }
    }
  }
}
```


---

<!-- https://serenity-bdd.github.io/docs/guide/cucumber -->

# Running Cucumber scenarios with Serenity

:::tip Comprehensive Cucumber Guide Available
For a complete, in-depth guide on using Cucumber with Serenity BDD and JUnit 5, including configuration options, best practices, and troubleshooting, see the dedicated [Cucumber with JUnit 5](/docs/cucumber/cucumber-junit5) section.
:::

To run Cucumber scenarios with Serenity, you need to create a Junit 5 test runner class like this:

```java
   import org.junit.platform.suite.api.IncludeEngines;
   import org.junit.platform.suite.api.SelectClasspathResource;
   import org.junit.platform.suite.api.Suite;
   
   @Suite
   @IncludeEngines("cucumber")
   @SelectClasspathResource("/features")
   public class CucumberTestSuite {}
```

Note that you need to specify at least the `features` attribute, to define the directory containing your feature files.

# Feature hierarchies

Serenity expects to find feature files in the `src/test/resources/features` folder by default. You can organise your feature files in a hierarchy of folders underneath this one, as shown here:

```
+ src
|-- test
|   |-- resources
|   |  |-- features
|   |  |   |-- authentication
|   |  |   |   |-- login.feature
|   |  |   |-- cart
|   |  |   |   |-- managing_the_cart.feature
|   |  |   |-- catalog
|   |  |   |   |-- browse_catalog.feature
|   |  |   |   |-- filtering_products.feature
|   |  |   |-- purchases
|   |  |   |   |-- completing_a_purchase.feature
|   |  |   |-- sales_tax
|   |  |   |   |-- calculating_sales_tax.feature
``` 

The directory structure will be used to build the Serenity requirements hierarchy, like the one shown here:

![](img/cucumber-requirements-hierarchy.png)


# Filtering test execution in Cucumber

The simplest way to control which scenarios you want to execute is to use tags and the `cucumber.filter.tags` command line option. For example, to run only scenarios or features annotated with `@smoke`, you would run the following command:
```
mvn clean verify -Dcucumber.filter.tags="@smoke"
```

You can use [Cucumber Tag Expressions](https://cucumber.io/docs/cucumber/api/#tag-expressions) to determine which scenarios to run. For example, to run only features with both the `@authentication` tag and the `@smoke` tag, you would run the following:
```
 mvn clean verify -Dcucumber.filter.tags="@authentication and @smoke"
 ```

To run scenarios with either the `@cart` or the `@catalog` tag, you could run the following:
```
 mvn clean verify -Dcucumber.filter.tags="@cart or @catalog"
 ```
# Running Cucumber scenarios with Serenity in parallel

Starting with version 3.6.0, is possible to run the Cucumber scenarios in parallel.

The following steps are necessary to activate the parallel execution: 
     
1. Add following dependencies in your application pom.xml:
```xml
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-junit-platform-engine</artifactId>
        <version>7.11.0</version>
        <scope>test</scope>
    </dependency>
    
    <dependency>
        <groupId>org.junit.platform</groupId>
        <artifactId>junit-platform-suite</artifactId>
        <version>1.9.2</version>
        <scope>test</scope>
    </dependency>
```
2. Create a file named `junit-platform.properties` under `test/resources`
```
cucumber.execution.parallel.enabled=true
cucumber.execution.parallel.config.strategy=fixed
cucumber.execution.parallel.config.fixed.parallelism=4
cucumber.execution.parallel.config.fixed.max-pool-size=4
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel
```

:::note Breaking Change in Serenity 5.0.0
The Cucumber plugin path changed from `io.cucumber.core.plugin.*` to `net.serenitybdd.cucumber.core.plugin.*` in Serenity 5.0.0. Make sure to update your configuration files.
:::
More informations about the meaning of the properties can be found in [Cucumber JUnit Platform Engine Documentation](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine)

3. Configure the classpath location of the scenarios to be executed in a Java class placed in a package under `test/java`
```java
   import org.junit.platform.suite.api.IncludeEngines;
   import org.junit.platform.suite.api.SelectClasspathResource;
   import org.junit.platform.suite.api.Suite;
   
   @Suite
   @IncludeEngines("cucumber")
   @SelectClasspathResource("/features")
   public class CucumberTestSuite {}
```


---

<!-- https://serenity-bdd.github.io/docs/junit5/junit5-tests -->

# Running Serenity BDD Tests with JUnit 5

This guide covers everything you need to know to write and run Serenity BDD tests using JUnit 5 (Jupiter), without Cucumber.

## Overview

JUnit 5 is the latest version of the popular Java testing framework. Combined with Serenity BDD, you get:

- **Modern Test Features**: Parameterized tests, nested tests, dynamic tests, and more
- **Powerful Assertions**: Built-in and third-party assertion libraries
- **Rich Reporting**: Serenity's detailed reports with screenshots and step-by-step execution details
- **Parallel Execution**: Run tests concurrently for faster feedback
- **Flexible Organization**: Tags, nested classes, and display names for better test organization

:::tip JUnit 5 Recommended
JUnit 4 is deprecated as of Serenity 5.0.0 and will be removed in Serenity 6.0.0. All new projects should use JUnit 5.
:::

## Prerequisites

- Java 17 or higher
- Maven or Gradle
- An IDE with Java support (IntelliJ IDEA, Eclipse, VS Code, etc.)

## Setting Up Dependencies

### Maven Dependencies

Add the following to your `pom.xml`:

```xml
<properties>
    <serenity.version>5.4.1</serenity.version>
    <junit.version>6.0.3</junit.version>
</properties>

<dependencies>
    <!-- Serenity JUnit 5 Integration -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-junit5</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity Screenplay (optional, but recommended) -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity WebDriver integration (for web tests) -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay-webdriver</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- JUnit 5 (Jupiter) -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- AssertJ (recommended for fluent assertions) -->
    <dependency>
        <groupId>org.assertj</groupId>
        <artifactId>assertj-core</artifactId>
        <version>3.24.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

### Gradle Dependencies

For Gradle, add to your `build.gradle`:

```groovy
dependencies {
    testImplementation "net.serenity-bdd:serenity-junit5:5.4.1"
    testImplementation "net.serenity-bdd:serenity-screenplay:5.4.1"
    testImplementation "net.serenity-bdd:serenity-screenplay-webdriver:5.4.1"

    testImplementation "org.junit.jupiter:junit-jupiter-api:6.0.3"
    testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:6.0.3"

    testImplementation "org.assertj:assertj-core:3.24.2"
}

test {
    useJUnitPlatform()
}
```

## Writing Your First Test

### Basic Test Structure

Every Serenity JUnit 5 test must be annotated with `@ExtendWith(SerenityJUnit5Extension.class)`:

```java
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
class WhenSearchingForProducts {

    @Test
    void shouldFindProductByName() {
        // Your test code here
    }

    @Test
    void shouldFilterProductsByCategory() {
        // Your test code here
    }
}
```

### Web Test Example

Here's a complete example of a web test:

```java
import net.serenitybdd.annotations.Managed;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.WebDriver;

import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
class WhenBrowsingProducts {

    @Managed(driver = "chrome", options = "headless")
    WebDriver driver;

    @Test
    void shouldDisplayProductDetails() {
        driver.get("https://example.com/products/123");

        String productTitle = driver.findElement(By.id("product-title")).getText();

        assertThat(productTitle).isEqualTo("Product Name");
    }
}
```

### Using Step Libraries

For better organization, use Serenity step libraries:

```java
import net.serenitybdd.annotations.Steps;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
class WhenManagingShoppingCart {

    @Steps
    NavigationSteps navigation;

    @Steps
    ProductSteps products;

    @Steps
    CartSteps cart;

    @Test
    void shouldAddProductToCart() {
        navigation.openHomePage();
        products.searchFor("laptop");
        products.selectFirstProduct();
        cart.addToCart();

        cart.shouldContain(1, "items");
    }
}
```

## Test Lifecycle

### Method-Level Lifecycle

Use JUnit 5 lifecycle annotations:

```java
import org.junit.jupiter.api.*;

@ExtendWith(SerenityJUnit5Extension.class)
class ProductTests {

    @BeforeEach
    void setUp() {
        // Runs before each test method
        System.out.println("Setting up test");
    }

    @AfterEach
    void tearDown() {
        // Runs after each test method
        System.out.println("Cleaning up test");
    }

    @BeforeAll
    static void setUpClass() {
        // Runs once before all tests in this class
        System.out.println("Setting up test class");
    }

    @AfterAll
    static void tearDownClass() {
        // Runs once after all tests in this class
        System.out.println("Cleaning up test class");
    }

    @Test
    void test1() {
        // Test code
    }

    @Test
    void test2() {
        // Test code
    }
}
```

### Execution Order

```
setUpClass()
  setUp()
    test1()
  tearDown()
  setUp()
    test2()
  tearDown()
tearDownClass()
```

## Display Names and Organization

### Custom Display Names

Make test names more readable in reports:

```java
import org.junit.jupiter.api.DisplayName;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Shopping Cart Management")
class ShoppingCartTests {

    @Test
    @DisplayName("Should add product to empty cart")
    void addToEmptyCart() {
        // Test code
    }

    @Test
    @DisplayName("Should update quantity of existing product")
    void updateQuantity() {
        // Test code
    }

    @Test
    @DisplayName("Should remove product from cart")
    void removeProduct() {
        // Test code
    }
}
```

### Organising Tests with @Feature and @Story

You can use the `@Feature` and `@Story` annotations to organise your tests into a requirements hierarchy in the Serenity reports. This gives you explicit control over how tests appear in the Living Documentation, independent of the package structure:

```java
import net.serenitybdd.annotations.Feature;
import net.serenitybdd.annotations.Story;

@ExtendWith(SerenityJUnit5Extension.class)
@Feature("Shopping Cart")
@Story("Add item to cart")
@DisplayName("When adding items to the shopping cart")
class WhenAddingItemsTest {

    @Test
    @DisplayName("Should add a single item")
    void addSingleItem() { /* ... */ }

    @Test
    @DisplayName("Should update quantity for duplicate items")
    void updateQuantityForDuplicates() { /* ... */ }
}
```

When `@Story` is not present, the `@DisplayName` value is used as the story name in the requirements hierarchy. This means you can write:

```java
@Feature("Shopping Cart")
@DisplayName("Add item to cart")  // Used as the story name
class WhenAddingItemsTest { /* ... */ }
```

See [Annotation-Based Requirements](/docs/guide/annotation-requirements) for a comprehensive guide covering the full `@Epic` > `@Feature` > `@Story` hierarchy, inheritance, and migration from class-based annotations.

### Nested Tests

Organize related tests with `@Nested`:

```java
import org.junit.jupiter.api.Nested;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("User Authentication")
class AuthenticationTests {

    @Nested
    @DisplayName("When logging in")
    class Login {

        @Test
        @DisplayName("Should succeed with valid credentials")
        void validCredentials() {
            // Test code
        }

        @Test
        @DisplayName("Should fail with invalid password")
        void invalidPassword() {
            // Test code
        }

        @Test
        @DisplayName("Should fail with non-existent user")
        void nonExistentUser() {
            // Test code
        }
    }

    @Nested
    @DisplayName("When logging out")
    class Logout {

        @Test
        @DisplayName("Should clear session")
        void clearSession() {
            // Test code
        }

        @Test
        @DisplayName("Should redirect to login page")
        void redirectToLogin() {
            // Test code
        }
    }
}
```

#### Nested Classes and Requirements Annotations

`@Nested` classes inherit `@Epic`, `@Feature`, and `@Story` annotations from their enclosing class. This lets you define the feature once on the outer class and assign individual stories to each nested class:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@Feature("User Authentication")
class AuthenticationTests {

    @Nested
    @Story("Login")
    class WhenLoggingIn {
        @Test
        void shouldSucceedWithValidCredentials() { /* ... */ }
    }

    @Nested
    @Story("Logout")
    class WhenLoggingOut {
        @Test
        void shouldClearSession() { /* ... */ }
    }
}
```

This produces the requirements hierarchy:

```
User Authentication (feature)
├── Login (story)
│   └── Should succeed with valid credentials
└── Logout (story)
    └── Should clear session
```

See [Annotation-Based Requirements](/docs/guide/annotation-requirements#inheriting-annotations-in-junit-5-nested-classes) for the full details on annotation inheritance with nested classes.

## Parameterized Tests

### Simple Parameterized Tests

```java
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;

@ExtendWith(SerenityJUnit5Extension.class)
class SearchTests {

    @Steps
    SearchSteps search;

    @ParameterizedTest
    @ValueSource(strings = {"laptop", "phone", "tablet"})
    @DisplayName("Should find products for search term: {0}")
    void shouldFindProducts(String searchTerm) {
        search.searchFor(searchTerm);
        search.shouldSeeResults();
    }
}
```

### CSV Source

```java
import org.junit.jupiter.params.provider.CsvSource;

@ParameterizedTest
@CsvSource({
    "admin,     admin123,  Dashboard",
    "user,      user123,   User Home",
    "guest,     guest123,  Guest Portal"
})
@DisplayName("Should login as {0} and see {2}")
void shouldLoginSuccessfully(String username, String password, String expectedPage) {
    login.as(username, password);
    navigation.shouldBeOn(expectedPage);
}
```

### Method Source

```java
import org.junit.jupiter.params.provider.MethodSource;
import java.util.stream.Stream;

@ParameterizedTest
@MethodSource("provideTestData")
@DisplayName("Should process order for {0}")
void shouldProcessOrder(Order order) {
    checkout.process(order);
    checkout.shouldShowConfirmation();
}

static Stream<Order> provideTestData() {
    return Stream.of(
        new Order("Product1", 2, 29.99),
        new Order("Product2", 1, 49.99),
        new Order("Product3", 5, 9.99)
    );
}
```

## Tags and Filtering

### Tagging Tests

Use `@Tag` to categorize tests:

```java
import org.junit.jupiter.api.Tag;

@ExtendWith(SerenityJUnit5Extension.class)
class ProductTests {

    @Test
    @Tag("smoke")
    @Tag("fast")
    void quickSanityCheck() {
        // Fast smoke test
    }

    @Test
    @Tag("regression")
    @Tag("slow")
    void comprehensiveTest() {
        // Full regression test
    }

    @Test
    @Tag("wip")
    void workInProgress() {
        // Test under development
    }
}
```

### Running Tagged Tests

**Maven:**
```bash
# Run only smoke tests
mvn test -Dgroups=smoke

# Run smoke OR regression
mvn test -Dgroups="smoke | regression"

# Run smoke AND fast
mvn test -Dgroups="smoke & fast"

# Exclude wip tests
mvn test -DexcludedGroups=wip
```

**junit-platform.properties:**
```properties
junit.jupiter.includeTags=smoke
junit.jupiter.excludeTags=wip,slow
```

## Conditional Test Execution

### OS-Specific Tests

```java
import org.junit.jupiter.api.condition.*;

@Test
@EnabledOnOs(OS.WINDOWS)
void runOnlyOnWindows() {
    // Windows-specific test
}

@Test
@DisabledOnOs(OS.MAC)
void dontRunOnMac() {
    // Test disabled on macOS
}
```

### Java Version-Specific

```java
@Test
@EnabledOnJre(JRE.JAVA_17)
void runOnlyOnJava17() {
    // Java 17 specific test
}

@Test
@EnabledForJreRange(min = JRE.JAVA_17, max = JRE.JAVA_21)
void runOnJava17To21() {
    // Modern Java versions
}
```

### Custom Conditions

```java
@Test
@EnabledIf("isProductionEnvironment")
void runOnlyInProduction() {
    // Production-only test
}

boolean isProductionEnvironment() {
    return System.getProperty("env", "dev").equals("prod");
}
```

## Assertions

### JUnit 5 Assertions

```java
import static org.junit.jupiter.api.Assertions.*;

@Test
void demonstrateAssertions() {
    // Basic assertions
    assertEquals(expected, actual);
    assertTrue(condition);
    assertFalse(condition);
    assertNull(object);
    assertNotNull(object);

    // Array assertions
    assertArrayEquals(expectedArray, actualArray);

    // Exception assertions
    assertThrows(IllegalArgumentException.class, () -> {
        // Code that should throw exception
    });

    // Timeout assertions
    assertTimeout(Duration.ofSeconds(2), () -> {
        // Code that should complete within 2 seconds
    });

    // Grouped assertions
    assertAll("User validation",
        () -> assertEquals("John", user.getFirstName()),
        () -> assertEquals("Doe", user.getLastName()),
        () -> assertTrue(user.isActive())
    );
}
```

### AssertJ (Recommended)

```java
import static org.assertj.core.api.Assertions.*;

@Test
void demonstrateAssertJ() {
    // Fluent assertions
    assertThat(actual).isEqualTo(expected);
    assertThat(list).hasSize(3)
                    .contains("item1", "item2")
                    .doesNotContain("item3");

    // String assertions
    assertThat(text).startsWith("Hello")
                    .endsWith("World")
                    .contains("Test");

    // Exception assertions
    assertThatThrownBy(() -> methodThatThrows())
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessage("Invalid input");

    // Soft assertions (continue even after failures)
    SoftAssertions softly = new SoftAssertions();
    softly.assertThat(user.getName()).isEqualTo("John");
    softly.assertThat(user.getAge()).isGreaterThan(18);
    softly.assertAll();
}
```

## Parallel Execution

See the dedicated [Parallel Execution Guide](parallel-execution) for comprehensive coverage.

Quick example in `junit-platform.properties`:

```properties
# Enable parallel execution
junit.jupiter.execution.parallel.enabled=true

# Run test classes in parallel
junit.jupiter.execution.parallel.mode.default=concurrent

# Run test methods in same class sequentially
junit.jupiter.execution.parallel.mode.classes.default=concurrent

# Use dynamic strategy
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=1.0
```

## Best Practices

### 1. Test Naming

```java
// Good - Describes behavior
@Test
void shouldCalculateDiscountForRegularCustomer() { }

// Better - Even more descriptive
@Test
@DisplayName("Should apply 10% discount for customers with 5+ orders")
void regularCustomerDiscount() { }

// Bad - Unclear purpose
@Test
void test1() { }
```

### 2. Test Organization

```java
// Good - Organized by feature/behavior
@Nested
@DisplayName("When user is logged in")
class LoggedIn {

    @Nested
    @DisplayName("And viewing their profile")
    class ViewingProfile {

        @Test
        @DisplayName("Should see personal information")
        void seesPersonalInfo() { }

        @Test
        @DisplayName("Should be able to edit details")
        void canEditDetails() { }
    }
}
```

### 3. Use Step Libraries

```java
// Good - Delegating to step libraries
@Test
void shouldCompleteCheckout() {
    cart.addProduct("laptop");
    checkout.proceedToCheckout();
    payment.payWithCreditCard("4111111111111111");
    confirmation.shouldShowOrderNumber();
}

// Bad - Low-level implementation in test
@Test
void checkout() {
    driver.findElement(By.id("add-to-cart")).click();
    driver.findElement(By.id("checkout-button")).click();
    // ... many more lines
}
```

### 4. Clean Test Data

```java
@ExtendWith(SerenityJUnit5Extension.class)
class OrderTests {

    private String orderId;

    @BeforeEach
    void createTestData() {
        orderId = testDataFactory.createOrder();
    }

    @AfterEach
    void cleanupTestData() {
        testDataFactory.deleteOrder(orderId);
    }

    @Test
    void shouldProcessOrder() {
        // Test uses orderId
    }
}
```

### 5. Avoid Test Interdependence

```java
// Bad - Tests depend on execution order
@Test
@Order(1)
void createUser() {
    userId = userService.create("John");
}

@Test
@Order(2)
void updateUser() {
    userService.update(userId, "Jane"); // Depends on test 1
}

// Good - Each test is independent
@Test
void createUser() {
    String userId = userService.create("John");
    assertThat(userId).isNotNull();
}

@Test
void updateUser() {
    String userId = userService.create("John"); // Create own data
    userService.update(userId, "Jane");
    assertThat(userService.get(userId).getName()).isEqualTo("Jane");
}
```

## Configuration

### Maven Surefire/Failsafe

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-failsafe-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <includes>
                    <include>**/*Test.java</include>
                    <include>**/*Tests.java</include>
                    <include>**/*TestCase.java</include>
                </includes>
                <systemPropertyVariables>
                    <webdriver.driver>${webdriver.driver}</webdriver.driver>
                </systemPropertyVariables>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>integration-test</goal>
                        <goal>verify</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

### Serenity Properties

Create `serenity.properties` in `src/test/resources`:

```properties
# WebDriver configuration
webdriver.driver=chrome
webdriver.chrome.driver=path/to/chromedriver

# Timeouts
webdriver.timeouts.implicitlywait=2000
webdriver.wait.for.timeout=10000

# Reporting
serenity.project.name=My Project
serenity.test.root=net.example

# Screenshots
serenity.take.screenshots=FOR_FAILURES
serenity.take.screenshots.for.tasks=BEFORE_AND_AFTER_EACH_STEP
```

## Troubleshooting

### Common Issues

**1. "No tests found"**
- Ensure test class has `@ExtendWith(SerenityJUnit5Extension.class)`
- Check test methods have `@Test` from `org.junit.jupiter.api`
- Verify Maven/Gradle is configured to run JUnit 5 tests

**2. "Multiple WebDriver instances"**
- Use `@Managed` WebDriver - Serenity manages lifecycle
- Don't create WebDriver instances manually
- Ensure proper cleanup in `@AfterEach` if needed

**3. "Tests fail in parallel but pass individually"**
- Check for shared state between tests
- Ensure test data is isolated
- Review WebDriver management

## Next Steps

- Explore [Parallel Execution](parallel-execution) for faster test runs
- Learn about [Screenplay Pattern](/docs/screenplay/screenplay_fundamentals) for better test design
- Review [Serenity Reports](/docs/reporting/the_serenity_reports) documentation
- Check out [WebDriver Integration](/docs/guide/driver_config) for web testing

## Additional Resources

- [JUnit 5 User Guide](https://junit.org/junit5/docs/current/user-guide/)
- [Serenity BDD Official Site](https://serenity-bdd.info)
- [AssertJ Documentation](https://assertj.github.io/doc/)
- [Example Project](https://github.com/serenity-bdd/serenity-junit-screenplay-starter)


---

<!-- https://serenity-bdd.github.io/docs/junit5/parallel-execution -->

# Running JUnit 5 Serenity Tests in Parallel

Running JUnit 5 tests in parallel can significantly reduce test execution time. This guide explains how to configure and optimize parallel execution for Serenity BDD tests using JUnit 5.

## Overview

JUnit 5 (Jupiter) has built-in support for parallel test execution. When combined with Serenity BDD, you can run test methods and test classes concurrently, taking advantage of multi-core processors.

:::tip Parallel Execution Benefits
On a machine with 8 cores, parallel execution can reduce test time from 30 minutes to 5-8 minutes or less.
:::

## Prerequisites

- JUnit 5 (Jupiter)
- Serenity BDD 3.6.0 or higher
- Thread-safe test code
- Sufficient system resources (CPU, RAM)

## Basic Configuration

### Step 1: Enable Parallel Execution

Create or update `junit-platform.properties` in `src/test/resources`:

```properties
# Enable parallel execution
junit.jupiter.execution.parallel.enabled=true
```

### Step 2: Configure Execution Mode

```properties
# Run test classes in parallel
junit.jupiter.execution.parallel.mode.default=concurrent

# Run test classes in parallel
junit.jupiter.execution.parallel.mode.classes.default=concurrent
```

### Step 3: Configure Execution Strategy

```properties
# Use dynamic strategy (recommended)
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=1.0
```

## Execution Modes

### Concurrent Mode

Tests run in parallel:

```properties
junit.jupiter.execution.parallel.mode.default=concurrent
junit.jupiter.execution.parallel.mode.classes.default=concurrent
```

### Same Thread Mode

Tests run sequentially:

```properties
junit.jupiter.execution.parallel.mode.default=same_thread
junit.jupiter.execution.parallel.mode.classes.default=same_thread
```

### Mixed Mode

Run classes in parallel but methods within a class sequentially:

```properties
# Classes in parallel
junit.jupiter.execution.parallel.mode.classes.default=concurrent

# Methods in same class run sequentially
junit.jupiter.execution.parallel.mode.default=same_thread
```

## Execution Strategies

### Dynamic Strategy (Recommended)

Automatically determines thread count based on available processors:

```properties
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=1.0
```

**Factor calculation:** `threads = processors × factor`

**Examples** (on an 8-core machine):
- Factor `1.0` = 8 threads (recommended)
- Factor `0.5` = 4 threads
- Factor `2.0` = 16 threads

### Fixed Strategy

Uses a specified number of threads:

```properties
junit.jupiter.execution.parallel.config.strategy=fixed
junit.jupiter.execution.parallel.config.fixed.parallelism=4
```

**Use when:**
- You need consistent thread counts
- Running on shared CI/CD infrastructure
- Debugging parallel execution issues

### Custom Strategy

Implement your own strategy:

```properties
junit.jupiter.execution.parallel.config.strategy=custom
junit.jupiter.execution.parallel.config.custom.class=com.example.MyParallelStrategy
```

## Controlling Parallelism at Class/Method Level

### Per-Class Configuration

Use `@Execution` annotation to control parallelism:

```java
import org.junit.jupiter.api.parallel.Execution;
import org.junit.jupiter.api.parallel.ExecutionMode;

@ExtendWith(SerenityJUnit5Extension.class)
@Execution(ExecutionMode.CONCURRENT)  // Run this class's methods in parallel
class FastTests {

    @Test
    void test1() { }

    @Test
    void test2() { }

    @Test
    void test3() { }
}
```

### Force Sequential Execution

```java
@ExtendWith(SerenityJUnit5Extension.class)
@Execution(ExecutionMode.SAME_THREAD)  // Run sequentially
class DatabaseMigrationTests {

    @Test
    void migration1() { }

    @Test
    void migration2() { }  // Must run after migration1
}
```

### Method-Level Control

```java
@ExtendWith(SerenityJUnit5Extension.class)
class MixedTests {

    @Test
    @Execution(ExecutionMode.CONCURRENT)
    void canRunInParallel() { }

    @Test
    @Execution(ExecutionMode.SAME_THREAD)
    void mustRunSequentially() { }
}
```

## Resource Locks

Prevent concurrent access to shared resources:

```java
import org.junit.jupiter.api.parallel.ResourceLock;

@ExtendWith(SerenityJUnit5Extension.class)
class SharedResourceTests {

    @Test
    @ResourceLock("database")
    void accessDatabase1() {
        // Exclusive access to database
    }

    @Test
    @ResourceLock("database")
    void accessDatabase2() {
        // Will wait for accessDatabase1 to complete
    }

    @Test
    @ResourceLock(value = "database", mode = READ)
    void readFromDatabase() {
        // Read-only access - can run concurrently with other reads
    }
}
```

### Common Resource Locks

```java
import static org.junit.jupiter.api.parallel.Resources.*;

@Test
@ResourceLock(SYSTEM_PROPERTIES)
void modifiesSystemProperties() { }

@Test
@ResourceLock(SYSTEM_OUT)
void writesToSystemOut() { }

@Test
@ResourceLock("my-custom-resource")
void accessesCustomResource() { }
```

## Thread Safety with Serenity

### WebDriver Management

Serenity's `@Managed` WebDriver is automatically thread-safe:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@Execution(ExecutionMode.CONCURRENT)
class WebTests {

    @Managed(driver = "chrome", options = "headless")
    WebDriver driver;  // Each thread gets its own instance

    @Test
    void test1() {
        driver.get("https://example.com");
        // Thread-safe
    }

    @Test
    void test2() {
        driver.get("https://example.com/other");
        // Independent WebDriver instance
    }
}
```

### Step Libraries

Step libraries are thread-safe when properly used:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@Execution(ExecutionMode.CONCURRENT)
class CheckoutTests {

    @Steps
    CartSteps cart;  // Thread-safe - instance per thread

    @Test
    void addToCart() {
        cart.addProduct("Product1");
    }

    @Test
    void removeFromCart() {
        cart.addProduct("Product2");
        cart.removeProduct("Product2");
    }
}
```

### Avoid Shared Mutable State

```java
// ❌ BAD - Not thread-safe
@ExtendWith(SerenityJUnit5Extension.class)
@Execution(ExecutionMode.CONCURRENT)
class BadTests {

    private String sharedData;  // Shared mutable state!

    @Test
    void test1() {
        sharedData = "test1";  // Race condition!
    }

    @Test
    void test2() {
        sharedData = "test2";  // Race condition!
    }
}

// ✅ GOOD - Thread-safe
@ExtendWith(SerenityJUnit5Extension.class)
@Execution(ExecutionMode.CONCURRENT)
class GoodTests {

    @Test
    void test1() {
        String localData = "test1";  // Local variable - thread-safe
        // Use localData
    }

    @Test
    void test2() {
        String localData = "test2";  // Independent
        // Use localData
    }
}
```

## Complete Configuration Example

### Comprehensive junit-platform.properties

```properties
# ==========================================
# Parallel Execution
# ==========================================
junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=concurrent
junit.jupiter.execution.parallel.mode.classes.default=concurrent

# ==========================================
# Execution Strategy
# ==========================================
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=1.0

# Alternative: Fixed strategy
# junit.jupiter.execution.parallel.config.strategy=fixed
# junit.jupiter.execution.parallel.config.fixed.parallelism=4
# junit.jupiter.execution.parallel.config.fixed.max-pool-size=8

# ==========================================
# Test Instance Lifecycle
# ==========================================
junit.jupiter.testinstance.lifecycle.default=per_method

# ==========================================
# Test Discovery
# ==========================================
junit.jupiter.testclass.order.default=org.junit.jupiter.api.ClassOrderer$Random

# ==========================================
# Display Names
# ==========================================
junit.jupiter.displayname.generator.default=org.junit.jupiter.api.DisplayNameGenerator$ReplaceUnderscores
```

## Maven Configuration

### Failsafe Plugin

Configure Maven Failsafe plugin for parallel execution:

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
        <!-- Enable JUnit 5 -->
        <includes>
            <include>**/*Test.java</include>
            <include>**/*Tests.java</include>
        </includes>

        <!-- System properties -->
        <systemPropertyVariables>
            <webdriver.driver>${webdriver.driver}</webdriver.driver>
            <environment>${environment}</environment>
        </systemPropertyVariables>

        <!-- Increase memory for parallel execution -->
        <argLine>-Xmx2g</argLine>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

### Running from Command Line

```bash
# Run all tests in parallel
mvn clean verify

# Override parallelism
mvn clean verify -Djunit.jupiter.execution.parallel.config.fixed.parallelism=8

# Disable parallel execution
mvn clean verify -Djunit.jupiter.execution.parallel.enabled=false
```

## Gradle Configuration

```groovy
test {
    useJUnitPlatform()

    // Enable parallel execution
    maxParallelForks = Runtime.runtime.availableProcessors()

    // Increase memory
    minHeapSize = "512m"
    maxHeapSize = "2g"

    // System properties
    systemProperty 'junit.jupiter.execution.parallel.enabled', 'true'
    systemProperty 'junit.jupiter.execution.parallel.config.strategy', 'dynamic'
    systemProperty 'junit.jupiter.execution.parallel.config.dynamic.factor', '1.0'
}
```

## Performance Optimization

### 1. Choose the Right Strategy

**Small test suites** (&lt;30 tests):
```properties
junit.jupiter.execution.parallel.config.strategy=fixed
junit.jupiter.execution.parallel.config.fixed.parallelism=2
```

**Medium test suites** (30-100 tests):
```properties
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=1.0
```

**Large test suites** (&gt;100 tests):
```properties
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=0.75
```

### 2. Monitor Resource Usage

```bash
# Monitor while tests run
top
htop
jconsole
```

Watch for:
- **CPU**: Should be near 100% utilization
- **Memory**: Each browser instance uses ~200-500MB RAM
- **Threads**: Should match your parallelism setting

### 3. Optimize Test Design

```java
// ✅ GOOD - Fast, focused tests
@Test
void shouldCalculateTotal() {
    // No external dependencies, runs quickly
    assertThat(calculator.add(2, 3)).isEqualTo(5);
}

// ⚠️ SLOW - Consider optimization
@Test
void shouldProcessLargeDataset() {
    // Process 10000 records - consider using smaller dataset
}
```

### 4. Balance Thread Count

Too few threads:
```properties
# Underutilizing CPU
junit.jupiter.execution.parallel.config.dynamic.factor=0.25
```

Too many threads:
```properties
# May cause resource exhaustion
junit.jupiter.execution.parallel.config.dynamic.factor=4.0
```

Optimal:
```properties
# Matches CPU cores
junit.jupiter.execution.parallel.config.dynamic.factor=1.0
```

## Debugging Parallel Tests

### Temporarily Disable Parallelism

```properties
junit.jupiter.execution.parallel.enabled=false
```

Or via command line:
```bash
mvn verify -Djunit.jupiter.execution.parallel.enabled=false
```

### Run Single Test Class

```bash
mvn test -Dtest=MyTestClass
```

### Enable Verbose Logging

Add to `junit-platform.properties`:
```properties
# Show which thread runs which test
junit.platform.output.capture.stdout=true
junit.platform.output.capture.stderr=true
```

In your test:
```java
@BeforeEach
void logThread() {
    System.out.println("Running on: " + Thread.currentThread().getName());
}
```

## Common Issues and Solutions

### Issue 1: Flaky Tests

**Symptoms:** Tests pass individually but fail in parallel

**Solutions:**
- Check for shared mutable state
- Verify test data isolation
- Review resource locking
- Add proper synchronization

```java
// Problem: Shared state
private static int counter = 0;  // ❌ Not thread-safe

@Test
void incrementCounter() {
    counter++;  // Race condition
}

// Solution: Use atomic types or local variables
private static AtomicInteger counter = new AtomicInteger(0);  // ✅ Thread-safe

@Test
void incrementCounter() {
    counter.incrementAndGet();
}
```

### Issue 2: Resource Exhaustion

**Symptoms:** Tests slow down or fail after some time

**Solutions:**
- Reduce thread count
- Increase JVM heap size
- Check for resource leaks
- Monitor system resources

```xml
<!-- Increase heap size -->
<argLine>-Xmx4g</argLine>
```

### Issue 3: WebDriver Issues

**Symptoms:** Browser instances multiply or don't close

**Solutions:**
- Use `@Managed` WebDriver (Serenity handles lifecycle)
- Ensure proper cleanup in `@AfterEach`
- Limit concurrent browser instances

```java
// ✅ Serenity manages lifecycle
@Managed
WebDriver driver;

// ❌ Don't manage manually in parallel tests
WebDriver driver = new ChromeDriver();  // Memory leak risk
```

### Issue 4: Database Locks

**Symptoms:** Tests timeout waiting for database

**Solutions:**
- Use resource locks
- Isolate test data
- Use in-memory database for tests

```java
@Test
@ResourceLock("database")
void modifiesDatabase() {
    // Exclusive database access
}
```

## Best Practices

### 1. Start Small

Begin with 2-4 threads and gradually increase:

```properties
junit.jupiter.execution.parallel.config.strategy=fixed
junit.jupiter.execution.parallel.config.fixed.parallelism=2
```

### 2. Isolate Test Data

```java
@ExtendWith(SerenityJUnit5Extension.class)
class UserTests {

    @Test
    void createUser() {
        String uniqueId = UUID.randomUUID().toString();
        User user = createTestUser("user_" + uniqueId);
        // Test with unique user
    }
}
```

### 3. Use Tags for Selective Parallelism

```java
@Test
@Tag("parallel")
void canRunInParallel() { }

@Test
@Tag("serial")
@Execution(ExecutionMode.SAME_THREAD)
void mustRunSequentially() { }
```

```properties
# Run only parallel tests
junit.jupiter.includeTags=parallel
```

### 4. Clean Up Resources

```java
@AfterEach
void cleanup() {
    // Clean up test data
    testDataService.deleteTestData(testId);
}
```

### 5. Document Thread Safety

```java
/**
 * Tests in this class modify global application state
 * and must run sequentially.
 */
@Execution(ExecutionMode.SAME_THREAD)
class GlobalStateTests {
    // ...
}
```

## Measuring Performance

### Before Parallel Execution
```
Total tests: 150
Execution time: 25 minutes
```

### After Parallel Execution (8 threads)
```
Total tests: 150
Execution time: 4 minutes
Speedup: 6.25x
Efficiency: 78%
```

**Calculate metrics:**
```
Speedup = Sequential Time / Parallel Time
Efficiency = Speedup / Number of Threads × 100%
```

## Next Steps

- Return to the main [JUnit 5 Guide](junit5-tests)
- Learn about [Test Organization](junit5-tests#display-names-and-organization)
- Review [Best Practices](junit5-tests#best-practices)
- Explore [Serenity Reports](/docs/reporting/the_serenity_reports)

## Additional Resources

- [JUnit 5 Parallel Execution Docs](https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution)
- [Serenity BDD Performance Tips](https://serenity-bdd.info)
- [Java Concurrency in Practice](https://jcip.net/)


---

<!-- https://serenity-bdd.github.io/docs/cucumber/cucumber-junit5 -->

# Running Cucumber Scenarios with Serenity BDD and JUnit 5

Serenity BDD provides seamless integration with Cucumber, allowing you to write executable specifications in Gherkin and run them using JUnit 5. This guide covers everything you need to know to use Cucumber with Serenity BDD and JUnit 5 effectively.

## Overview

Cucumber is a popular BDD (Behavior-Driven Development) tool that allows you to write test scenarios in plain language using the Gherkin syntax. When combined with Serenity BDD and JUnit 5, you get:

- **Living Documentation**: Serenity generates rich, narrative reports from your Cucumber scenarios
- **Modern Test Execution**: JUnit 5's powerful platform for running tests
- **Parallel Execution**: Run scenarios in parallel for faster test execution
- **Rich Reporting**: Detailed test reports with screenshots, stack traces, and more

## Prerequisites

Before you start, ensure you have:
- Java 17 or higher
- Maven or Gradle
- An IDE with Java support (IntelliJ IDEA, Eclipse, VS Code, etc.)

## Setting Up Dependencies

### Maven Dependencies

Add the following dependencies to your `pom.xml`:

```xml
<properties>
    <serenity.version>5.4.1</serenity.version>
    <cucumber.version>7.34.2</cucumber.version>
    <junit.version>6.0.3</junit.version>
</properties>

<dependencies>
    <!-- Serenity Cucumber Integration -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-cucumber</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Cucumber JUnit Platform Engine -->
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-junit-platform-engine</artifactId>
        <version>${cucumber.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- JUnit Platform Suite -->
    <dependency>
        <groupId>org.junit.platform</groupId>
        <artifactId>junit-platform-suite</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

### Gradle Dependencies

For Gradle, add to your `build.gradle`:

```groovy
dependencies {
    testImplementation "net.serenity-bdd:serenity-cucumber:5.4.1"
    testImplementation "io.cucumber:cucumber-junit-platform-engine:7.34.2"
    testImplementation "org.junit.platform:junit-platform-suite:6.0.3"
}
```

## Creating a Basic Test Runner

The simplest way to run Cucumber scenarios with JUnit 5 is to create a test suite class:

```java
import org.junit.platform.suite.api.*;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
class CucumberTestSuite {
}
```

This minimal configuration:
- `@Suite` - Marks this as a JUnit Platform Suite
- `@IncludeEngines("cucumber")` - Tells JUnit to use the Cucumber engine
- `@SelectClasspathResource("features")` - Points to the directory containing your feature files

## Configuring the Serenity Reporter

:::warning Breaking Change in Serenity 5.0.0
The Serenity Cucumber plugin path changed in version 5.0.0 from `io.cucumber.core.plugin.*` to `net.serenitybdd.cucumber.core.plugin.*`
:::

To generate Serenity reports, you must configure the Serenity reporter plugin. Add this to your test suite:

```java
import org.junit.platform.suite.api.*;
import static io.cucumber.junit.platform.engine.Constants.PLUGIN_PROPERTY_NAME;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"
)
class CucumberTestSuite {
}
```

The `SerenityReporterParallel` plugin is thread-safe and recommended for all scenarios, even if you're not running tests in parallel.

## Configuration Options

### Using @ConfigurationParameter Annotations

You can configure various Cucumber options using `@ConfigurationParameter` annotations. Here are the most commonly used:

#### Specifying Step Definition Packages

```java
import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;

@ConfigurationParameter(
    key = GLUE_PROPERTY_NAME,
    value = "com.example.stepdefinitions"
)
```

#### Filtering by Tags

```java
import static io.cucumber.junit.platform.engine.Constants.FILTER_TAGS_PROPERTY_NAME;

@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "@smoke and not @wip"
)
```

#### Specifying Feature Paths

```java
import static io.cucumber.junit.platform.engine.Constants.FEATURES_PROPERTY_NAME;

@ConfigurationParameter(
    key = FEATURES_PROPERTY_NAME,
    value = "src/test/resources/features"
)
```

#### Complete Example

```java
import org.junit.platform.suite.api.*;
import static io.cucumber.junit.platform.engine.Constants.*;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"
)
@ConfigurationParameter(
    key = GLUE_PROPERTY_NAME,
    value = "com.example.stepdefinitions"
)
@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "@smoke"
)
class SmokeTestSuite {
}
```

### Using junit-platform.properties

Alternatively, you can configure Cucumber options in a `junit-platform.properties` file located in `src/test/resources`:

```properties
# Enable Cucumber
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel
cucumber.glue=com.example.stepdefinitions
cucumber.filter.tags=@smoke
cucumber.features=src/test/resources/features

# Scenario execution order
cucumber.execution.order=random

# Plugin output
cucumber.plugin=pretty,html:target/cucumber-reports/cucumber.html
```

:::tip When to Use Each Approach
- Use `@ConfigurationParameter` for **suite-specific** configuration (e.g., different test suites for smoke, regression, etc.)
- Use `junit-platform.properties` for **project-wide** default configuration
- Annotations override properties file settings
:::

## Organizing Feature Files

### Directory Structure

Serenity expects feature files in `src/test/resources/features` by default. Organize them hierarchically by feature area:

```
src/test/resources/features/
├── authentication/
│   ├── login.feature
│   └── logout.feature
├── shopping/
│   ├── add_to_cart.feature
│   ├── checkout.feature
│   └── payment.feature
└── search/
    ├── basic_search.feature
    └── advanced_filters.feature
```

This hierarchy will be reflected in your Serenity reports, creating a clear requirements structure.

### Feature File Example

```gherkin
@shopping @checkout
Feature: Checkout Process
  As a customer
  I want to complete my purchase
  So that I can receive my items

  Background:
    Given I have items in my cart

  @happy-path @smoke
  Scenario: Successful checkout with credit card
    When I proceed to checkout
    And I enter valid shipping information
    And I pay with a valid credit card
    Then I should see an order confirmation
    And I should receive a confirmation email

  @edge-case
  Scenario: Checkout with invalid credit card
    When I proceed to checkout
    And I enter valid shipping information
    And I pay with an invalid credit card
    Then I should see a payment error message
    And my order should not be placed
```

## Writing Step Definitions

Step definitions connect your Gherkin scenarios to Java code:

```java
package com.example.stepdefinitions;

import io.cucumber.java.en.*;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.actors.OnStage;

public class CheckoutStepDefinitions {

    @Given("{actor} has items in the cart")
    public void hasItemsInCart(Actor actor) {
        actor.attemptsTo(
            // Your implementation here
        );
    }

    @When("{actor} proceeds to checkout")
    public void proceedsToCheckout(Actor actor) {
        actor.attemptsTo(
            // Your implementation here
        );
    }

    @Then("{actor} should see an order confirmation")
    public void shouldSeeOrderConfirmation(Actor actor) {
        actor.should(
            // Your assertions here
        );
    }
}
```

### Step Definition Best Practices

1. **Keep steps reusable** - Write generic steps that can be used in multiple scenarios
2. **Use the Screenplay pattern** - For better maintainability and readability
3. **Avoid step interdependence** - Each step should be independent
4. **Use parameters** - Make steps flexible with Cucumber expressions

## Filtering Scenarios with Tags

### Tag Expressions

Cucumber supports powerful tag expressions for filtering scenarios:

```bash
# Run scenarios with @smoke tag
mvn clean verify -Dcucumber.filter.tags="@smoke"

# Run scenarios with both tags
mvn clean verify -Dcucumber.filter.tags="@smoke and @regression"

# Run scenarios with either tag
mvn clean verify -Dcucumber.filter.tags="@smoke or @regression"

# Exclude scenarios
mvn clean verify -Dcucumber.filter.tags="not @wip"

# Complex expressions
mvn clean verify -Dcucumber.filter.tags="(@smoke or @regression) and not @slow"
```

:::caution Gradle ignores command-line `-D` options in the test JVM
`gradle test -Dcucumber.filter.tags=@smoke` runs every scenario, because Gradle does not pass `-D` options to the JVM that runs the tests. Forward them in `build.gradle`:

```groovy
test {
    systemProperties System.properties.findAll { k, v -> k.toString().startsWith('cucumber.') }
}
```
:::

:::caution Name the runner class so Maven runs it
Maven's test plugin only runs classes named `*Test`, `*Tests`, `Test*` or `*TestCase`. A runner called `CucumberSuite` or `CucumberTestSuite` is skipped without a warning, and the build ends with `Results: 0 tests`. Call it `RunCucumberTests` (or similar), or add the name to the `includes` of the surefire plugin.
:::


### In Code

```java
@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "(@smoke or @regression) and not @wip"
)
```

### In Properties File

```properties
cucumber.filter.tags=(@smoke or @regression) and not @wip
```

## Running Scenarios in Parallel

See the dedicated [Parallel Execution](parallel-execution) guide for detailed information on running Cucumber scenarios in parallel.

Quick example:

**junit-platform.properties:**
```properties
cucumber.execution.parallel.enabled=true
cucumber.execution.parallel.config.strategy=dynamic
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel
```

## Cucumber Hooks

Cucumber hooks allow you to run code before or after scenarios:

```java
package com.example.hooks;

import io.cucumber.java.*;

public class CucumberHooks {

    @Before
    public void beforeScenario(Scenario scenario) {
        System.out.println("Starting scenario: " + scenario.getName());
    }

    @After
    public void afterScenario(Scenario scenario) {
        System.out.println("Finished scenario: " + scenario.getName());
        if (scenario.isFailed()) {
            // Handle failure
        }
    }

    @BeforeStep
    public void beforeStep() {
        // Runs before each step
    }

    @AfterStep
    public void afterStep() {
        // Runs after each step
    }
}
```

### Tagged Hooks

Run hooks only for specific tags:

```java
@Before("@database")
public void setupDatabase() {
    // Only runs for scenarios tagged with @database
}

@After("@cleanup")
public void cleanup() {
    // Only runs for scenarios tagged with @cleanup
}
```

### Hook Execution Order

Control hook execution order with the `order` parameter:

```java
@Before(order = 1)
public void firstHook() {
    // Runs first
}

@Before(order = 2)
public void secondHook() {
    // Runs second
}
```

## Data Tables

Cucumber data tables allow you to pass structured data to steps:

### Feature File:
```gherkin
Scenario: Create multiple users
  Given the following users exist:
    | username | email              | role  |
    | alice    | alice@example.com  | admin |
    | bob      | bob@example.com    | user  |
    | charlie  | charlie@example.com| user  |
```

### Step Definition:
```java
@Given("the following users exist:")
public void createUsers(DataTable dataTable) {
    List<Map<String, String>> users = dataTable.asMaps();
    for (Map<String, String> user : users) {
        String username = user.get("username");
        String email = user.get("email");
        String role = user.get("role");
        // Create user
    }
}
```

## Scenario Outlines

Scenario outlines allow you to run the same scenario with different data:

```gherkin
Scenario Outline: Login with different credentials
  Given I am on the login page
  When I enter username "<username>" and password "<password>"
  Then I should see "<result>"

  Examples:
    | username | password | result          |
    | admin    | admin123 | Dashboard       |
    | user     | user123  | User Home       |
    | invalid  | wrong    | Invalid credentials |
```

## Configuration Parameters Reference

### Common Cucumber Constants

All available from `io.cucumber.junit.platform.engine.Constants`:

| Constant | Purpose | Example |
|----------|---------|---------|
| `PLUGIN_PROPERTY_NAME` | Configure plugins | `"net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"` |
| `GLUE_PROPERTY_NAME` | Step definition packages | `"com.example.stepdefinitions"` |
| `FILTER_TAGS_PROPERTY_NAME` | Tag expression filter | `"@smoke and not @wip"` |
| `FEATURES_PROPERTY_NAME` | Feature file locations | `"src/test/resources/features"` |
| `PLUGIN_PUBLISH_QUIET_PROPERTY_NAME` | Suppress Cucumber publish messages | `"true"` |
| `ANSI_COLORS_DISABLED_PROPERTY_NAME` | Disable colored output | `"true"` |
| `EXECUTION_DRY_RUN_PROPERTY_NAME` | Check step definitions without running | `"true"` |
| `OBJECT_FACTORY_PROPERTY_NAME` | Custom object factory | `"com.example.CustomObjectFactory"` |

### Parallel Execution Properties

| Property | Purpose | Example |
|----------|---------|---------|
| `cucumber.execution.parallel.enabled` | Enable parallel execution | `true` |
| `cucumber.execution.parallel.config.strategy` | Execution strategy | `dynamic`, `fixed` |
| `cucumber.execution.parallel.config.fixed.parallelism` | Number of parallel threads (fixed) | `4` |
| `cucumber.execution.parallel.config.dynamic.factor` | Multiplier for available processors | `1.0` |

## Multiple Test Suites

You can create multiple test suites for different purposes:

```java
// Smoke tests
@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = FILTER_TAGS_PROPERTY_NAME, value = "@smoke")
class SmokeTestSuite {}

// Regression tests
@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = FILTER_TAGS_PROPERTY_NAME, value = "@regression")
class RegressionTestSuite {}

// Specific feature area
@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features/authentication")
class AuthenticationTestSuite {}
```

## Best Practices

### 1. Feature File Organization
- Group related features in directories
- Use meaningful feature names
- Keep scenarios focused and independent
- Use Background for common setup

### 2. Tagging Strategy
- Use tags consistently across the project
- Common tags: `@smoke`, `@regression`, `@wip`, `@bug`, `@slow`
- Tag by feature area: `@authentication`, `@checkout`, `@search`
- Tag by test type: `@ui`, `@api`, `@integration`

### 3. Step Definitions
- Write reusable steps
- Use Cucumber expressions for flexibility
- Keep step implementations thin - delegate to action classes or Screenplay tasks
- Avoid duplicating step definitions

### 4. Scenario Design
- Write scenarios from the user's perspective
- Use Given-When-Then structure consistently
- Keep scenarios focused on a single behavior
- Use scenario outlines for data-driven tests

### 5. Reporting
- Always configure the Serenity reporter
- Use meaningful scenario and step names
- Add relevant tags for filtering reports
- Review reports regularly

## Troubleshooting

### Common Issues

**1. JUnit 5 tests not running alongside Cucumber tests**

If you have both JUnit 5 tests and Cucumber tests in your project, but only Cucumber tests are being discovered and run, this is likely because Cucumber's `cucumber.features` property causes other discovery selectors to be ignored. You'll see a warning like:

```
WARNING: Discovering tests using the cucumber.features property. Other discovery selectors are ignored!
```

The solution is to configure separate Maven Failsafe executions for JUnit and Cucumber tests. See [Running JUnit 5 and Cucumber Tests Together](/docs/guide/maven#running-junit-5-and-cucumber-tests-together) for the full configuration.

**2. "No tests found"**
- Ensure `@Suite` and `@IncludeEngines("cucumber")` are present
- Check that feature files are in the correct location
- Verify step definitions are in the glue path

**3. "Step undefined"**
- Implement the missing step definition
- Check the glue configuration points to your step definitions package
- Ensure step regex/expressions match

**4. "Plugin not found"**
- Verify you're using the correct plugin path: `net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel`
- Check Serenity dependencies are included

**5. "Tests not running in parallel"**
- Ensure parallel configuration is in `junit-platform.properties`
- Use `SerenityReporterParallel` (not `SerenityReporter`)
- Check JUnit Platform configuration

## Next Steps

- Learn about [Parallel Execution](parallel-execution) for faster test runs
- Explore [Cucumber Configuration Reference](configuration-reference) for advanced options
- Check out the [Screenplay Pattern](/docs/screenplay/screenplay_fundamentals) for better test maintainability
- Review [Serenity Reports](/docs/reporting/the_serenity_reports) documentation

## Additional Resources

- [Cucumber Documentation](https://cucumber.io/docs/cucumber/)
- [JUnit 5 User Guide](https://junit.org/junit5/docs/current/user-guide/)
- [Serenity BDD Official Site](https://serenity-bdd.info)
- [Example Project](https://github.com/serenity-bdd/serenity-cucumber-starter)


---

<!-- https://serenity-bdd.github.io/docs/cucumber/parallel-execution -->

# Running Cucumber Scenarios in Parallel

Running Cucumber scenarios in parallel can dramatically reduce test execution time. This guide explains how to configure and optimize parallel execution with Serenity BDD and JUnit 5.

## Overview

Parallel execution in Cucumber with JUnit 5 is powered by the Cucumber JUnit Platform Engine, which integrates with JUnit 5's parallel test execution capabilities. When properly configured, multiple scenarios can run simultaneously, taking advantage of multi-core processors.

## Prerequisites

- Serenity BDD 3.6.0 or higher
- JUnit 5
- Cucumber JUnit Platform Engine
- Thread-safe test code

## Basic Configuration

### Step 1: Add Required Dependencies

Ensure you have the Cucumber JUnit Platform Engine dependency:

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit-platform-engine</artifactId>
    <version>7.33.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-suite</artifactId>
    <version>5.10.0</version>
    <scope>test</scope>
</dependency>
```

### Step 2: Use the Parallel Reporter

:::warning Important
You **must** use `SerenityReporterParallel` for parallel execution, not `SerenityReporter`.
:::

Update your test suite to use the parallel-safe reporter:

```java
import org.junit.platform.suite.api.*;
import static io.cucumber.junit.platform.engine.Constants.PLUGIN_PROPERTY_NAME;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"
)
class CucumberTestSuite {
}
```

### Step 3: Configure Parallel Execution

Create or update `junit-platform.properties` in `src/test/resources`:

```properties
# Enable parallel execution
cucumber.execution.parallel.enabled=true

# Use dynamic strategy (recommended)
cucumber.execution.parallel.config.strategy=dynamic

# Configure the Serenity reporter
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel
```

## Execution Strategies

### Dynamic Strategy (Recommended)

The dynamic strategy automatically determines the number of threads based on available processors:

```properties
cucumber.execution.parallel.config.strategy=dynamic
cucumber.execution.parallel.config.dynamic.factor=1.0
```

The `factor` is a multiplier for the number of available processors:
- `1.0` = same number of threads as processors (recommended)
- `0.5` = half the number of processors
- `2.0` = double the number of processors

**Example:** On a machine with 8 cores:
- Factor `1.0` = 8 threads
- Factor `0.5` = 4 threads
- Factor `2.0` = 16 threads

### Fixed Strategy

The fixed strategy uses a specified number of threads:

```properties
cucumber.execution.parallel.config.strategy=fixed
cucumber.execution.parallel.config.fixed.parallelism=4
cucumber.execution.parallel.config.fixed.max-pool-size=4
```

- `parallelism` - Number of concurrent threads
- `max-pool-size` - Maximum size of the thread pool

**Use when:**
- You need consistent, predictable thread counts
- Running on shared CI/CD infrastructure
- Debugging parallel execution issues

### Custom Strategy

For advanced use cases, you can implement a custom strategy:

```properties
cucumber.execution.parallel.config.strategy=custom
cucumber.execution.parallel.config.custom.class=com.example.MyParallelStrategy
```

## Complete Configuration Example

**junit-platform.properties:**
```properties
# Parallel execution
cucumber.execution.parallel.enabled=true
cucumber.execution.parallel.config.strategy=dynamic
cucumber.execution.parallel.config.dynamic.factor=1.0

# Serenity reporter
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel

# Optional: Control execution order
cucumber.execution.order=random

# Optional: Fail fast
cucumber.execution.fail-fast=false
```

## Thread Safety Considerations

### WebDriver Management

Serenity's `@Managed` WebDriver is automatically thread-safe when using parallel execution:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class WebDriverSteps {

    @Managed
    WebDriver driver;  // Thread-safe - each thread gets its own instance

    @Given("I am on the home page")
    public void navigateToHomePage() {
        driver.get("https://example.com");
    }
}
```

Each thread will have its own isolated WebDriver instance.

### Step Definition Thread Safety

Step definition classes must be thread-safe:

**✅ Thread-Safe (Recommended):**
```java
public class LoginSteps {

    @Given("{actor} is on the login page")
    public void navigateToLoginPage(Actor actor) {
        actor.attemptsTo(
            Navigate.to("/login")
        );
    }
}
```

**❌ Not Thread-Safe:**
```java
public class LoginSteps {

    private String username;  // Shared state - NOT thread-safe!

    @Given("user enters username {string}")
    public void enterUsername(String user) {
        this.username = user;  // Race condition!
    }
}
```

### Using Scenario Context

For sharing data within a scenario, use Cucumber's scenario context:

```java
public class CheckoutSteps {

    private final ScenarioContext context;

    public CheckoutSteps(ScenarioContext context) {
        this.context = context;  // Injected per scenario
    }

    @When("I add item to cart")
    public void addItem() {
        context.put("cartTotal", calculateTotal());
    }

    @Then("cart total should be correct")
    public void verifyTotal() {
        Double total = context.get("cartTotal", Double.class);
        // Verify total
    }
}
```

## Controlling Parallelism

### Parallel at Different Levels

You can control what runs in parallel:

#### Scenario-Level Parallelism (Default)
```properties
# Each scenario runs in its own thread
cucumber.execution.parallel.enabled=true
```

#### Feature-Level Parallelism
To run features in parallel but scenarios within a feature sequentially, you need to configure JUnit Platform:

**junit-platform.properties:**
```properties
junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=concurrent
junit.jupiter.execution.parallel.mode.classes.default=concurrent
```

### Limiting Concurrent Scenarios

Control the maximum number of concurrent scenarios:

```properties
cucumber.execution.parallel.config.strategy=fixed
cucumber.execution.parallel.config.fixed.parallelism=4
```

## Parallel Execution with Tags

You can run specific tags in parallel:

```java
@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"
)
@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "@parallel"
)
class ParallelTestSuite {
}
```

Or exclude scenarios from parallel execution:

```properties
cucumber.filter.tags=not @serial
```

## Maven/Gradle Configuration

### Maven Surefire Plugin

Configure Maven to support parallel execution:

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <skip>true</skip>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-failsafe-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <includes>
                    <include>**/*TestSuite.java</include>
                </includes>
                <systemPropertyVariables>
                    <webdriver.driver>${webdriver.driver}</webdriver.driver>
                </systemPropertyVariables>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>integration-test</goal>
                        <goal>verify</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

### Gradle Configuration

For Gradle:

```groovy
test {
    useJUnitPlatform()
    maxParallelForks = Runtime.runtime.availableProcessors()

    systemProperty 'cucumber.execution.parallel.enabled', 'true'
    systemProperty 'cucumber.execution.parallel.config.strategy', 'dynamic'
}
```

## Performance Optimization

### 1. Choose the Right Strategy

- **Small test suites** (&lt;50 scenarios): Fixed strategy with 2-4 threads
- **Medium test suites** (50-200 scenarios): Dynamic strategy with factor 1.0
- **Large test suites** (&gt;200 scenarios): Dynamic strategy with factor 0.75-1.0

### 2. Optimize Scenario Design

- **Keep scenarios independent** - No shared state between scenarios
- **Minimize setup time** - Use efficient Before hooks
- **Avoid sleeps** - Use explicit waits instead
- **Clean up resources** - Use After hooks properly

### 3. Resource Management

```properties
# Control thread pool size to avoid resource exhaustion
cucumber.execution.parallel.config.fixed.max-pool-size=8

# Avoid too many concurrent browsers
webdriver.pool.max=10
```

### 4. Monitor Resource Usage

Watch for:
- CPU utilization (should be near 100% for optimal performance)
- Memory consumption (each browser instance uses RAM)
- Network bandwidth (for remote WebDriver)
- Database connections (if applicable)

## Debugging Parallel Tests

### Disable Parallel Execution Temporarily

```properties
cucumber.execution.parallel.enabled=false
```

Or via command line:
```bash
mvn clean verify -Dcucumber.execution.parallel.enabled=false
```

### Run with Fewer Threads

```properties
cucumber.execution.parallel.config.strategy=fixed
cucumber.execution.parallel.config.fixed.parallelism=1
```

### Verbose Logging

Enable detailed logging to diagnose issues:

```properties
# Log file location
cucumber.plugin=pretty,html:target/cucumber-reports.html,json:target/cucumber.json

# Serenity logging
serenity.verbose=true
serenity.logging=VERBOSE
```

## Common Issues and Solutions

### Issue 1: Flaky Tests

**Symptoms:** Tests pass when run individually but fail when run in parallel

**Solutions:**
- Check for shared state in step definitions
- Ensure WebDriver instances are properly isolated
- Review test data - avoid shared test data
- Add proper synchronization/waits

### Issue 2: Resource Exhaustion

**Symptoms:** Tests slow down or crash after some time

**Solutions:**
- Reduce parallelism: lower the thread count
- Increase heap size: `-Xmx4g`
- Check for resource leaks (unclosed connections, browser instances)
- Monitor system resources

### Issue 3: Report Generation Issues

**Symptoms:** Serenity reports are incomplete or corrupted

**Solutions:**
- Ensure you're using `SerenityReporterParallel`
- Check Serenity version (3.6.0+)
- Verify maven-failsafe-plugin is configured correctly
- Check for filesystem race conditions

### Issue 4: CI/CD Pipeline Failures

**Symptoms:** Tests fail only in CI but pass locally

**Solutions:**
- Match thread count to CI environment capabilities
- Use fixed strategy for consistent behavior
- Increase timeouts for slower CI environments
- Check CI resource limits

## Best Practices

### 1. Start Small
Begin with 2-4 threads and gradually increase:

```properties
cucumber.execution.parallel.config.strategy=fixed
cucumber.execution.parallel.config.fixed.parallelism=2
```

### 2. Use Tags Strategically

Mark scenarios that can't run in parallel:

```gherkin
@serial @database-migration
Scenario: Migrate database schema
  # This scenario must run alone
```

Then exclude them:
```properties
cucumber.filter.tags=not @serial
```

### 3. Isolate Test Data

Each scenario should create and clean up its own test data:

```java
@Before
public void setupTestData() {
    // Create unique test data for this scenario
    String uniqueId = UUID.randomUUID().toString();
    context.put("testUserId", "user_" + uniqueId);
}

@After
public void cleanupTestData() {
    // Clean up this scenario's test data
    String userId = context.get("testUserId", String.class);
    deleteUser(userId);
}
```

### 4. Monitor and Adjust

- Monitor test execution times
- Track flaky test rates
- Adjust parallelism based on metrics
- Review resource utilization

### 5. Document Thread Safety

Add comments for non-thread-safe scenarios:

```gherkin
# @serial - Modifies global application state
@serial @admin
Scenario: Update application settings
  Given I am logged in as admin
  When I change the default language to Spanish
  Then all users should see Spanish interface
```

## Measuring Performance Improvements

### Before Parallel Execution
```
Total scenarios: 100
Execution time: 50 minutes
```

### After Parallel Execution (8 threads)
```
Total scenarios: 100
Execution time: 8 minutes
Speedup: 6.25x
Efficiency: 78%
```

Calculate your speedup:
```
Speedup = Sequential Time / Parallel Time
Efficiency = Speedup / Number of Threads
```

## Next Steps

- Review the main [Cucumber with JUnit 5](cucumber-junit5) guide
- Check the [Configuration Reference](configuration-reference) for all available options
- See [Best Practices](cucumber-junit5#best-practices) for writing maintainable tests
- Explore [Serenity Reports](/docs/reporting/the_serenity_reports) documentation

## Additional Resources

- [Cucumber Parallel Execution Docs](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine#parallel-execution)
- [JUnit 5 Parallel Execution](https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution)
- [Serenity BDD Performance Tips](https://serenity-bdd.info)


---

<!-- https://serenity-bdd.github.io/docs/cucumber/advanced-patterns -->

# Advanced Cucumber Patterns with Serenity BDD

This guide covers advanced patterns and techniques for writing maintainable, scalable Cucumber tests with Serenity BDD. You'll learn patterns used by experienced test automation engineers to build robust test suites.

## Prerequisites

This guide assumes you're familiar with:
- Basic Cucumber concepts (features, scenarios, step definitions)
- Serenity BDD fundamentals
- Either the Screenplay pattern or Page Objects

If you're new to Cucumber with Serenity, start with [Running Cucumber Scenarios with JUnit 5](cucumber-junit5).

## Advanced Hook Patterns

Cucumber hooks allow you to run code at specific points in the test lifecycle. Understanding advanced hook patterns is essential for proper test setup and cleanup.

### Hook Types and Execution Order

Cucumber provides several hook types that execute at different points:

```java
package com.example.hooks;

import io.cucumber.java.*;

public class LifecycleHooks {

    // Runs once before ALL scenarios (Cucumber 7+)
    @BeforeAll
    public static void beforeAllScenarios() {
        System.out.println("Starting test suite");
        // Initialize shared resources, start test containers, etc.
    }

    // Runs before EACH scenario
    @Before
    public void beforeScenario(Scenario scenario) {
        System.out.println("Starting: " + scenario.getName());
    }

    // Runs before EACH step
    @BeforeStep
    public void beforeStep() {
        // Useful for logging or timing
    }

    // Runs after EACH step
    @AfterStep
    public void afterStep() {
        // Useful for screenshots or state verification
    }

    // Runs after EACH scenario
    @After
    public void afterScenario(Scenario scenario) {
        System.out.println("Finished: " + scenario.getName());
        if (scenario.isFailed()) {
            // Custom failure handling
        }
    }

    // Runs once after ALL scenarios (Cucumber 7+)
    @AfterAll
    public static void afterAllScenarios() {
        System.out.println("Test suite complete");
        // Cleanup shared resources
    }
}
```

**Execution order for a single scenario:**
```
@BeforeAll (once per test run)
  └─> @Before
        └─> @BeforeStep → Step 1 → @AfterStep
        └─> @BeforeStep → Step 2 → @AfterStep
        └─> @BeforeStep → Step 3 → @AfterStep
      @After
@AfterAll (once per test run)
```

### Tagged Hooks

Run hooks only for scenarios with specific tags:

```java
public class TaggedHooks {

    @Before("@database")
    public void setupDatabase() {
        // Only runs for scenarios tagged @database
        DatabaseTestUtils.resetDatabase();
        DatabaseTestUtils.loadFixtures("test-data.sql");
    }

    @After("@database")
    public void cleanupDatabase() {
        DatabaseTestUtils.truncateAllTables();
    }

    @Before("@authenticated")
    public void ensureAuthenticated() {
        // Setup authenticated session before scenarios that need it
    }

    @Before("@slow")
    public void increaseTimeouts() {
        // Increase timeouts for slow-running scenarios
    }
}
```

### Tag Expressions in Hooks

Use complex tag expressions to target specific scenarios:

```java
public class ConditionalHooks {

    @Before("@ui and not @headless")
    public void setupBrowserWithUI() {
        // Only for UI tests that need a visible browser
    }

    @Before("@api or @integration")
    public void setupApiClient() {
        // For API or integration tests
    }

    @Before("(@smoke or @regression) and not @wip")
    public void setupForRealTests() {
        // For smoke or regression, but skip work-in-progress
    }
}
```

### Hook Ordering

Control the order of hook execution when you have multiple hooks of the same type:

```java
public class OrderedHooks {

    // Lower order values run first for @Before hooks
    @Before(order = 1)
    public void firstSetup() {
        System.out.println("1. Initialize test environment");
    }

    @Before(order = 2)
    public void secondSetup() {
        System.out.println("2. Setup test data");
    }

    @Before(order = 3)
    public void thirdSetup() {
        System.out.println("3. Navigate to application");
    }

    // Higher order values run first for @After hooks (reverse order)
    @After(order = 3)
    public void firstCleanup() {
        System.out.println("1. Capture final state");
    }

    @After(order = 2)
    public void secondCleanup() {
        System.out.println("2. Cleanup test data");
    }

    @After(order = 1)
    public void thirdCleanup() {
        System.out.println("3. Close resources");
    }
}
```

:::tip Hook Order Memory Aid
- **@Before**: Lower numbers run first (1, 2, 3...)
- **@After**: Higher numbers run first (...3, 2, 1)

Think of it as wrapping: setup builds up, teardown unwinds in reverse.
:::

### Screenplay-Specific Hooks

When using the Screenplay pattern, set up actors in hooks:

```java
package com.example.hooks;

import io.cucumber.java.*;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.actors.OnlineCast;
import net.serenitybdd.screenplay.abilities.BrowseTheWeb;

public class ScreenplayHooks {

    @Before
    public void setTheStage() {
        OnStage.setTheStage(new OnlineCast());
    }

    @After
    public void drawTheCurtain() {
        OnStage.drawTheCurtain();
    }
}
```

For Playwright-based tests:

```java
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;

public class PlaywrightHooks {

    @Before
    public void setTheStage() {
        OnStage.setTheStage(Cast.whereEveryoneCan(
            BrowseTheWebWithPlaywright.usingTheDefaultConfiguration()
        ));
    }
}
```

## Custom Parameter Types

Cucumber expressions support custom parameter types that transform step arguments into domain objects.

### Defining Custom Parameter Types

```java
package com.example.parameters;

import io.cucumber.java.ParameterType;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

public class CustomParameters {

    // Transform "today", "tomorrow", "yesterday" into LocalDate
    @ParameterType("today|tomorrow|yesterday|\\d{4}-\\d{2}-\\d{2}")
    public LocalDate date(String value) {
        return switch (value) {
            case "today" -> LocalDate.now();
            case "tomorrow" -> LocalDate.now().plusDays(1);
            case "yesterday" -> LocalDate.now().minusDays(1);
            default -> LocalDate.parse(value);
        };
    }

    // Transform currency amounts like "$100.50" or "€50"
    @ParameterType("\\$[\\d,]+\\.?\\d*|€[\\d,]+\\.?\\d*|£[\\d,]+\\.?\\d*")
    public Money money(String value) {
        String currency = value.substring(0, 1);
        double amount = Double.parseDouble(value.substring(1).replace(",", ""));
        return new Money(amount, currency);
    }

    // Transform user roles
    @ParameterType("admin|manager|user|guest")
    public UserRole role(String value) {
        return UserRole.valueOf(value.toUpperCase());
    }
}
```

### Using Custom Parameters in Steps

```gherkin
Feature: Order Management

  Scenario: Schedule order for delivery
    Given an order placed on 2024-01-15
    When I schedule delivery for tomorrow
    Then the delivery date should be after today

  Scenario: Apply discount to order
    Given an order totaling $150.00
    When a manager applies a 10% discount
    Then the new total should be $135.00
```

```java
public class OrderSteps {

    @Given("an order placed on {date}")
    public void anOrderPlacedOn(LocalDate orderDate) {
        // orderDate is already a LocalDate object
        theActorInTheSpotlight().remember("orderDate", orderDate);
    }

    @When("I schedule delivery for {date}")
    public void scheduleDeliveryFor(LocalDate deliveryDate) {
        theActorInTheSpotlight().attemptsTo(
            ScheduleDelivery.forDate(deliveryDate)
        );
    }

    @Given("an order totaling {money}")
    public void anOrderTotaling(Money total) {
        // total is a Money object with amount and currency
        theActorInTheSpotlight().attemptsTo(
            CreateOrder.withTotal(total)
        );
    }

    @When("a {role} applies a {int}% discount")
    public void applyDiscount(UserRole role, int percentage) {
        // role is a UserRole enum
        theActorInTheSpotlight().attemptsTo(
            ApplyDiscount.of(percentage).asA(role)
        );
    }
}
```

### Actor Parameter Type

Serenity BDD provides a built-in `{actor}` parameter type:

```gherkin
Scenario: Multiple users interact
  Given Alice has items in her cart
  And Bob is browsing the catalog
  When Alice proceeds to checkout
  And Bob adds a laptop to his cart
  Then Alice should see the payment page
  And Bob should have 1 item in his cart
```

```java
public class MultiActorSteps {

    @Given("{actor} has items in her/his cart")
    public void hasItemsInCart(Actor actor) {
        actor.attemptsTo(
            AddToCart.item("Sample Product")
        );
    }

    @When("{actor} proceeds to checkout")
    public void proceedsToCheckout(Actor actor) {
        actor.attemptsTo(
            NavigateTo.theCheckoutPage()
        );
    }

    @Then("{actor} should have {int} item(s) in her/his cart")
    public void shouldHaveItemsInCart(Actor actor, int count) {
        actor.should(
            seeThat(TheCart.itemCount(), equalTo(count))
        );
    }
}
```

## Complex Data Table Patterns

Data tables are powerful for passing structured data to steps.

### Basic Data Table Transformations

```gherkin
Scenario: Create multiple products
  Given the following products exist:
    | name        | price  | category    | inStock |
    | Laptop      | 999.99 | Electronics | true    |
    | Headphones  | 149.99 | Electronics | true    |
    | Desk Chair  | 299.99 | Furniture   | false   |
```

**Using DataTable directly:**

```java
@Given("the following products exist:")
public void createProducts(DataTable dataTable) {
    List<Map<String, String>> rows = dataTable.asMaps();
    for (Map<String, String> row : rows) {
        String name = row.get("name");
        double price = Double.parseDouble(row.get("price"));
        String category = row.get("category");
        boolean inStock = Boolean.parseBoolean(row.get("inStock"));
        // Create product...
    }
}
```

**Automatic transformation to POJOs:**

```java
public class Product {
    private String name;
    private double price;
    private String category;
    private boolean inStock;

    // Getters and setters...
}

@Given("the following products exist:")
public void createProducts(List<Product> products) {
    // Cucumber automatically transforms rows to Product objects
    for (Product product : products) {
        theActorInTheSpotlight().attemptsTo(
            CreateProduct.withDetails(product)
        );
    }
}
```

### DataTableType for Custom Transformations

```java
package com.example.parameters;

import io.cucumber.java.DataTableType;
import java.util.Map;

public class DataTableTypes {

    @DataTableType
    public Product productEntry(Map<String, String> entry) {
        Product product = new Product();
        product.setName(entry.get("name"));
        product.setPrice(parsePrice(entry.get("price")));
        product.setCategory(entry.get("category"));
        product.setInStock("yes".equalsIgnoreCase(entry.get("available")));

        // Handle optional fields
        if (entry.containsKey("sku")) {
            product.setSku(entry.get("sku"));
        }

        return product;
    }

    @DataTableType
    public Address addressEntry(Map<String, String> entry) {
        return Address.builder()
            .street(entry.get("street"))
            .city(entry.get("city"))
            .state(entry.get("state"))
            .zipCode(entry.get("zip"))
            .country(entry.getOrDefault("country", "USA"))
            .build();
    }

    private double parsePrice(String price) {
        return Double.parseDouble(price.replace("$", "").replace(",", ""));
    }
}
```

### Vertical Data Tables

For single-entity data, use vertical tables:

```gherkin
Scenario: Create a detailed user profile
  Given a user with the following details:
    | First Name    | John              |
    | Last Name     | Smith             |
    | Email         | john@example.com  |
    | Phone         | +1-555-123-4567   |
    | Date of Birth | 1990-05-15        |
    | Role          | Premium Member    |
```

```java
@Given("a user with the following details:")
public void createUser(DataTable dataTable) {
    Map<String, String> userData = dataTable.asMap();

    UserProfile profile = UserProfile.builder()
        .firstName(userData.get("First Name"))
        .lastName(userData.get("Last Name"))
        .email(userData.get("Email"))
        .phone(userData.get("Phone"))
        .dateOfBirth(LocalDate.parse(userData.get("Date of Birth")))
        .role(userData.get("Role"))
        .build();

    theActorInTheSpotlight().attemptsTo(
        CreateUserProfile.with(profile)
    );
}
```

### Nested Data Structures

For complex data, combine tables with scenario outlines:

```gherkin
Scenario Outline: Validate order with multiple items
  Given a customer places an order with:
    | product   | quantity | unit price |
    | <item1>   | <qty1>   | <price1>   |
    | <item2>   | <qty2>   | <price2>   |
  When the order is processed
  Then the order total should be <total>

  Examples:
    | item1     | qty1 | price1 | item2      | qty2 | price2 | total   |
    | Laptop    | 1    | $999   | Mouse      | 2    | $25    | $1049   |
    | Monitor   | 2    | $300   | Keyboard   | 1    | $75    | $675    |
```

## Doc Strings for Long-Form Content

Use doc strings for multi-line text content:

```gherkin
Scenario: Submit a support ticket
  Given the customer has a billing issue
  When they submit a support ticket with:
    """
    Subject: Incorrect charge on my account

    Hello,

    I noticed an incorrect charge of $49.99 on my account
    dated January 15th. I did not authorize this transaction.

    Please investigate and refund the amount.

    Thank you,
    John Smith
    Account: JS-12345
    """
  Then a ticket should be created with priority "High"
```

```java
@When("they submit a support ticket with:")
public void submitTicket(String ticketContent) {
    theActorInTheSpotlight().attemptsTo(
        SubmitSupportTicket.withContent(ticketContent)
    );
}
```

### Doc Strings with Content Types

Specify the content type for structured data:

```gherkin
Scenario: Create product via API
  When I send a POST request to "/api/products" with:
    """json
    {
      "name": "Wireless Keyboard",
      "price": 79.99,
      "category": "Electronics",
      "specifications": {
        "connection": "Bluetooth 5.0",
        "battery": "AAA x 2",
        "warranty": "2 years"
      }
    }
    """
  Then the response status should be 201
```

```java
@When("I send a POST request to {string} with:")
public void sendPostRequest(String endpoint, String jsonBody) {
    theActorInTheSpotlight().attemptsTo(
        Post.to(endpoint).with(request -> request
            .contentType(ContentType.JSON)
            .body(jsonBody)
        )
    );
}
```

## Sharing State Between Steps

Managing state across steps is crucial for maintainable tests.

### Using Actor Memory (Screenplay Pattern)

The recommended approach with Screenplay:

```java
public class OrderSteps {

    @Given("a customer creates an order")
    public void createOrder() {
        String orderId = UUID.randomUUID().toString();

        theActorInTheSpotlight().attemptsTo(
            CreateOrder.withId(orderId)
        );

        // Store for later steps
        theActorInTheSpotlight().remember("orderId", orderId);
    }

    @When("the customer adds {string} to the order")
    public void addItem(String item) {
        String orderId = theActorInTheSpotlight().recall("orderId");

        theActorInTheSpotlight().attemptsTo(
            AddToOrder.item(item).forOrder(orderId)
        );
    }

    @Then("the order should contain {int} items")
    public void verifyItemCount(int expectedCount) {
        String orderId = theActorInTheSpotlight().recall("orderId");

        theActorInTheSpotlight().should(
            seeThat(TheOrder.withId(orderId).itemCount(), equalTo(expectedCount))
        );
    }
}
```

### Typed Memory with Generics

Create type-safe memory keys:

```java
public class MemoryKeys {
    public static final String ORDER_ID = "orderId";
    public static final String CUSTOMER = "customer";
    public static final String CART_ITEMS = "cartItems";
}

// Usage
actor.remember(MemoryKeys.ORDER_ID, orderId);
String id = actor.recall(MemoryKeys.ORDER_ID);
```

### Using World Objects (Dependency Injection)

For complex state management, use Cucumber's dependency injection:

**With PicoContainer (default):**

```java
// Shared state class
public class TestContext {
    private Order currentOrder;
    private Customer currentCustomer;
    private List<String> capturedErrors = new ArrayList<>();

    public Order getCurrentOrder() { return currentOrder; }
    public void setCurrentOrder(Order order) { this.currentOrder = order; }

    public Customer getCurrentCustomer() { return currentCustomer; }
    public void setCurrentCustomer(Customer customer) { this.currentCustomer = customer; }

    public void addError(String error) { capturedErrors.add(error); }
    public List<String> getErrors() { return capturedErrors; }
}

// Step definitions receive TestContext via constructor injection
public class OrderSteps {
    private final TestContext context;

    public OrderSteps(TestContext context) {
        this.context = context;
    }

    @Given("a customer creates an order")
    public void createOrder() {
        Order order = new Order();
        context.setCurrentOrder(order);
    }

    @When("an error occurs: {string}")
    public void captureError(String error) {
        context.addError(error);
    }
}
```

**Add PicoContainer dependency:**

```xml
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-picocontainer</artifactId>
    <version>${cucumber.version}</version>
    <scope>test</scope>
</dependency>
```

## Error Handling Patterns

Handle errors gracefully in step definitions.

### Expected Errors Pattern

```gherkin
Scenario: Prevent checkout with empty cart
  Given a customer with an empty cart
  When they attempt to checkout
  Then they should see an error: "Your cart is empty"
```

```java
public class ErrorSteps {

    @When("they attempt to checkout")
    public void attemptCheckout() {
        try {
            theActorInTheSpotlight().attemptsTo(
                ProceedToCheckout.now()
            );
            // Store that no error occurred
            theActorInTheSpotlight().remember("checkoutError", null);
        } catch (CheckoutException e) {
            // Store the error for verification
            theActorInTheSpotlight().remember("checkoutError", e.getMessage());
        }
    }

    @Then("they should see an error: {string}")
    public void shouldSeeError(String expectedError) {
        String actualError = theActorInTheSpotlight().recall("checkoutError");
        assertThat(actualError).isEqualTo(expectedError);
    }
}
```

### Using Questions for Error States

A cleaner approach with Screenplay:

```java
public class ErrorMessage implements Question<String> {

    public static Question<String> displayed() {
        return new ErrorMessage();
    }

    @Override
    public String answeredBy(Actor actor) {
        return Text.of(".error-message").answeredBy(actor);
    }
}

// In steps
@Then("they should see an error: {string}")
public void shouldSeeError(String expectedError) {
    theActorInTheSpotlight().should(
        seeThat(ErrorMessage.displayed(), equalTo(expectedError))
    );
}
```

### Soft Assertions for Multiple Checks

```java
@Then("the order summary should show:")
public void verifyOrderSummary(DataTable expected) {
    Actor actor = theActorInTheSpotlight();

    actor.attemptsTo(
        Ensure.that(OrderSummary.subtotal()).isEqualTo(expected.get("subtotal")),
        Ensure.that(OrderSummary.tax()).isEqualTo(expected.get("tax")),
        Ensure.that(OrderSummary.shipping()).isEqualTo(expected.get("shipping")),
        Ensure.that(OrderSummary.total()).isEqualTo(expected.get("total"))
    );
}
```

## Step Definition Organization

### One Class Per Feature Area

Organize step definitions by domain area:

```
src/test/java/com/example/stepdefinitions/
├── authentication/
│   ├── LoginSteps.java
│   ├── RegistrationSteps.java
│   └── PasswordResetSteps.java
├── shopping/
│   ├── CartSteps.java
│   ├── CheckoutSteps.java
│   └── PaymentSteps.java
├── common/
│   ├── NavigationSteps.java
│   └── VerificationSteps.java
└── hooks/
    ├── ScreenplayHooks.java
    └── DatabaseHooks.java
```

### Thin Steps, Rich Tasks

Keep step definitions thin by delegating to Screenplay tasks:

```java
// Bad: Logic in step definition
@When("the customer adds {string} to their cart")
public void addToCart(String productName) {
    WebDriver driver = getDriver();
    driver.findElement(By.cssSelector(".search-input")).sendKeys(productName);
    driver.findElement(By.cssSelector(".search-button")).click();
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector(".product-card")));
    driver.findElement(By.cssSelector(".add-to-cart-button")).click();
    wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector(".cart-updated")));
}

// Good: Delegate to Task
@When("the customer adds {string} to their cart")
public void addToCart(String productName) {
    theActorInTheSpotlight().attemptsTo(
        AddToCart.theProduct(productName)
    );
}
```

### Reusable Step Patterns

Create generic steps that work across features:

```java
public class CommonSteps {

    @Given("{actor} is on the {word} page")
    public void navigateToPage(Actor actor, String pageName) {
        actor.attemptsTo(
            NavigateTo.thePage(pageName)
        );
    }

    @Then("{actor} should see the message {string}")
    public void shouldSeeMessage(Actor actor, String message) {
        actor.should(
            seeThat(TheVisibleText.onPage(), containsString(message))
        );
    }

    @Then("{actor} should see {int} {word} displayed")
    public void shouldSeeCount(Actor actor, int count, String elementType) {
        actor.should(
            seeThat(TheCount.of(elementType), equalTo(count))
        );
    }
}
```

## Background Best Practices

### Keep Backgrounds Simple

```gherkin
# Good: Simple, essential setup
Background:
  Given the user is logged in as "admin"

# Bad: Too much detail in background
Background:
  Given a user with email "admin@example.com" exists
  And the user has password "SecurePass123!"
  And the user has role "administrator"
  And the user's account is active
  And the user has accepted terms of service
  When the user navigates to the login page
  And enters their credentials
  And clicks the login button
  Then they should be on the dashboard
```

### Use Tags to Share Backgrounds

```gherkin
@authenticated
Feature: Shopping Cart

  # This feature assumes user is logged in
  # The @authenticated hook handles login

  Scenario: Add item to cart
    When I search for "laptop"
    And I add the first result to my cart
    Then my cart should have 1 item
```

```java
@Before("@authenticated")
public void loginAsDefaultUser() {
    OnStage.theActorCalled("Customer").attemptsTo(
        Login.withCredentials("testuser", "password123")
    );
}
```

## Scenario Outline Patterns

### Dynamic Examples with Tags

```gherkin
@smoke
Scenario Outline: Quick login validation
  Given I am on the login page
  When I login as "<userType>"
  Then I should see the "<dashboard>" dashboard

  @admin
  Examples: Admin Users
    | userType     | dashboard    |
    | super_admin  | Super Admin  |
    | site_admin   | Site Admin   |

  @regular
  Examples: Regular Users
    | userType     | dashboard    |
    | premium      | Premium      |
    | standard     | Standard     |
```

### Example Tables from External Sources

Load examples from files or databases:

```java
public class DynamicExamples {

    @ParameterType(".*\\.csv")
    public List<Map<String, String>> csvFile(String filename) {
        return CsvReader.read("src/test/resources/data/" + filename);
    }
}
```

## Integration: Screenplay vs Page Objects

You can use either pattern with Cucumber, or even mix them.

### Pure Screenplay Approach

```java
public class CheckoutSteps {

    @When("{actor} completes checkout with card ending in {string}")
    public void completeCheckout(Actor actor, String lastFourDigits) {
        actor.attemptsTo(
            CompleteCheckout.withCard(lastFourDigits)
        );
    }

    @Then("{actor} should receive order confirmation")
    public void shouldReceiveConfirmation(Actor actor) {
        actor.should(
            seeThat(OrderConfirmation.isDisplayed(), is(true)),
            seeThat(OrderConfirmation.orderNumber(), not(emptyString()))
        );
    }
}
```

### Page Object Approach

```java
public class CheckoutSteps {

    @Steps
    CheckoutPage checkoutPage;

    @Steps
    ConfirmationPage confirmationPage;

    @When("the user completes checkout with card ending in {string}")
    public void completeCheckout(String lastFourDigits) {
        checkoutPage.enterCardEndingIn(lastFourDigits);
        checkoutPage.submitOrder();
    }

    @Then("the user should receive order confirmation")
    public void shouldReceiveConfirmation() {
        assertThat(confirmationPage.isDisplayed()).isTrue();
        assertThat(confirmationPage.getOrderNumber()).isNotEmpty();
    }
}
```

### Hybrid Approach

Use Page Objects for simple pages, Screenplay for complex flows:

```java
public class HybridSteps {

    @Steps
    LoginPage loginPage;  // Simple page, use Page Object

    @When("the user logs in with valid credentials")
    public void login() {
        loginPage.loginAs("user@example.com", "password");
    }

    @When("{actor} completes the multi-step registration")
    public void completeRegistration(Actor actor) {
        // Complex flow, use Screenplay
        actor.attemptsTo(
            CompleteRegistration.withDefaults()
        );
    }
}
```

## Performance Optimization

### Parallel Execution with Isolated State

Ensure your hooks and state management are thread-safe:

```java
public class ThreadSafeHooks {

    // ThreadLocal for parallel execution
    private static final ThreadLocal<TestContext> contextHolder = new ThreadLocal<>();

    @Before
    public void setUp() {
        contextHolder.set(new TestContext());
    }

    @After
    public void tearDown() {
        contextHolder.remove();
    }

    public static TestContext getContext() {
        return contextHolder.get();
    }
}
```

### Lazy Initialization

Don't initialize resources until needed:

```java
public class LazyDriverHooks {

    @Before("@ui")
    public void initializeDriver() {
        // Only create browser for UI tests
        OnStage.setTheStage(new OnlineCast());
    }

    @Before("@api")
    public void initializeApiClient() {
        // Only create API client for API tests
        OnStage.setTheStage(Cast.whereEveryoneCan(
            CallAnApi.at(baseUrl)
        ));
    }
}
```

## Debugging Tips

### Verbose Logging in Hooks

```java
@BeforeStep
public void logStepStart() {
    System.out.println(">>> Starting step at " + LocalDateTime.now());
}

@AfterStep
public void logStepEnd(Scenario scenario) {
    System.out.println("<<< Step completed, scenario status: " + scenario.getStatus());
}
```

### Capture State on Failure

```java
@After
public void captureOnFailure(Scenario scenario) {
    if (scenario.isFailed()) {
        // Capture screenshot
        byte[] screenshot = theActorInTheSpotlight()
            .usingAbilityTo(BrowseTheWeb.class)
            .takeScreenshot();
        scenario.attach(screenshot, "image/png", "failure-screenshot");

        // Capture page source
        String pageSource = theActorInTheSpotlight()
            .asksFor(ThePageSource.current());
        scenario.attach(pageSource, "text/html", "page-source");

        // Capture browser console
        List<String> consoleLogs = theActorInTheSpotlight()
            .asksFor(ConsoleMessages.all());
        scenario.attach(String.join("\n", consoleLogs), "text/plain", "console-logs");
    }
}
```

## Summary

These advanced patterns help you build maintainable, scalable Cucumber test suites:

| Pattern | When to Use |
|---------|-------------|
| Tagged Hooks | Conditional setup/teardown based on scenario tags |
| Ordered Hooks | Control execution order of multiple hooks |
| Custom Parameters | Transform step arguments to domain objects |
| Data Table Types | Automatic transformation of table rows |
| Actor Memory | Share state between steps (Screenplay) |
| World Objects | Complex state with dependency injection |
| Thin Steps | Keep steps minimal, delegate to tasks |
| Soft Assertions | Verify multiple conditions before failing |

## Next Steps

- Explore [Parallel Execution](parallel-execution) for faster test runs
- Learn about [Cucumber Configuration](configuration-reference) options
- Master the [Screenplay Pattern](/docs/screenplay/screenplay_fundamentals)
- Review [Serenity Reporting](/docs/reporting/the_serenity_reports) for rich documentation

## Additional Resources

- [Cucumber Expressions Documentation](https://cucumber.io/docs/cucumber/cucumber-expressions/)
- [Cucumber Hooks Reference](https://cucumber.io/docs/cucumber/api/#hooks)
- [Serenity BDD Screenplay Guide](/docs/screenplay/screenplay_fundamentals)


---

<!-- https://serenity-bdd.github.io/docs/cucumber/configuration-reference -->

# Cucumber Configuration Reference

This page provides a comprehensive reference of all configuration options for running Cucumber with Serenity BDD and JUnit 5.

## Configuration Methods

There are three ways to configure Cucumber with JUnit 5:

1. **@ConfigurationParameter annotations** (in test suite classes)
2. **junit-platform.properties** file (in src/test/resources)
3. **System properties** (command line or build tool)

Priority order: Annotations > System Properties > Properties File

## Essential Serenity Configuration

### Serenity Reporter Plugin

**Required for Serenity reports**

```java
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"
)
```

Or in `junit-platform.properties`:
```properties
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel
```

:::warning Breaking Change in Serenity 5.0.0
The plugin path changed from `io.cucumber.core.plugin.*` to `net.serenitybdd.cucumber.core.plugin.*`
:::

**Available reporters:**
- `SerenityReporterParallel` - Thread-safe, recommended for all scenarios
- `SerenityReporter` - Legacy, not thread-safe

## Core Cucumber Configuration

### Feature File Location

Specify where to find feature files:

```java
// Annotation approach
@SelectClasspathResource("features")

// Or using configuration parameter
@ConfigurationParameter(
    key = FEATURES_PROPERTY_NAME,
    value = "src/test/resources/features"
)
```

**junit-platform.properties:**
```properties
cucumber.features=src/test/resources/features
```

### Step Definitions (Glue)

Specify packages containing step definitions:

```java
@ConfigurationParameter(
    key = GLUE_PROPERTY_NAME,
    value = "com.example.stepdefinitions,com.example.hooks"
)
```

**junit-platform.properties:**
```properties
cucumber.glue=com.example.stepdefinitions,com.example.hooks
```

**Multiple packages:** Separate with commas

### Tag Filtering

Filter scenarios by tags:

```java
@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "@smoke and not @wip"
)
```

**junit-platform.properties:**
```properties
cucumber.filter.tags=@smoke and not @wip
```

**Tag expression syntax:**
- `@tag1 and @tag2` - Both tags required
- `@tag1 or @tag2` - Either tag required
- `not @tag` - Exclude tag
- `(@tag1 or @tag2) and not @tag3` - Complex expressions

**Command line:**
```bash
mvn verify -Dcucumber.filter.tags="@smoke"
```

## Parallel Execution Configuration

### Enable Parallel Execution

```properties
cucumber.execution.parallel.enabled=true
```

### Execution Strategy

**Dynamic (recommended):**
```properties
cucumber.execution.parallel.config.strategy=dynamic
cucumber.execution.parallel.config.dynamic.factor=1.0
```

Factor calculation: `threads = processors × factor`

**Fixed:**
```properties
cucumber.execution.parallel.config.strategy=fixed
cucumber.execution.parallel.config.fixed.parallelism=4
cucumber.execution.parallel.config.fixed.max-pool-size=4
```

**Custom:**
```properties
cucumber.execution.parallel.config.strategy=custom
cucumber.execution.parallel.config.custom.class=com.example.MyStrategy
```

### Parallel Execution Mode

```properties
# Parallel scenarios (default)
cucumber.execution.parallel.mode.default=concurrent

# Parallel features
cucumber.execution.parallel.mode.features.default=concurrent
```

## Execution Behavior

### Execution Order

Control scenario execution order:

```properties
# Random order (good for finding test dependencies)
cucumber.execution.order=random

# Alphabetical order
cucumber.execution.order=lexicographical

# Reverse alphabetical
cucumber.execution.order=reverse
```

### Dry Run

Check for undefined steps without executing:

```java
@ConfigurationParameter(
    key = EXECUTION_DRY_RUN_PROPERTY_NAME,
    value = "true"
)
```

**junit-platform.properties:**
```properties
cucumber.execution.dry-run=true
```

### Wip (Work In Progress)

Run only scenarios tagged with @wip:

```properties
cucumber.execution.wip=true
```

### Strict Mode

Treat undefined and pending steps as errors:

```properties
cucumber.execution.strict=true
```

## Plugin Configuration

### Multiple Plugins

Configure multiple plugins:

```properties
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel,\
  pretty,\
  html:target/cucumber-reports/cucumber.html,\
  json:target/cucumber-reports/cucumber.json,\
  junit:target/cucumber-reports/cucumber.xml
```

### Common Plugins

| Plugin | Purpose | Example |
|--------|---------|---------|
| `pretty` | Console output with colors | `pretty` |
| `html` | HTML report | `html:target/cucumber.html` |
| `json` | JSON report | `json:target/cucumber.json` |
| `junit` | JUnit XML report | `junit:target/cucumber.xml` |
| `timeline` | Timeline report | `timeline:target/timeline` |
| `usage` | Step usage report | `usage:target/usage.json` |
| `rerun` | Failed scenarios file | `rerun:target/rerun.txt` |

### Suppress Cucumber Messages

Suppress "Share your results" message:

```java
@ConfigurationParameter(
    key = PLUGIN_PUBLISH_QUIET_PROPERTY_NAME,
    value = "true"
)
```

**junit-platform.properties:**
```properties
cucumber.publish.quiet=true
```

## Output Formatting

### ANSI Colors

Disable colored console output:

```java
@ConfigurationParameter(
    key = ANSI_COLORS_DISABLED_PROPERTY_NAME,
    value = "true"
)
```

**junit-platform.properties:**
```properties
cucumber.ansi-colors.disabled=true
```

### Monochrome Output

```properties
cucumber.plugin=pretty,monochrome
```

### Snippet Type

Configure generated snippet style:

```properties
# Camelcase (recommended for Java)
cucumber.snippet-type=camelcase

# Underscore
cucumber.snippet-type=underscore
```

## Object Factory

### Custom Object Factory

For dependency injection:

```java
@ConfigurationParameter(
    key = OBJECT_FACTORY_PROPERTY_NAME,
    value = "com.example.CustomObjectFactory"
)
```

**junit-platform.properties:**
```properties
cucumber.object-factory=com.example.CustomObjectFactory
```

**Common factories:**
- PicoFactory (default)
- Spring
- Guice
- OpenEJB
- Weld

## JUnit Platform Integration

### Test Discovery

```properties
# Include/exclude test classes
junit.jupiter.testclass.include.classname.pattern=.*IT
junit.jupiter.testclass.exclude.classname.pattern=.*IntegrationTest

# Include/exclude test methods
junit.jupiter.testmethod.include.pattern=test.*
junit.jupiter.testmethod.exclude.pattern=.*Slow
```

### Parallel Execution (JUnit Level)

```properties
junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=concurrent
junit.jupiter.execution.parallel.mode.classes.default=concurrent
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=1.0
```

## Complete Configuration Example

### Comprehensive junit-platform.properties

```properties
# ==========================================
# Serenity BDD Configuration
# ==========================================
cucumber.plugin=net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel

# ==========================================
# Feature Files and Step Definitions
# ==========================================
cucumber.features=src/test/resources/features
cucumber.glue=com.example.stepdefinitions,com.example.hooks

# ==========================================
# Filtering
# ==========================================
cucumber.filter.tags=not @wip
cucumber.filter.name=.*checkout.*

# ==========================================
# Parallel Execution
# ==========================================
cucumber.execution.parallel.enabled=true
cucumber.execution.parallel.config.strategy=dynamic
cucumber.execution.parallel.config.dynamic.factor=1.0

# ==========================================
# Execution Behavior
# ==========================================
cucumber.execution.order=random
cucumber.execution.dry-run=false
cucumber.execution.strict=true

# ==========================================
# Plugins and Reporting
# ==========================================
cucumber.plugin=pretty,\
  html:target/cucumber-reports/cucumber.html,\
  json:target/cucumber-reports/cucumber.json,\
  junit:target/cucumber-reports/cucumber.xml
cucumber.publish.quiet=true

# ==========================================
# Output Formatting
# ==========================================
cucumber.ansi-colors.disabled=false
cucumber.snippet-type=camelcase

# ==========================================
# JUnit Platform
# ==========================================
junit.jupiter.execution.parallel.enabled=false
junit.jupiter.testinstance.lifecycle.default=per_method
```

### Complete Test Suite Example

```java
import org.junit.platform.suite.api.*;
import static io.cucumber.junit.platform.engine.Constants.*;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"
)
@ConfigurationParameter(
    key = GLUE_PROPERTY_NAME,
    value = "com.example.stepdefinitions"
)
@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "@smoke and not @wip"
)
@ConfigurationParameter(
    key = PLUGIN_PUBLISH_QUIET_PROPERTY_NAME,
    value = "true"
)
class CucumberTestSuite {
}
```

## Environment-Specific Configuration

### Using Profiles

Create multiple properties files:

```
src/test/resources/
├── junit-platform.properties (default)
├── junit-platform-ci.properties (CI environment)
└── junit-platform-dev.properties (development)
```

Activate via Maven:
```bash
mvn verify -Dprofile=ci
```

### Environment Variables

Override properties using environment variables:

```bash
export CUCUMBER_FILTER_TAGS="@smoke"
export CUCUMBER_EXECUTION_PARALLEL_ENABLED=true
mvn verify
```

## Constants Reference

All constants from `io.cucumber.junit.platform.engine.Constants`:

| Constant | Property Key |
|----------|--------------|
| `ANSI_COLORS_DISABLED_PROPERTY_NAME` | `cucumber.ansi-colors.disabled` |
| `EXECUTION_DRY_RUN_PROPERTY_NAME` | `cucumber.execution.dry-run` |
| `EXECUTION_ORDER_PROPERTY_NAME` | `cucumber.execution.order` |
| `EXECUTION_STRICT_PROPERTY_NAME` | `cucumber.execution.strict` |
| `FEATURES_PROPERTY_NAME` | `cucumber.features` |
| `FILTER_NAME_PROPERTY_NAME` | `cucumber.filter.name` |
| `FILTER_TAGS_PROPERTY_NAME` | `cucumber.filter.tags` |
| `GLUE_PROPERTY_NAME` | `cucumber.glue` |
| `OBJECT_FACTORY_PROPERTY_NAME` | `cucumber.object-factory` |
| `PLUGIN_PROPERTY_NAME` | `cucumber.plugin` |
| `PLUGIN_PUBLISH_ENABLED_PROPERTY_NAME` | `cucumber.publish.enabled` |
| `PLUGIN_PUBLISH_QUIET_PROPERTY_NAME` | `cucumber.publish.quiet` |
| `PLUGIN_PUBLISH_TOKEN_PROPERTY_NAME` | `cucumber.publish.token` |
| `SNIPPET_TYPE_PROPERTY_NAME` | `cucumber.snippet-type` |

## Next Steps

- Return to the main [Cucumber with JUnit 5](cucumber-junit5) guide
- Learn about [Parallel Execution](parallel-execution)
- Review [Best Practices](cucumber-junit5#best-practices)

## Additional Resources

- [Cucumber Configuration Docs](https://github.com/cucumber/cucumber-jvm/tree/main/cucumber-junit-platform-engine#configuration-options)
- [JUnit Platform Configuration](https://junit.org/junit5/docs/current/user-guide/#running-tests-config-params)


---

<!-- https://serenity-bdd.github.io/docs/screenplay/screenplay_fundamentals -->

# Screenplay Fundamentals

The Screenplay Pattern is a modern test automation design pattern intented to make it easier to write scalabble, maintainable test code. You can get a quick overview of a simple Screenplay test [here](../../docs/tutorials/screenplay).

In this section, we will look at how to write high quality test automation using the Screenplay pattern in more detail. We will intially focus on interacting with a web application using Selenium - in the following sections, we will see how to interact with APIs and databases using the Screenplay model.

In Screenplay we model _actors_ who interact with an application in various ways to perform _tasks_ that help them acheive their goals. Actors have _abilities_, such as the ability to interact with a web browser or query a database, that help them perform these tasks. Actors can also answer _questions_ about the state of the system, so that we can check whether a feature is behaving the way we would expect it to.

![](img/screenplay-model.svg)

## Setting up a Screenplay test
Serenity BDD Screenplay tests can be written using any framwork that works with Serenity BDD. We will start by discussing how to set up a simple Serenity Screenplay test case using common libraries such as JUnit 4, JUnit 5 and Cucumber.

### Screenplay and JUnit 4

Running a Screenplay test in JUnit 4 and JUnit 5 is no different to any other Serenity BDD test. For JUnit 4, add the `serenity-junit` dependency to your project if it is not already there:
```xml
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-junit</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay-webdriver</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
```

### Screenplay and JUnit 5 (Recommended)

For JUnit 5, add the following dependency to your project:
```xml
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-junit5</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay-webdriver</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
```
Next, you need to use the `SerenityJUnit5Extension` class, like this:
```java
import net.serenitybdd.junit.runners.SerenityJUnit5Extension;
import org.junit.jupiter.api.Test;

@ExtendWith(SerenityJUnit5Extension.class)
class AddNewTodos {

    @Test
    @DisplayName("Add a todo item to an empty list")
    void addToEmptyList() {...}
}
```

### Screenplay and JUnit 4 (Deprecated)

:::warning JUnit 4 Deprecated
JUnit 4 support is deprecated as of Serenity 5.0.0 and will be removed in Serenity 6.0.0. Please migrate to JUnit 5 (see above).
:::

If you're still using JUnit 4, use the `SerenityRunner` class in your test class, like this:

```java
import net.serenitybdd.junit.runners.SerenityRunner;
import org.junit.Test;

@RunWith(SerenityRunner.class)
public class AddNewTodos {

    @Test
    public void addToEmptyList() {...}
}
```

### Screenplay and Cucumber

To run a Screenplay scenario with Cucumber and Serenity, you just need the standard Screenplay dependencies along with the `serenity-cucumber` dependency, as shown below:
```xml
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-cucumber</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-screenplay-webdriver</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
```

#### With JUnit 5 (Recommended)

For JUnit 5, use the `@Suite` annotation with the Cucumber JUnit Platform Engine:

```java
import org.junit.platform.suite.api.*;

import static io.cucumber.junit.platform.engine.Constants.PLUGIN_PROPERTY_NAME;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel"
)
class TestSuite {}
```

#### With JUnit 4 (Deprecated)

:::warning JUnit 4 Deprecated
JUnit 4 Cucumber runners are deprecated as of Serenity 5.0.0 and will be removed in Serenity 6.0.0. Please migrate to JUnit 5 (see above).
:::

For JUnit 4, you would use:

```java
import io.cucumber.junit.CucumberOptions;
import net.serenitybdd.cucumber.CucumberWithSerenity;
import org.junit.runner.RunWith;

@RunWith(CucumberWithSerenity.class)
@CucumberOptions(
        features = "classpath:features"
)
public class TestSuite {}
```

## Defining the actors

Every Screenplay test needs at least one actor (and some have several). There are several ways we can define an actor, which vary slightly depending on the test framework you are using.

### Actors in JUnit

One way to create a new actor is to use the `Actor.named()` method. For example, to create an actor named Toby, we could write the following:

```java
Actor toby = Actor.named("Toby");
```

However this actor will not be able to do very much until we give him the ability to interact with our application. That's where _abilities_ come into play.

The most commonly-needed ability is the ability to browse the web using a web automation library such as Selenium or Playwright. In a Serenity JUnit test, we can use the `@Managed` annotation to manage the WebDriver lifecycle. Once we have a driver available, we can assign it to an actor using the `BrowseTheWeb` class like this:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class AddNewTodosWithAManagedDriver {

    @Managed
    WebDriver driver;

    @Test
    @DisplayName("Add a todo item to an empty list")
    void addToEmptyList() {
        Actor toby = Actor.named("Toby")
                          .whoCan(BrowseTheWeb.with(driver));
    ...
    }
}
```

### Defining actors using the CastMember annotation

For many scenarios we can simplify this code shown above. If we just need to use an actor who can interact with a website using Selenium, we can use the `@CastMember` annotation. This annotation will configure an actor with a WebDriver instance, and manage the browser lifecycle for us (so no need for the `@Managed` annotation or `WebDriver` variable). You can see an example of this annotation in action here:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class AddNewTodosWithACastMember {

    @CastMember
    Actor toby;

    @Test
    @DisplayName("Add a todo item to an empty list")
    void addToEmptyList() {

        toby.attemptsTo(
                Open.browserOn().the(TodoMvcPage.class),
                Enter.theValue("Buy some milk").into(".new-todo").thenHit(Keys.RETURN)
        );
        Collection<String> items = toby.asksFor(Text.ofEach(".todo-list label"));
        assertThat(items).containsExactly("Buy some milk");

        String title = toby.asksFor(Text.of(By.tagName("h1")));
        assertThat(title).isEqualTo("todos");
    }
}
```

The name of the actor will be derived from the name of the variable. If you need a more descriptive name, you can use the `name` attribute to provide a free text value, which will be used in the reports:

```java
    @CastMember(name = "Tim the Enchanter")
    Actor tim;
```

### Actors in Cucumber

Setting up actors in Cucumber is a little more compicated than in JUnit, because we generally refer to them by name in the Cucumber scenarios. Suppose for example we want to automate the following scenario:

```gherkin
  Scenario: Add items to an empty list
    Given Toby starts with an empty list
    When he adds "Buy some milk" to his list
    Then the todo list should contain the following items:
      | Buy some milk |
```

#### Using a Managed driver with Cucumber
We can use the same approach as we used for JUnit in our Cucumber step definition files, declaring a Webdriver instance using the `@Managed` annotation and assigning it to our actor using the `BrowseTheWeb` ability class:

```java
public class TodoStepDefinitions {

    @Managed
    WebDriver driver;

    Actor toby = Actor.named("Toby");

    @Before
    public void setupActor() {
        toby.can(BrowseTheWeb.with(driver));
    }

    @Given("Toby starts with an empty list")
    public void stats_with_an_empty_list() {
        toby.attemptsTo(
                Open.url("https://todomvc.com/examples/angularjs/#/")
        );
    }
```

However, the name of the actor ("Toby") is part of the scenario steps. We may want to have other scenarios with other actors, or have a scenario involving more than one actor. 

#### Casts and Stages
We can make our Cucumber step definitions more flexible by introducing the concept of a _Cast_ of actors, and a _stage_ on which they perform. 

A _Cast_ is a class whose job is to provide actors with a specific set of abilities, when we need them to play a role in our tests. For example, we can use the `OnlineCast` class to provide actors who are equiped with their own Webdriver instances. This way, we don't need to declare the `@Managed` driver, and each actor can have their own browser if we have a scenario with more than one actor.

A _stage_ is where our actors perform their roles. A scenario has a single stage, that we can use to identify an actor by name or find the currently active actor. 

We need to assign a cast to the stage at the start of each scenario; we can do this by calling the `OnStage.setTheStage()` method and passing in a specific cast, like this:

```java
OnStage.setTheStage(new OnlineCast());
```

Once we have set the stage, we can obtain an actor with a given name using the `OnStage.theActorCalled()` method, like this:
```java
Actor toby = OnStage.theActorCalled("Toby");
```

Using this approach, we could implement the first step of our scenario in a way that will work no matter which actor is involved, like this:
```java
    @Given("{word} starts with an empty list")
    public void stats_with_an_empty_list(String actorName) {
        Actor actor = OnStage.theActorCalled(actorName);
        actor.attemptsTo(
                Open.url("https://todomvc.com/examples/angularjs/#/")
        );
    }
```

It is often useful to define a custom Cucumber expression so that we don't have to call the `OnStage.theActorCalled()` method each time:
```java
    @ParameterType(".*")
    public Actor actor(String actorName) {
        return OnStage.theActorCalled(actorName);
    }

    @Given("{actor} starts with an empty list")
    public void stats_with_an_empty_list(Actor actor) {
        actor.attemptsTo(
                Open.url("https://todomvc.com/examples/angularjs/#/")
        );
    }
```

This way, our next step can simply use a parameter of type `Actor`, like this:
```java
    @When("{actor} adds {string} to his list")
    public void he_adds_to_his_list(Actor actor, String item) {
        actor.attemptsTo(
                Enter.theValue(item).into(".new-todo").thenHit(Keys.RETURN)
        );
    }
```

These methods are defined out-of-the-box with the Serenity Cucumber Starter template on Github, so you don't need to add them yourself if you are using this template.

The `OnStage` class also recognises pronouns - when an expression such as "he adds 'Walk the dog' to the todo list" or "her shopping cart should be empty", the `theActorCalled()` method will recognise the pronoun and fetch the last active actor with the `theActorInTheSpotlight()` method. By default, the pronouns are:
    - he
    - she
    - they
    - it
    - his
    - her
    - their
    - its
You can define your own list of pronouns using the `screenplay.pronouns` Serenity property in the `serenity.conf` file, e.g.

```conf
screenplay.pronouns=il,elle,ils,elles,son,sa,leur,leurs
```

#### Casts and Abilities

In the previous code, we used the `OnlineCast` class to define the cast of actors:

```java
OnStage.setTheStage(new OnlineCast());
```

Casts are very flexible, and we can set them up to produce actors with additional abilities if we need to.

For example, imagine we wanted to give our actors the ability to deliver some coffee. To do this, we can create a `Deliver` ability class. To deliver a coffee, we will call the `deliverItem()` method, which will (for our purposes) simply return a string with an item with a unique number (such as "Coffee #1").

The Ability class could look like this:

```java
    public class Deliver implements Ability {
        final String item;
        private int counter = 1;

        private Deliver(String item) {
            this.item = item;
        }

        public static some(String item) {
            return new Deliver(item)
        }

        public String deliverItem() {
            return item + " #" + counter++;
        }
    }
```

Now we can assign this ability to our actors in the `Cast` by using the `Cast.whereEveryoneCan()` method:

```java
OnStage.setTheStage(
    Cast.whereEveryoneCan(Fetch.some("Coffee"))
);
```

If we needed a more complex setup, we can also use a Lambda expression to provide the code we need to execute to enhance a new actor with additional abilities, like this: 

```java
Consumer<Actor> fetchTheCoffee = { actor -> actor.whoCan(Fetch.some("Coffee")) }

OnStage.setTheStage(
    Cast.whereEveryoneCan(fetchTheCoffee)
);
```


#### The Actor in the spotlight

Sometimes a step does not refer to an actor by name, but implicitly refers to the last actor who did anything in the scenario. For example, the third step, "Then the todo list should contain the following items..." does not have an explicit actor. 

In these situations, we can use the `OnStage.theActorInTheSpotlight()` method to refer to the last known active actor. For example, we could implement the third step of our scenario like this:

```java
    @Then("the todo list should contain the following items:")
    public void the_todo_list_should_contain(List<String> expectedItems) {
        Actor currentActor = OnStage.theActorInTheSpotlight();
        var todos = currentActor.asksFor(Text.ofEach(".todo-list li"));
        assertThat(todos).containsExactlyElementsOf(expectedItems);
    }
```

## Grouping interactions into tasks

Screenplay aims to make it easy to write maintainable and scaleable automation code. And an important way to do this is by grouping interactions into reusable sequences that represent higher level domain concepts.

For example, the following test shows how to login to the https://www.saucedemo.com/ test site:

```java
        toby.attemptsTo(
                Open.url("https://www.saucedemo.com/"),
                Enter.theValue("standard_user").into("#user-name"),
                Enter.theValue("secret_sauce").into("#password"),
                Click.on("#login-button")
        );
```

These four lines involve all login in to the site. However it is hard to see that at a glance when reading the code. We could make this code much more readable by grouping these interactions into a single task. 

### Grouping interactions using the Task class
A better approach would be to group these related interactions into a single `Task`. 

The simplest way to do this is to use the `Task.where()` method. This method lets us return a task (or more precisely, an implementation of the `Performable` interface) that combines several other tasks or interactions. 

The task that allows an actor to login as a standard user could look like this:

```java
public class Login {
    public static Task asAStandardUser() {
        return Task.where(
                Open.url("https://www.saucedemo.com/"),
                Enter.theValue("standard_user").into("#user-name"),
                Enter.theValue("secret_sauce").into("#password"),
                Click.on("#login-button")
        );
    }
}
```

We might want to make our task more configurable, by adding some parameters to the method signature. In this case, it is useful to make our task more descriptive by adding a text description before the list of _Performable_s, as shown below. This description will appear in the reports whenever the task is executed. The `{0}` in the description will be replaced by the name of the actor (so "Toby" in our test). 

```java
public class Login {
    public static Performable as(String username, String password) {
        return Task.where(
                "{0} logs in as " + username,
                Open.url("https://www.saucedemo.com/"),
                Enter.theValue(username).into("#user-name"),
                Enter.theValue(password).into("#password"),
                Click.on("#login-button")
        );
    }
}
```

We can now refactor our original test using this method:

```java
        toby.attemptsTo(Login.asAStandardUser());
```

or

```java
        toby.attemptsTo(Login.as("standard_user","secret_sauce"));
```

### Using lambda expressions to create custom tasks

So far we havce seen how to create a _Task_ from a list of other tasks or interactions. But sometimes we need to have more control over the logic of our task. We can do this very easily using lambda expressions, which give us total control over how our task should work. 

For example, imagine we have refactored our TodoMVC example above to use the following Task class to open the TodoMVC application with an empty list:

```java

public class Start {
    public static Performable withAnEmptyTodoList() {
        return Task.where("{0} starts with an empty todo list",
                Open.url("https://todomvc.com/examples/angularjs/#/")
        );
    }
```

We could also create a task to add a todo item to the list:

```java
public class AddATodoItem {
    public static Performable called(String thingToDo) {
        return Task.where("{0} adds a todo item called " + thingToDo,
                Enter.theValue(item).into(".new-todo").thenHit(Keys.RETURN)
        );
    }
}
```

Now suppose we want to allow Toby to start with some elements already in his list. We could imagine a new `Start.withAListContainingTheItems(...)` method like this:

```java
        toby.attemptsTo(
                Start.withAListContaingTheItems("Feed the cat","Buy some bread")
        );
```

However to implement this method, we need to loop over the provided list of items, and call the `AddATodoItem` task for each of them. We can do this by using a Lambda expression instead of a list of _Performable_s. The Lambda expression takes an actor as a parameter, and allows us to write arbitrary blocks of code to implement our task. For example, the `withAListContaingTheItems()` method might look like the following:

```java
    public static Performable withAListContainingTheItems(String... items) {
        return Task.where("{0} starts with a list containing " + Arrays.asList(items),
                actor -> {
                    actor.attemptsTo(Start.withAnEmptyTodoList());
                    for (String item : items) {
                        actor.attemptsTo(AddATodoItem.called(item));
                    }
                }
        );
```

The full `Start` class would now look like this:

```java
public class Start {
    public static Performable withAnEmptyTodoList() {
        return Task.where("{0} starts with an empty todo list",
                Open.url("https://todomvc.com/examples/angularjs/#/")
        );
    }

    public static Performable withAListContainingTheItems(String... items) {
        return Task.where("{0} starts with a list containing " + Arrays.asList(items),
                actor -> {
                    actor.attemptsTo(Start.withAnEmptyTodoList());
                    for (String item : items) {
                        actor.attemptsTo(AddATodoItem.called(item));
                    }
                }
        );
    }
}

```

### Writing custom Performable classes.

Sometimes we need more control over the creation of a Task. We can do this by creating a class that implements the `Performable` interface. 

The `Performable` interface has a single method that you need to implement: `performAs()`. This method takes an `Actor` as a parameter. A very simple custom task might look like this:

```java
public class AddItem implements Performable {
    @Override
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
                Enter.theValue("Buy some milk")
                        .into(".new-todo")
                        .thenHit(Keys.RETURN)
        );
    }
}
```

Now we can use this class directly in our tests:

```java
    AddItem addANewItem = new AddItem();
    toby.attemptsTo(addANewItem);
```

By default, Serenity will record this action in the reports using the name of the actor and the name of the class, so in this case, the report would include something like "Toby add item". If we want a more descriptive text, we can add the `@Step` annotation to the `performAs()` method, as shown here (the "{0}" placeholder will be replaced by the name of the actor):

```java
public class AddItem implements Performable {
    @Override
    @Step("{0} adds an item to the list")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
                Enter.theValue("Buy some milk")
                        .into(".new-todo")
                        .thenHit(Keys.RETURN)
        );
    }
}
```

In this class, we can only add the item "Buy some milk" to our list. We could make our class more flexible by recordinh the name of the task as a parameter. To do this, we need to add a member variable to our `Performable` to represent this value, and pass it in to the constructor:

```java
public class AddItem implements Performable {
    private String name;

    public AddItem(String name) {
        this.name = name;
    }

    @Override
    @Step("{0} adds an item to the list")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
                Enter.theValue(name)
                        .into(".new-todo")
                        .thenHit(Keys.RETURN)
        );
    }

    public static AddItem called(String name) {
        return new AddItem(name);
    }
}
```

We can now make our test code more readable, as shown here:
```java
    toby.attemptsTo(AddItem.named("Walk the dog"));
```

However there is one more thing we need to do to make this work correctly. The code shown here will not be correctly reported in the Serenity reports. For technical reasons, every `Performable` implementation must have a default constructor, even if you don't use it directly in your code. So the complete implementation will look like this:

```java
public class AddItem implements Performable {
    private String name;

    public AddItem() {}

    public AddItem(String name) {
        this.name = name;
    }

    @Override
    @Step("{0} adds an item to the list")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
                Enter.theValue(name)
                        .into(".new-todo")
                        .thenHit(Keys.RETURN)
        );
    }

    public static AddItem called(String name) {
        return new AddItem(name);
    }
}
```

:::tip
Always remember to add a default constructor with no parameters to your `Performable` implementations, otherwise they will not appear correctly in the reports.
:::

## Questions - querying the state of the system

Screenplay is an actor-centric pattern, and just as actors interact with the system by performing _tasks_ and _interactions_, they can query the state of the system by asking _questions_.

### Using bundled Question classes
An actor can ask a question by using the `askFor()` method. You can see an example of how this works here:

```java
   String pageTitle = toby.asksFor(Text.of(".title"));
```

`Text` is an example of a _Question Factory_. Question Factories provide a convenient way to query the state of the application, and there are many to choose from. For example, we could check whether a particular web element was visible using the `Visibility` class, like this:

```java
   boolean isVisible = toby.asksFor(Visibility.of(".title"));
```

Serenity BDD comes with lot bundled _Question Factories_ like these, and we will look at them in more detail in the next section. But you can also write your own custom questions, to query any aspect of your application that you like.

### Creating custom Questions using Lambda expressions
One way to implement a _Question_ is to use a Java 8 Lambda expression that takes an _Actor_ as an argument. For example, the following method returns an _Integer Question_ (a _Question_ that returns an integer). 

```java
    Question<Integer> numberOfTodoItems() {
        return actor -> BrowseTheWeb.as(actor).findAll(".todo-list li").size();
    }
```

We could find the answer to this question using the `asksFor()` method, as in the previous example:
```java
   int numberOfTodos = toby.asksFor(numberOfTodoItems());
```

An alternative to the `asksFor()` method is the `Question`'s own `answeredBy()` method:

```java
   int numberOfTodos = numberOfTodoItems().answeredBy(toby);
```

This format can be more convenient for assertions, as illustrated in this example:

```java
   assertThat(numberOfTodoItems().answeredBy(toby)).isEqualTo(1);
```

### Making questions more readable with the `Question.about()` method
We could make this method more readable by using the `Question.about` format - this will produce a more meaningful error message. In the following example, we use the `BrowseTheWeb` class to access the Serenity WebDriver API and find the number of todo list items currently on the page:

```java
    Question<Integer> numberOfTodoItems() {
        return Question.about("the number of todo items")
                   .answeredBy(
                       actor -> BrowseTheWeb.as(actor).findAll(".todo-list li").size());
    }
```

### Converting Questions

Questions also provide a convenient way to convert responses into different types. This is particularly useful for the bundled WebDriver `Question` classes, that typically return values in text form. 

For example, the TodoMVC application shows the number of items remaining to do at any time beneath the list:

![](img/items-left.png)

We can locate the item count using the CSS expression _".todo-count strong"_. We could fetch this value as a String using the `Text` class we saw previously:

```java
    String itemsLeftCount = toby.asksFor(Text.of(".todo-count strong");
```

However if we prefer to retrieve the value as an integer, we could use the `asInteger()` method like this:

```java
   int itemsLeftCount = toby.asksFor(Text.of(".todo-count strong").asInteger());
```

Some of the conversion methods available include the following:

| Type         | Method         | Example     |
| ------------ | -----------    | ----------- |
| Integer      | asInteger()    | Text.of(".todo-count strong").asInteger()    |
| Long         | asLong()       | Text.of(".todo-count strong").asLong()       |
| Float        | asFloat()      | Text.of(".currency-value").asFloat()         |
| Double       | asDouble()     | Text.of(".currency-value").asDouble()        |
| BigDecimal   | asBigDecimal() | Text.of(".currency-value").asBigDecimal() |

### Converting date values
Date values can also be converted to `LocalDate` objects. If the date uses the standard ISO date format (e.g. "2022-05-15"), it can be converted using the `asDate()` method, like this:

```java
   LocalDate dateValue = toby.asksFor(
       Text.of("#departure-date").asDate()
    );
```

If the date uses a different format, the `asDate()` method takes a date-time pattern that can be used to parse the value, e.g.

```java
    LocalDate dateValue = toby.asksFor(
        Text.of("#departure-date").asDate("d MMM uuuu")
    );
```

### Converting to lists of values

We can also use the `asListOf()` method to find all the answers to a specific question, and convert each of them to a specified type. For example, to convert a list of matching String values to integers, we could use the following code:

```java
    List<Integer> itemQuantities = toby.asksFor(
        Text.of(".item-quantity").asListOf(Integer.class)
    );
```

### Working with collections

Another way to retrieve a list of values is to use the `ofEach()` method. 

```java
    Collection<String> itemQuantities = toby.asksFor(Text.of(".item-quantity"));
```

As with the `Text.of()` method, we can use the `asListOf()` method to convert this collection into another type

```java
    List<String> itemQuantities = toby.asksFor(
        Text.of(".item-quantity").asListOf(Integer.class)
    );
```

If we need to perform a more complex operation, we can use the `mapEach()` method to apply an arbitrary Lambda expression to each matching element:

```java
   Collection<Integer> nameLengths = toby.asksFor(Text.ofEach(".name").mapEach(s -> s.length()));
```

## Actor-specific session data

Sometimes we need to store information in a step or task and reuse it in a subsequent one. Each Screenplay actor can remember information, and retrieve it later on in the test. We do this using the `remember()` method:

```java
    int actualCost = 100
    actor.remember("Total Cost", total);
```

Later on, we can retrieve this information using the `recall()` method:
```java
    int recalledCost = dana.recall("Total Cost");
    assertThat(recalledCost).isEqualTo(100);
```

An actor can remember information of any type, even the answer to a question. For example,the `Text.of()` method returns a Question object of type `Question<String>`. An actor can remember the answer to this question by using it as a parameter to the `remember()` method:

```java
    actor.remember("Total Cost", Text.of("#total-cost").asInteger());
```

We can then recall this value in the same way as any other:

```java
    int totalCost = actor.recall("Total Cost");
    assertThat(totalCost).isEqualTo(100);
```

We can even recall a map containing every value currently remembered by the actor. We do this using the `recallAll()` method:

```java
    Map<String, Object> all = actor.recallAll();
```

We can also remove a remembered value using the `forget()` method:

```java
    actor.forget("Total Cost");
```

## Conclusion
Now that we have seen how to set up a Screenplay test using different frameworks, how to organise interactions into tasks, and how to query the state of the system, we will look at how to use Screenplay to interact with a web application in more detail.


---

<!-- https://serenity-bdd.github.io/docs/screenplay/screenplay_webdriver -->

# Web Testing with Serenity Screenplay
## Introduction
Web tests are a common use case for Screenplay scenarios, where we try to model user behaviour and interactions with the system. In this section, we will learn how to interact with a web application using the Screenplay WebDriver integration.

## Opening a URL

### Opening a URL directly
In Screenplay, you open a new page using the `Open` interaction class. This can work with a URL, e.g:

```java
toby.attemptsTo(Open.url("https://todomvc.com/examples/angularjs/#/"));
```

### Opening the URL of a Page Object
If you have defined a Page Object with a default url, you can open a page object by referring to the page object class. Suppose we have defined the following Serenity Page Object, and set the `@DefaultUrl` value to the TodoMVC application URL:

```java
@DefaultUrl("https://todomvc.com/examples/angularjs/#/")
public class TodoMvcPage extends PageObject {}
```

We can now open this page using the `Open.browserOn()` method, like this:

```java
toby.attemptsTo(Open.browserOn().the(TodoMvcPage.class));
```

### Using named pages

Sometimes it can be convenient to store the URLs for different environments or servers in the `serenity.conf` file, and refer to them by the name of the property in our test code. 

For example, imagine we wanted to run our tests against the Angular, React and Polymer implementations of the TodoMVC app. Each application has a different URL, that we could store in the `serenity.conf` file like this:

```json
pages {
    angular = "https://todomvc.com/examples/angularjs/#/"
    react = "https://todomvc.com/examples/react/#/"
    polymer = "https://todomvc.com/examples/polymer/index.html"
}
```

Next, we can refer to these properties in our code using the `thePageNamed()` method, like this:

```java
toby.attemptsTo(Open.browserOn().thePageNamed("pages.react"));
```

## Locating elements on a page

In Screenplay, you can use several different strategies to locate the elements you need to interact with. 

### CSS and XPath

The simplest way to locate an element is to use a CSS or XPath expression, as shown here:

```java
toby.attemptsTo(
    Click.on("#login-button")
);
```

Or

```java
toby.attemptsTo(
    Click.on("//input[@id='login-button']")
);
```

Serenity will interpret the string to determine whether it is an XPath or CSS expression. In some cases there may be some ambiguity, and Serenity will default to XPath. If this is not intended, you can use the "xpath:" or "css:" prefixes to specify which type of locator you mean:

```java
toby.attemptsTo(
    Click.on("css:input[name=login-button]")
);
```


### Using Selenium locators
You can also use any of the standard Selenium locator (`org.openqa.selenium.By`) classes, as shown here:

```java
toby.attemptsTo(
    Click.on(By.id("login-button"))
);
```

### Using the Target class

Using text or `By` locators has the advantage of being concise, but it can lead to poorly readable test reports, especially when complex or non-meaningful XPath or CSS locators are used. In Screenplay, the `Target` class allows us to give a locator strategy a more meaningful name. For example, consider the following code:

```java
toby.attemptsTo(Click.on("//button[.='Add']"));
```

In the Serenity reports, this step will be reported as "Toby clicks on //button[.='Add']", which is not very readable. 

If we represent this button using the `Target` class, we can associate a label such as "Add to cart button", like this:

```java
Target ADD_TO_CART = Target.the("Add to cart button").located(By.cssSelector("//button[.='Add']"));

toby.attemptsTo(Click.on(ADD_TO_CART));
```

In the reports, this step will now appear as "Toby clicks on Add to cart button".

### Using dynamic targets

You can also include variables into a `Target` locator, to make your locators dynamic. You can include numbered paramaters using "{0}", "{1}", etc, and then use the `of()` method to instantiate the `Target with the value you are interested in. For example, we could create a generic locator for a button containing a given text like this:

```java
Target BUTTON_WITH_LABEL = Target.the("{0} button").located(By.cssSelector("//button[.='{0}']"));

toby.attemptsTo(Click.on(BUTTON_WITH_LABEL.of('Add')));
```

We could even use this dynamic target to define other targets with specific values, like this:

```java
Target BUTTON_WITH_LABEL = Target.the("{0} button").located(By.cssSelector("//button[.='{0}']"));
Target ADD_BUTTON = BUTTON_WITH_LABEL.of('Add');

toby.attemptsTo(Click.on(ADD_BUTTON));
```

### Using Page Elements

Serenity [Page Elements](../../docs/guide/page_elements) provide a more intuitive and readable way to locate elements on a page, often without needing to use XPath or CSS. With Page Elements, you can identify elements using expressions such as the following
  - `Click.on(Button.withText("Add to cart"))`
  - `Enter.theValue(").into(InputField.withPlaceholder("Enter the customer name"))`
  - `Click.on(PageElement.locatedBy(".item").containingText("Bananas"))`

You can learn more about Page Elements [here](../../docs/guide/page_elements).

## Interacting with elements

In this section we will see how to interact with elements on a web page using Selenium WebDriver with Serenity Screenplay.

### Screenplay Interaction classes
You can find the standard Serenity interaction classes in the `net.serenitybdd.screenplay.actions` package.
 
| Interaction                    | Purpose              | Example     |
| -----------                    | --------             | ----------- |
| Clear                          | Clear an input field | `actor.attemptsTo(Clear.field("#firstname"))`           |
| Click                          | Click on an element  | `actor.attemptsTo(Click.on("#add-to-cart"))`           |
| DoubleClick | Double-click on an element using a Selenium Action | `actor.attemptsTo(DoubleClick.on("#add-to-cart"))`           |
| Enter                          | Type a value into an input field  | `actor.attemptsTo(Enter.theValue("scott").into("#username"))`           |
| Evaluate                       | Evaluate a Javascript expression  | `actor.attemptsTo(Evaluate.javascript("window.localStorage.clear();")`           |
| Hit                            | Press a key  | `actor.attemptsTo(Hit.the(Keys.ENTER).into("#searchterms"))`           |
| JavaScriptClick                | Click on an element using Javascript rather than Selenium | `actor.attemptsTo(JavaScriptClick.on("#add-to-cart"))`           |
| MoveMouse                      | Move the mouse over a specified element | `actor.attemptsTo(MoveMouse.to("#main-menu"))`           |
| Open | Open a specific URL or page | `actor.attemptsTo(Open.url("https://www.google.com"))`|
| PerformOn | Perform one or more actions on several elements | See below |
| RightClick | Right-click on a given element | `actor.attemptsTo(RightClick.on("#menu"))` |
| Scroll | Scroll to an element using Javascript | `actor.attemptsTo(Scroll.to("#terms-and-conditions"))` |
| SelectFromOptions | Select a value in an HTML dropdown | `actor.attemptsTo(SelectFromOptions.byVisibleText("Red").from("#color"))` |
| SendKeys | Enter a value into a field using the Selenium sendKeys() method |`actor.attemptsTo(SendKeys.of("scott").into("#username"))`           | 
| SetCheckbox                  | Check a checkbox field | `actor.attemptsTo(SetCheckbox.of("#subscribe-to-newsletter").toTrue())`           |
| Switch   | Switch to another window or tab | `actor.attemptsTo(Switch.toNewWindow())`           |
| Upload    | Upload a file using an HTML upload field |  `actor.attemptsTo(Upload.theFile(pathToFile)).to("#uploaded-file"))`           |
| WithDevTools | Perform an action with the Chrome DevTools | See below |

The more important interactions are described in more detail in the following sections.

### Clear

The `Clear` interaction resets the value of an HTML form element.

```java
        dina.attemptsTo(Clear.field(By.id("first-name")));
```

### Click

Click on a button or element.

```java
        dina.attemptsTo(Click.on("#some-button"));
```

Sometimes an element is not in an interactable state when we first attempt to click on it. For example, it may be disabled, or not yet visible on the page. In these cases, we can ask Serenity to wait for the element to be enabled using the `afterWaitingUntilEnabled()` method:

```java
        dina.attemptsTo(Click.on("#some-button").afterWaitingUntilEnabled());
```

If the element is not yet rendered, we can use the `afterWaitingUntilPresent()` method:

```java
        dina.attemptsTo(Click.on("#some-button").afterWaitingUntilPresent());
```

In both these cases, Serenity will wait for up to 5 seconds by default for the element to be present or available. You can configure this timeout using the `webdriver.wait.for.timeout` system property (defined in milliseconds).

### DoubleClick

Double-click on a button or element, using Selenium Actions.

```java
        dina.attemptsTo(DoubleClick.on("#some-button"));
```

### Enter and SendKeys

There are two ways to enter a value into a field. 

`Enter` will enter a value into a field, first waiting until the field is enabled, and then clearing the field of any current values, before entering the specified value.

```java
        dina.attemptsTo(Enter.theValue("Sarah-Jane").into("#firstName"));
```

`SendKeys` will perform the equivalent of Selenium `sendKeys()`, you can use `Enter.keyValue()` instead of `Enter.theValue()`

```java
        dina.attemptsTo(SendKeys.of("Sarah-Jane").into("#firstName"));
```

### Evaluate a Javascript expression

The `Evaluate` task executes a JavaScript command in the context of the currently selected frame or window. For example, the following code will clear the local storage in Dina's browser:

```java
dina.attemptsTo(Evaluate.javascript("window.localStorage.clear()"));
```

If the script has a return value (i.e. if the script contains a return statement), you can also retrieve the value returned by a Javascript expression. You can do this in two ways. The first is to use the `result()` method to turn the `Evaluate` action into a question. You can see an example here:

```java
        Long result = (Long) dina.asksFor(Evaluate.javascript("return 1 + 1").result());
        assertThat(result).isEqualTo(2);
```

The type of the object returned by WebDriver is as follows: 
 * For an HTML element, this method returns a `WebElement`
 * For a decimal, a `Double` is returned
 * For a non-decimal number, a `Long` is returned
 * For a boolean, a `Boolean` is returned
 * For all other cases, a `String` is returned.
 * For an array, return a `List<Object>` with each object following the rules above. We support nested lists.
 * For a map, return a `Map<String, Object>` with values following the rules above.

### Hit a particular key

You can enter any Selenium key or key-combination using the `Enter` task. You may also want to use the `Hit` task for more readability. The `Hit` interaction class is similar to the `Enter` class, but takes a list of one or more `Keys` values:

```java
        dina.attemptsTo(Enter.theValue("Sarah-Jane").into(By.id("firstName")));
        dina.attemptsTo(Hit.the(Keys.TAB).into(By.id("firstName")));
```

### Working with checkboxes

You can check or uncheck a checkbox element by clicking on it using the `Click` interaction. If you want to be sure that that the element is checked or unchecked, you can also use the `SetCheckbox` class, to either check or uncheck the field.

For example, to check the Terms & Conditions checkbox on a form, you might use the following:

```java
        dina.attemptsTo(SetCheckbox.of("#terms-and-conditions").toTrue());
```

And to uncheck it, you could do this:

```java
        dina.attemptsTo(SetCheckbox.of("#terms-and-conditions").toFalse());
```

Since enabling and disabling checkboxes involves clicking, we can also use the `afterWaitingUntilEnabled()` and `afterWaitingUntilPresent()` methods available with the `Click` interaction class, e.g.

```java
        dina.attemptsTo(
            SetCheckbox.of("#terms-and-conditions").toFalse()
                                                   .afterWaitingUntilEnabled());
```

### JavaScriptClick

Sometimes it is useful to be able to bypass Selenium and perform a click() directly with JavaScript. We can do this with the `JavaScriptClick` class. The class has the same API as the `Click` class, e.g.

```java
        dina.attemptsTo(JavaScriptClick.on("#button"));
```

### Moving the mouse

We can move the mouse to an element on the page using `MoveMouse`, e.g.

```java
        dina.attemptsTo(MoveMouse.to("#button"));
```

If we need to perform one or more actions on the element once we have moved the cursor over it, we can do that using the `andThen()` method with a Lambda expression, which is passed the Actions object. For example, to click on the button after moving the cursor to it, we could do the following:

```java
        dina.attemptsTo(MoveMouse.to(BUTTON).andThen(actions -> actions.click()));
```

### Performing actions on collections of elements

We can also perform actions on a collection of elements. Suppose we have an HTML page containing a list of checkboxes like this:

```html
    <div>
        <label>Condiments:</label>
        Salt <input type="checkbox" id="salt" class="condiment" name="salt">
        Pepper <input type="checkbox" id="pepper" class="condiment" name="pepper">
        Sauce <input type="checkbox" id="sause" class="condiment" name="sauce">
    </div>
```

We could check each of these checkboxes in one go by using the `PerformOn.eachMatching()` method. This takes two parameters:
 - A locator (a Target, `By` locator, or CSS or XPath expression)
 - A lambda expression that accepts a `WebElementFacade`

If we wanted to click on each of these checkboxes, we could do the following:

```java
         dina.attemptsTo(
            PerformOn.eachMatching(".condiment", WebElementFacade::click)
        );
```

You can also use Screenplay performables, as shown in this example:
```java
        dina.attemptsTo(
            PerformOn.eachMatching(".condiment", 
                checkbox -> dina.attemptsTo(SetCheckbox.of(checkbox).toTrue()))
        );
```

### RightClick

You can right-click on an element using the `RightClick` class. This will use the Selenium `contextClick()` action method:

```java
        dina.attemptsTo(RightClick.on("#button"));
```

### Scrolling elements into view

Sometimes it can be useful to scroll to a specific element on the page. You can do this with the `Scroll` class, like this, which uses Javascript to scroll the element into view.

```java
        dina.attemptsTo(Scroll.to(By.id("#button")));
```

This class uses the Javascript `scrollIntoView()` method, which by default will scroll the screen so that the top of the element will be aligned to the top of the visible area of the scrollable ancestor. You can also align the bottom of the element to the bottom of the visible area of the scrollable ancestor, using the `andAlignToBottom()` method, e.g.

```java
        dina.attemptsTo(Scroll.to(By.id("#button")).andAlignToBottom());
```

### Selecting from dropdowns

We can select a value from a dropdown using the `SelectFromOptions` class. Suppose we have the following HTML code:

```html
        <select id="color">
            <option value="red">Red</option>
            <option value="green">Green</option>
            <option value="blue">Blue</option>
        </select>
```

We can select the second of these options in any of the following ways:
```java
    dina.attemptsTo(SelectFromOptions.byVisibleText("Green").from("#color"));
    dina.attemptsTo(SelectFromOptions.byValue("green").from("#color"));
    dina.attemptsTo(SelectFromOptions.byIndex(1).from("#color"));
```

We can retrieve the current value of a dropdown list using the `SelectedValue` Question class, e.g.

```java
    String selectedValue = dina.asksFor(SelectedValue.of(COLOR_"#color")));
```

### Switching to another window or frame

We can switch to a new window or tab using the `Switch` class. For example, the following code opens a link in a new tab and switches control to this tab:

```java
        dina.attemptsTo(
                Click.on("#link-that-opens-a-new-tab"),
                Switch.toNewWindow()
        );
```

If there are only two windows or tabs open, we can switch back to the original window by using the `Switch.toTheOtherWindow()` method:

```java
        dina.attemptsTo(
                Switch.toTheOtherWindow()
        );
```

Another option is to use the name or handle of the window you want to switch to, using `Switch.toWindow()`:

```java
        dina.attemptsTo(
                Switch.toWindow(originalWindowHandle)
        );
```

Alternatively, if you know the title of the window or tab, you can use the `Switch.toWindowTitled()` method:

```java
        dina.attemptsTo(
                Switch.toWindowTitled("The other window")
        );
```

Although HTML frames are considered obsolete for modern applications, they are still around in some older applications. You can interact with frames using the following methods:

Other Selenium switch functions are handled by the following methods:

| Interaction                    | Purpose              | Selenium equivalent     |
| -----------                    | --------             | -----------             |
| Switch.toFrame(index)          | Select a frame by its (zero-based) index. Selecting a frame by index is equivalent to the JS expression window.frames[index] where "window" is the DOM window represented by the current context. Once the frame has been selected, all subsequent calls on the WebDriver interface are made to that frame. | `driver.switch().toFrame(index)` |
| Switch.toFrame(nameOrId)       | Select a frame by its name or ID. Frames located by matching name attributes are always given precedence over those matched by ID. | `driver.switch().toFrame(nameOrId)` |
| Switch.toParentFrame()         | Change focus to the parent context. If the current context is the top level browsing context, the context remains unchanged. | `driver.switchTo().parentFrame()` |
| Switch.toDefaultContext()      |  Selects either the first frame on the page, or the main document when a page contains iframes. | `driver.switch().toDefaultContext()` |

Other Selenium switch functions are handled by the following methods:

| Interaction                    | Purpose              | Selenium equivalent     |
| -----------                    | --------             | -----------             |
| Switch.toActiveElement()       | Switches to the element that currently has focus within the document currently "switched to", or the body element if this cannot be detected. This matches the semantics of calling "document.activeElement" in Javascript. | `driver.switchTo().activeElement()`           |


### Dealing with Alert dialogs

We can work with HTML Alert dialogs using the `Switch.toAlert()` method. For example, the following code will switch the current window to the current alert dialog:
```java
        dina.attemptsTo(
                Switch.toAlert()
        );
```

We can query the text of the alert using the `HtmlAlert.text()` Question class:

```java
        dina.attemptsTo(
                Switch.toAlert()
        );
        assertThat(dina.asksFor(HtmlAlert.text())).isEqualTo("Are you sure?");
```

We can also accept or dismiss the alert message using the `Switch.toAlert().andAccept()` and `Switch.toAlert().andDismiss()` methods respectively:

```java
        dina.attemptsTo(
                Switch.toAlert().andAccept()
        );
```

### Upload

The simplest way to upload a file to an HTML upload field (one that has a type of 'file') is to use the `Upload` task. Suppose we have the following HTML form field:

```html
        <input type="file" id="upload-file" name="filename">
```

We can upload a file to this field as shown here:

```java
    Path fileToUpload = ...
    dina.attemptsTo(Upload.theFile(fileToUpload).to("#upload-file"));
```

If you are running the tests on a remote machine, you can use the Selenium Local File Detector. The Local File Detector allows the transfer of files from the client machine to the remote server. For example, if a test needs to upload a file to a web application, a remote WebDriver can automatically transfer the file from the local machine to the remote web server during runtime. This allows the file to be uploaded from the remote machine running the test.

```java
    Path fileToUpload = ...
    dina.attemptsTo(Upload.theFile(fileToUpload).to("#upload-file").usingLocalFileDetector());
```

You can also upload a file on the classpath resources using the `Upload.theClasspathResource()` method, as shown here:

```java
    Path fileToUpload = ...
    dina.attemptsTo(Upload.theClasspathResource("some/resource/path.txt").to("#upload-file"));
```

## Working with Chrome DevTools 

Many browsers provide "DevTools" – a set of tools that are integrated with the browser that developers can use to debug web apps and explore the performance of their pages. Google Chrome’s DevTools make use of a protocol called the Chrome DevTools Protocol (or “CDP” for short). As the name suggests, this is not designed for testing, nor to have a stable API, so functionality is highly dependent on the version of the browser.

In Serenity Screenplay, we can access the Selenium 4 DevTools library using the `WithDevTools.perform()` method. For example:

```java
        final List<Metric> metricList = new ArrayList<>();

        dina.attemptsTo(
                WithDevTools.perform(
                        devTools -> {
                            devTools.createSession();
                            devTools.send(Performance.enable(Optional.empty()));
                            metricList.addAll(devTools.send(Performance.getMetrics()));
                        }
                )
        );
```

If we want to use DevTools to retrieve a specific value, we can use the `DevToolsQuery` class:
```java
        List<Metric> metrics = dina.asksFor(
                DevToolsQuery.ask().about(devTools -> {
                    devTools.createSession();
                    devTools.send(Performance.enable(Optional.empty()));
                    return devTools.send(Performance.getMetrics());
                })
        );
```

## Querying the web page

Serenity Screenplay also gives you a large number of options when it comes to querying a web UI. Most involve special types of Question class.

In Screenplay web tests, you can simply implement a question which returns the object type you are interested, and then query the UI in a conventional Webdriver way. For example, suppose we want to read the user name on a page, which can be located with the ".user-name" CSS selector.

Screenplay assertion to check the user name might look like this:

```java
    sam.should(seeThat(TheUserName.value(), equalTo("sam")));
```

We could create a TheUserName question class to query this field as follows:

```java
@Subject("the displayed username")
public class TheUserName implements Question<String> {
    @Override
    public String answeredBy(Actor actor) {
        return BrowseTheWeb.as(actor).findBy(".user-name").getText();
    }

    public static Question<String> value() { return new TheUserName(); }
}
```
Here we use BrowseTheWeb.as(actor) to get the Serenity WebDriver API for the actor’s webdriver instance, which gives access to the full range of Serenity Page Object methods.

We could also use a Target to locate the user name, which we could store in a separate Page Component class:

```java
public static Target USER_NAME = Target.the("User name").locatedBy(".user-name");
```

We can then use the resolveFor() method to find the element matching that target in the actor’s browser:

```java
@Subject("the displayed username")
public class TheUserName implements Question<String> {

    @Override
    public String answeredBy(Actor actor) {
        return USER_NAME.resolveFor(actor).getText();
    }

    public static Question<String> value() { return new TheUserName(); }
}
```

Alternatively, we could write this class as a factory, and use a lambda expression instead of a fully blown Question class:

```java
public class TheUserName {

    public static Question<String> value() {
        return actor -> USER_NAME.resolveFor(actor).getText();
    }
}
```

In this case, the `@Subject` annotation will have no effect, so we need to pass in the name of the object we are checking in the Screenplay assertion:

```java
sam.should(seeThat("the displayed username", TheUserName.value(), equalTo("sam")));
```

So far you have seen how Screenplay questions work in detail. This will help you implement your own if you need to. However Serenity also provides a number of shortcuts related to querying web pages, which you will find in the net.serenitybdd.screenplay.questions package, which allow you to write much more concise automation code. 

## Bundled WebDriver Questions

Serenity provides many bundled Question classes in the `net.serenitybdd.screenplay.questions` package that a short-hand way of querying a web page. For example, the `Text` class lets us retrieve the text content of an element, like this:

```java
String name = sam.asksFor(Text.of("#name"));
```

If there are many matching entries, we can retrieve them all using the `ofEach()` method:

```java
Collection<String> names = sam.asksFor(Text.ofEach(".name"));
```

The full list of Web Question classes is provided here.

### Absence

Determine whether an element is _not_ present or visible on the page. A field that is present in the dom but is not rendered will be considered absent.

```java
boolean isNotPresent = sam.asksFor(Absence.of("#no-such-field"));
```

### Attribute

Check the value of an HTML attribute of a specified element.

```java
String placeholderText = sam.asksFor(Attribute.of(".new-todo").named("placeholder"));
```

### CheckboxValue

Determine whether a checkbox has been checked or not.

```java
boolean termsAndConditionsApproved = sam.asksFor(CheckboxValue.of("#tnc"));
```

### CSSValue

Retrieve the value of a specific CSS attribute of an element.

```java
String font = sam.asksFor(CSSValue.of(target).named("font"));
```

### CurrentlyEnabled

Check whether an element is currently enabled, without waiting.

```java
boolean isCurrentlyEnabled = sam.asksFor(CurrentlyEnabled.of("#some-button"));
```

### CurrentVisibility

Check whether an element is currently visible, without waiting.

```java
boolean isCurrentlyVisible = sam.asksFor(CurrentVisibility.of("#some-button"));
```

### Disabled

Check whether an element is disabled.

```java
boolean isDisabled = sam.asksFor(Disabled.of("#a-disabled-button"));
```

### Displayed

Check whether an element is displayed. If the element is not currently displayed, the test will wait for a short delay to give it time to be displayed.

```java
boolean isDisplayed = sam.asksFor(Displayed.of("#some-button"));
```

### Enabled

Check whether an element is enabled. If the element is not currently enabled, the test will wait for a short delay to give it time to be enabled.

```java
boolean isEnabled = sam.asksFor(Enabled.of("#some-button"));
```

### Presence

Check whether an element is present in the DOM. An invisible or hidden element can still be present in the DOM.

### SelectedStatus

Alternative to `CheckboxValue`

```java
boolean termsAndConditionsApproved = sam.asksFor(SelectedStatus.of("#tnc"));
```

# Text

To fetch the text value of an element, we can use the `Text` class:

```java
String introductionText = sam.asksFor(Text.of("#introduction"));
```

### TextContent

In some cases, we may need to read the `textContent` HTML property to get the text we need. To do this, we can use the `TextContent` class rather than `Text`. This returns the text content of the specified element, and all its descendants.

### TheCoordinates

Return the coordinates of a specified element.

### TheLocation

Return where on the page is the top left-hand corner of the rendered element.

### TheSize

What is the width and height of the rendered element?

### Value

Return the HTML `value` attribute of a specified element.

### Visibility

Determine whether this web element present and visible on the screen

### Working with Dropdowns

We can query the current selected value or values of an HTML `<SELECT>` element using the `SelectedValue`, `SelectedValues`, `SelectedVisibleTextValue` and `SelectedVisibleTextValue` Question classes.

For example, to find the current selected value of an HTML dropdown list, we could use the following code:

```java
String selectedColorValue = dina.asksFor(SelectedValue.of("#color-dropdown"));
```

To get the visible text of the selected item, we would use `SelectedVisibleTextValue`:

```java
String selectedColor = dina.asksFor(SelectedVisibleTextValue.of("#color-dropdown"));
```

For multi-selects, we can use `SelectedValues` and `SelectedVisibleTextValues`:

```java
List<String> selectedColors = dina.asksFor(SelectedValues.of("#color-dropdown"));
```

We can retrieve the current list of options using `SelectOptions`, which returns the list of visible texts for each option:

```java
List<String> selectedColors = dina.asksFor(SelectOptions.of("#color-dropdown"));
```

If we need the `value` attribute of each dropdown option, we can use `SelectOptionValues`, e.g.:

```java
List<String> selectedColors = dina.asksFor(SelectOptionValues.of("#color-dropdown"));
```



## Handling Waits

### Using the WaitUntil class
If you need to wait for an element to appear with Serenity Screenplay, there are a few options available. By default, Serenity will wait for a short delay if you try to interact with an element that is not on the page. However, you can ensure that this wait is sufficient by using the `WaitUntil` class, as shown here: 

```java
private final static Target DELAYED_BUTTON = PageElement.locatedBy("#delayed-button");

dina.attemptsTo(
    WaitUntil.the(DELAYED_BUTTON, WebElementStateMatchers.isVisible()),
    Click.on(DELAYED_BUTTON)
);
```

This code will wait until the element is visible before proceeding to the Click action. The timeout can be configured (in milliseconds) using the `webdriver.timeouts.implicitlywait` property, which is 5 seconds by default.

If you need to have a finer control over the timeout duration for specific situations, you can specify this by adding the `forNoMoreThan()` method, which lets you specify an explicit timeout:

```java
dina.attemptsTo(
    WaitUntil.the(DELAYED_BUTTON, isVisible()).forNoMoreThan(10).seconds()
);
 ```

You can also wait for other conditions. For example, to wait until an element dissapears, you can use the `isNotVisible()` matcher:

```java
dina.attemptsTo(
    WaitUntil.the(DISAPPEARING_BUTTON, isNotVisible())
);
```

The following matchers are available in the `WebElementStateMatchers` class. Note that all of the following methods also have a negative equivalent (`isNotVisible()`, `isNotEmpty()` etc.).

| Matcher                    | Purpose                              |
| -----------                | --------                             |
| containsText(...)          | Check that an element contains a specific text value |
| containsOnlyText(...)      | Check that an element contains exactly a specific text value |
| containsSelectOption(...)  | Check that a dropdown element contains a specific text value as an option|
| isClickable                | Check that an element is visible and enabled |
| isEmpty                    | Check that an element is not visible or contains an empty string |
| isEnabled                  | Check that an element is enabled |
| isPresent                  | Check that an element is present on the page |
| isSelected                 | Check that an element is selected     | 
| isVisible                  | Check that an element is visible     | 

### Waiting for a WebDriver condition

Another option is to wait for a WebDriver condition (which can be found in the `org.openqa.selenium.support.ui.ExpectedConditions` class), e.g.

```java
dina.attemptsTo(
        WaitUntil.the(
                invisibilityOfElementLocated(By.id("disappearing-button")))
);
```

### Waiting for Targets

You can also place a specific wait condition on a `Target` object. You can do this either when you define the `Target` variable (if it should be applied any time you interact with this element), or only when you interact with the element, as shown below:

```java
private final static Target INVISIBLE_BUTTON 
    = PageElement.locatedBy("#invisible-button");

dina.attemptsTo(
    Click.on(INVISIBLE_BUTTON.waitingForNoMoreThan(Duration.ofSeconds(3)))
);
```


---

<!-- https://serenity-bdd.github.io/docs/screenplay/screenplay_playwright -->

# Web Testing with Serenity Screenplay and Playwright

## Introduction

Playwright is a modern browser automation library that provides cross-browser testing capabilities with excellent support for modern web applications. The `serenity-screenplay-playwright` module brings the power of Playwright to Serenity BDD's Screenplay pattern, offering an alternative to the traditional WebDriver integration.

Playwright offers several advantages over WebDriver:
- **Auto-waiting**: Automatically waits for elements to be actionable before performing actions
- **Cross-browser**: Native support for Chromium, Firefox, and WebKit
- **Network interception**: Built-in support for mocking and intercepting network requests
- **Tracing**: Record detailed traces for debugging test failures
- **Device emulation**: Easy mobile and tablet device emulation
- **Modern architecture**: Event-driven design with better reliability

## Getting Started

### Maven Dependency

Add the following dependency to your project:

```xml
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-screenplay-playwright</artifactId>
    <version>${serenity.version}</version>
</dependency>
```

### The BrowseTheWebWithPlaywright Ability

To use Playwright with Screenplay, actors need the `BrowseTheWebWithPlaywright` ability. The recommended approach is to use Playwright's `@UsePlaywright` annotation, which manages the browser lifecycle automatically:

```java
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.playwright.junit5.SerenityPlaywrightExtension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import com.microsoft.playwright.*;

@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(ChromeHeadlessOptions.class)
class MyScreenplayTest {

    Actor alice;

    @BeforeEach
    void setUp(Page page) {
        alice = Actor.named("Alice");
        alice.can(BrowseTheWebWithPlaywright.withPage(page));
    }
}
```

The `withPage(Page)` factory method wraps a `@UsePlaywright`-managed page. Screenplay reuses the existing browser — no duplicate browser instance is created. On teardown, Screenplay only unregisters the page; it does **not** close the Page, BrowserContext, Browser, or Playwright instance.

:::tip `@SerenityPlaywright` shorthand
You can use the `@SerenityPlaywright` meta-annotation as a shorthand for both `@ExtendWith(SerenityJUnit5Extension.class)` and `@ExtendWith(SerenityPlaywrightExtension.class)`.
:::

#### Alternative: Manual Lifecycle Management

If you need full control over the browser lifecycle, you can manage it manually:

```java
Playwright playwright = Playwright.create();
Browser browser = playwright.chromium().launch();

Actor alice = Actor.named("Alice");
alice.can(BrowseTheWebWithPlaywright.using(browser));
```

### Configuration

When using `@UsePlaywright`, configure browser options with an `OptionsFactory`:

```java
public class ChromeHeadlessOptions implements OptionsFactory {
    @Override
    public Options getOptions() {
        return new Options()
                .setHeadless(true)
                .setLaunchOptions(
                        new BrowserType.LaunchOptions()
                                .setArgs(Arrays.asList(
                                    "--no-sandbox",
                                    "--disable-extensions",
                                    "--disable-gpu"))
                );
    }
}
```

For manual lifecycle management, configure programmatically:

```java
BrowserType.LaunchOptions options = new BrowserType.LaunchOptions()
    .setHeadless(false)
    .setSlowMo(100);

Browser browser = playwright.chromium().launch(options);
```

## Opening a URL

### Opening a URL directly

In Screenplay, you open a new page using the `Navigate` interaction class:

```java
alice.attemptsTo(Navigate.to("https://todomvc.com/examples/react/"));
```

### Opening the base URL

If you have configured a base URL, you can navigate to it:

```java
alice.attemptsTo(Navigate.toTheBaseUrl());
```

## Locating Elements on a Page

### The Target Class

The `Target` class in Playwright integration uses Playwright's powerful selector engine. Unlike WebDriver, Playwright provides multiple built-in selector strategies.

```java
Target SUBMIT_BUTTON = Target.the("Submit button").locatedBy("#submit-btn");

alice.attemptsTo(Click.on(SUBMIT_BUTTON));
```

### Playwright Selectors

Playwright supports a rich set of selectors:

```java
// CSS selector
Target.the("Login button").locatedBy("#login-btn")

// Text selector
Target.the("Submit button").locatedBy("text=Submit")

// Role selector (ARIA)
Target.the("Submit button").locatedBy("role=button[name='Submit']")

// XPath selector
Target.the("Email field").locatedBy("xpath=//input[@type='email']")

// Combining selectors
Target.the("Form submit").locatedBy("form >> button[type='submit']")
```

### Dynamic Targets

You can use parameterized targets for dynamic element location:

```java
Target MENU_ITEM = Target.the("{0} menu item").locatedBy("text={0}");

alice.attemptsTo(Click.on(MENU_ITEM.of("Settings")));
```

## UI Element Factories

Serenity Playwright provides convenient factory classes for locating common UI elements using Playwright's powerful selector syntax.

### Button

Locate buttons using various strategies:

```java
import net.serenitybdd.screenplay.playwright.ui.Button;

// By visible text (case-insensitive, uses role selector)
alice.attemptsTo(Click.on(Button.withText("Submit")));

// By name or ID attribute
alice.attemptsTo(Click.on(Button.withNameOrId("submit-btn")));

// By aria-label
alice.attemptsTo(Click.on(Button.withAriaLabel("Close dialog")));

// Containing specific text
alice.attemptsTo(Click.on(Button.containingText("Add to")));

// Custom locator
alice.attemptsTo(Click.on(Button.locatedBy("[data-testid='primary-action']")));
```

### InputField

Locate input fields:

```java
import net.serenitybdd.screenplay.playwright.ui.InputField;

// By name or ID
alice.attemptsTo(Enter.theValue("john@example.com").into(InputField.withNameOrId("email")));

// By placeholder text
alice.attemptsTo(Enter.theValue("Search...").into(InputField.withPlaceholder("Search products")));

// By associated label text
alice.attemptsTo(Enter.theValue("password123").into(InputField.withLabel("Password")));

// By aria-label
alice.attemptsTo(Enter.theValue("John").into(InputField.withAriaLabel("First name")));
```

### Link

Locate anchor elements:

```java
import net.serenitybdd.screenplay.playwright.ui.Link;

// By exact text
alice.attemptsTo(Click.on(Link.withText("Learn more")));

// Containing text
alice.attemptsTo(Click.on(Link.containingText("documentation")));

// By title attribute
alice.attemptsTo(Click.on(Link.withTitle("View user profile")));
```

### Checkbox

Locate checkbox inputs:

```java
import net.serenitybdd.screenplay.playwright.ui.Checkbox;

// By label text
alice.attemptsTo(Click.on(Checkbox.withLabel("Accept terms")));

// By name or ID
alice.attemptsTo(Click.on(Checkbox.withNameOrId("newsletter")));

// By value attribute
alice.attemptsTo(Click.on(Checkbox.withValue("premium")));
```

### RadioButton

Locate radio button inputs:

```java
import net.serenitybdd.screenplay.playwright.ui.RadioButton;

// By label text
alice.attemptsTo(Click.on(RadioButton.withLabel("Express shipping")));

// By value attribute
alice.attemptsTo(Click.on(RadioButton.withValue("express")));
```

### Dropdown

Locate select elements:

```java
import net.serenitybdd.screenplay.playwright.ui.Dropdown;

// By label text
alice.attemptsTo(
    SelectFromOptions.byVisibleText("Canada").from(Dropdown.withLabel("Country"))
);

// By name or ID
alice.attemptsTo(
    SelectFromOptions.byValue("us").from(Dropdown.withNameOrId("country"))
);
```

### Label

Locate label elements:

```java
import net.serenitybdd.screenplay.playwright.ui.Label;

// By text content
String labelText = alice.asksFor(Text.of(Label.withText("Email")));

// For a specific field ID
Target emailLabel = Label.forFieldId("email-input");
```

### Image

Locate image elements:

```java
import net.serenitybdd.screenplay.playwright.ui.Image;

// By alt text
alice.attemptsTo(Click.on(Image.withAltText("Product thumbnail")));

// By source URL
alice.attemptsTo(Click.on(Image.withSrc("/images/logo.png")));

// By partial source URL
alice.attemptsTo(Click.on(Image.withSrcContaining("product-123")));
```

## Interacting with Elements

### Core Interactions

The following interaction classes are available in the `net.serenitybdd.screenplay.playwright.interactions` package:

| Interaction | Purpose | Example |
|-------------|---------|---------|
| Click | Click on an element | `actor.attemptsTo(Click.on("#button"))` |
| DoubleClick | Double-click on an element | `actor.attemptsTo(DoubleClick.on("#item"))` |
| RightClick | Right-click (context menu) | `actor.attemptsTo(RightClick.on("#menu"))` |
| Enter | Type into an input field | `actor.attemptsTo(Enter.theValue("text").into("#field"))` |
| Clear | Clear an input field | `actor.attemptsTo(Clear.field("#field"))` |
| Hover | Hover over an element | `actor.attemptsTo(Hover.over("#menu"))` |
| Press | Press keyboard keys | `actor.attemptsTo(Press.key("Enter"))` |
| Check | Check a checkbox | `actor.attemptsTo(Check.checkbox("#agree"))` |
| Uncheck | Uncheck a checkbox | `actor.attemptsTo(Uncheck.checkbox("#agree"))` |
| Focus | Focus on an element | `actor.attemptsTo(Focus.on("#input"))` |
| Navigate | Navigate to a URL | `actor.attemptsTo(Navigate.to("https://..."))` |
| Upload | Upload a file | `actor.attemptsTo(Upload.file(path).to("#upload"))` |

### Click

Click on an element. Playwright automatically waits for the element to be actionable:

```java
alice.attemptsTo(Click.on("#submit-button"));
alice.attemptsTo(Click.on(SUBMIT_BUTTON));
```

### Double-Click

Double-click on an element:

```java
alice.attemptsTo(DoubleClick.on("#item"));
```

### Right-Click

Right-click to open context menus:

```java
alice.attemptsTo(RightClick.on("#file-item"));
```

### Enter Text

Type values into input fields:

```java
alice.attemptsTo(Enter.theValue("john@example.com").into("#email"));
```

You can also clear the field first:

```java
alice.attemptsTo(
    Clear.field("#email"),
    Enter.theValue("new-email@example.com").into("#email")
);
```

### Keyboard Interactions

Press keyboard keys:

```java
// Single key
alice.attemptsTo(Press.key("Enter"));

// Key combinations
alice.attemptsTo(Press.key("Control+a"));

// Multiple keys
alice.attemptsTo(Press.keys("Tab", "Tab", "Enter"));
```

### Hover

Hover over elements to trigger hover states:

```java
alice.attemptsTo(Hover.over("#dropdown-menu"));
```

### Check and Uncheck

Work with checkboxes:

```java
alice.attemptsTo(Check.checkbox("#newsletter"));
alice.attemptsTo(Uncheck.checkbox("#marketing-emails"));
```

### Focus

Focus on an element:

```java
alice.attemptsTo(Focus.on("#search-input"));
```

### Selecting from Dropdowns

Select options from dropdown menus:

```java
// By visible text
alice.attemptsTo(SelectFromOptions.byVisibleText("Red").from("#color"));

// By value attribute
alice.attemptsTo(SelectFromOptions.byValue("red").from("#color"));

// By index
alice.attemptsTo(SelectFromOptions.byIndex(2).from("#color"));

// Multiple values (for multi-select)
alice.attemptsTo(SelectFromOptions.byValue("red", "blue", "green").from("#colors"));
```

### Deselecting from Dropdowns

For multi-select dropdowns, you can deselect options:

```java
import net.serenitybdd.screenplay.playwright.interactions.DeselectFromOptions;

// Deselect by value
alice.attemptsTo(DeselectFromOptions.byValue("red").from("#colors"));

// Deselect by visible text
alice.attemptsTo(DeselectFromOptions.byVisibleText("Red").from("#colors"));

// Deselect by index
alice.attemptsTo(DeselectFromOptions.byIndex(0).from("#colors"));

// Deselect all
alice.attemptsTo(DeselectFromOptions.all().from("#colors"));
```

### Scrolling

Comprehensive scrolling capabilities:

```java
import net.serenitybdd.screenplay.playwright.interactions.Scroll;

// Scroll to an element
alice.attemptsTo(Scroll.to("#terms-and-conditions"));

// Scroll with alignment
alice.attemptsTo(Scroll.to("#section").andAlignToTop());
alice.attemptsTo(Scroll.to("#section").andAlignToCenter());
alice.attemptsTo(Scroll.to("#section").andAlignToBottom());

// Page-level scrolling
alice.attemptsTo(Scroll.toTop());
alice.attemptsTo(Scroll.toBottom());

// Scroll by specific amount (deltaX, deltaY)
alice.attemptsTo(Scroll.by(0, 500));

// Scroll to specific position
alice.attemptsTo(Scroll.toPosition(0, 1000));
```

### Drag and Drop

Drag elements from one location to another:

```java
import net.serenitybdd.screenplay.playwright.interactions.Drag;

// Basic drag and drop
alice.attemptsTo(Drag.from("#source").to("#target"));

// Alternative fluent syntax
alice.attemptsTo(Drag.the("#draggable").onto("#droppable"));

// With Targets
alice.attemptsTo(Drag.from(SOURCE_ELEMENT).to(TARGET_LOCATION));
```

### File Uploads

Upload files:

```java
Path fileToUpload = Paths.get("path/to/file.pdf");
alice.attemptsTo(Upload.file(fileToUpload).to("#file-input"));
```

### JavaScript Execution

Execute JavaScript in the page context:

```java
alice.attemptsTo(
    Evaluate.javascript("window.scrollTo(0, document.body.scrollHeight)")
);

// With return value
Object result = alice.asksFor(
    Evaluate.javascript("return document.title")
);
```

### Waiting

Wait for elements or conditions:

```java
// Wait for element to be visible
alice.attemptsTo(WaitUntil.the("#loading").isNotVisible());

// Wait for element to be hidden
alice.attemptsTo(WaitUntil.the("#spinner").isHidden());

// Wait with timeout
alice.attemptsTo(
    WaitUntil.the("#content").isVisible()
        .forNoMoreThan(Duration.ofSeconds(10))
);
```

## Querying the Web Page

### Bundled Questions

Serenity Playwright provides Question classes for querying page state:

| Question | Purpose | Example |
|----------|---------|---------|
| Text | Get element text | `actor.asksFor(Text.of("#title"))` |
| Value | Get input value | `actor.asksFor(Value.of("#email"))` |
| Attribute | Get attribute value | `actor.asksFor(Attribute.of("#link").named("href"))` |
| Presence | Check if element exists | `actor.asksFor(Presence.of("#modal"))` |
| Absence | Check if element is absent | `actor.asksFor(Absence.of("#error"))` |
| Visibility | Check if element is visible | `actor.asksFor(Visibility.of("#popup"))` |
| Enabled | Check if element is enabled | `actor.asksFor(Enabled.of("#submit"))` |
| SelectedStatus | Check if checkbox is selected | `actor.asksFor(SelectedStatus.of("#agree"))` |
| CSSValue | Get CSS property | `actor.asksFor(CSSValue.of("#box").named("color"))` |
| CurrentUrl | Get current page URL | `actor.asksFor(CurrentUrl.ofThePage())` |
| PageTitle | Get page title | `actor.asksFor(PageTitle.ofThePage())` |

### Text

Get the text content of an element:

```java
String heading = alice.asksFor(Text.of("#main-heading"));

// Multiple elements
List<String> items = alice.asksFor(Text.ofEach(".list-item"));
```

### Presence and Absence

Check whether elements exist on the page:

```java
// Check if present
boolean isPresent = alice.asksFor(Presence.of("#modal"));

// Check if absent
boolean isAbsent = alice.asksFor(Absence.of("#error-message"));
```

### Attributes

Get attribute values:

```java
String href = alice.asksFor(Attribute.of("#link").named("href"));
String placeholder = alice.asksFor(Attribute.of("#input").named("placeholder"));
```

### Current Page Information

Query page-level information:

```java
String url = alice.asksFor(CurrentUrl.ofThePage());
String title = alice.asksFor(PageTitle.ofThePage());
```

## Network Interception and Mocking

Playwright provides powerful network interception capabilities for testing.

### Intercepting Requests

```java
import net.serenitybdd.screenplay.playwright.network.InterceptNetwork;

// Intercept and fulfill with mock response
alice.attemptsTo(
    InterceptNetwork.requestsTo("**/api/users")
        .andRespondWith(
            new Route.FulfillOptions()
                .setStatus(200)
                .setBody("{\"users\": []}")
                .setContentType("application/json")
        )
);

// Intercept and respond with JSON
alice.attemptsTo(
    InterceptNetwork.requestsTo("**/api/user/123")
        .andRespondWithJson(200, Map.of(
            "id", 123,
            "name", "John Doe",
            "email", "john@example.com"
        ))
);
```

### Custom Request Handlers

For more control, use custom handlers:

```java
alice.attemptsTo(
    InterceptNetwork.requestsTo("**/api/**")
        .andHandle(route -> {
            if (route.request().method().equals("DELETE")) {
                route.fulfill(new Route.FulfillOptions()
                    .setStatus(403)
                    .setBody("{\"error\": \"Forbidden\"}"));
            } else {
                route.resume();
            }
        })
);
```

### Aborting Requests

Block specific requests (useful for testing error handling):

```java
alice.attemptsTo(
    InterceptNetwork.requestsTo("**/analytics/**").andAbort()
);
```

### Removing Routes

Remove previously registered route handlers:

```java
import net.serenitybdd.screenplay.playwright.network.RemoveRoutes;

// Remove all route handlers
alice.attemptsTo(RemoveRoutes.all());

// Remove routes for specific pattern
alice.attemptsTo(RemoveRoutes.forUrl("**/api/**"));
```

## API Testing Integration

:::info New in 5.2.2
API testing integration was added in Serenity BDD 5.2.2.
:::

Make API requests that share the browser's session context (cookies, authentication). This enables hybrid UI + API testing scenarios where you can set up data via API, perform UI actions, and verify state through API calls.

### Basic API Requests

```java
import net.serenitybdd.screenplay.playwright.interactions.api.APIRequest;
import net.serenitybdd.screenplay.playwright.questions.api.LastAPIResponse;

// Initialize browser context first (required for API requests)
alice.attemptsTo(Open.url("about:blank"));

// GET request
alice.attemptsTo(
    APIRequest.get("https://api.example.com/users/1")
);

// POST request with JSON body
alice.attemptsTo(
    APIRequest.post("https://api.example.com/users")
        .withJsonBody(Map.of(
            "name", "John Doe",
            "email", "john@example.com"
        ))
);

// PUT request
alice.attemptsTo(
    APIRequest.put("https://api.example.com/users/1")
        .withJsonBody(Map.of("name", "Jane Doe"))
);

// PATCH request
alice.attemptsTo(
    APIRequest.patch("https://api.example.com/users/1")
        .withJsonBody(Map.of("status", "active"))
);

// DELETE request
alice.attemptsTo(
    APIRequest.delete("https://api.example.com/users/1")
);

// HEAD request
alice.attemptsTo(
    APIRequest.head("https://api.example.com/users/1")
);
```

### Request Configuration

```java
// Add custom headers
alice.attemptsTo(
    APIRequest.get("https://api.example.com/data")
        .withHeader("Authorization", "Bearer token123")
        .withHeader("X-Custom-Header", "value")
);

// Add query parameters
alice.attemptsTo(
    APIRequest.get("https://api.example.com/search")
        .withQueryParam("q", "test")
        .withQueryParam("limit", "10")
);

// Set content type
alice.attemptsTo(
    APIRequest.post("https://api.example.com/data")
        .withBody("<xml>data</xml>")
        .withContentType("application/xml")
);

// Set timeout
alice.attemptsTo(
    APIRequest.get("https://api.example.com/slow")
        .withTimeout(30000)  // 30 seconds
);

// Fail on non-2xx status codes
alice.attemptsTo(
    APIRequest.get("https://api.example.com/data")
        .failOnStatusCode(true)
);
```

### Querying Responses

```java
// Get status code
int status = alice.asksFor(LastAPIResponse.statusCode());

// Check if response is OK (2xx)
boolean isOk = alice.asksFor(LastAPIResponse.ok());

// Get response body as string
String body = alice.asksFor(LastAPIResponse.body());

// Parse JSON response as Map
Map<String, Object> json = alice.asksFor(LastAPIResponse.jsonBody());

// Parse JSON array response as List
List<Map<String, Object>> items = alice.asksFor(LastAPIResponse.jsonBodyAsList());

// Get response headers
Map<String, String> headers = alice.asksFor(LastAPIResponse.headers());
String contentType = alice.asksFor(LastAPIResponse.header("Content-Type"));

// Get final URL (after redirects)
String url = alice.asksFor(LastAPIResponse.url());
```

### Hybrid UI + API Testing

API requests automatically share cookies with the browser context:

```java
@Test
void shouldUseAuthenticatedSession() {
    // Login via UI
    alice.attemptsTo(
        Navigate.to("https://myapp.com/login"),
        Enter.theValue("user@example.com").into("#email"),
        Enter.theValue("password").into("#password"),
        Click.on(Button.withText("Login"))
    );

    // API calls now include authentication cookies
    alice.attemptsTo(
        APIRequest.get("https://myapp.com/api/profile")
    );

    // Verify authenticated API response
    Map<String, Object> profile = alice.asksFor(LastAPIResponse.jsonBody());
    assertThat(profile.get("email")).isEqualTo("user@example.com");
}
```

### API Calls in Serenity Reports

API requests made via `APIRequest` are automatically recorded in Serenity reports, similar to RestAssured. The reports show:
- HTTP method and URL
- Request headers and body
- Response status code
- Response headers and body

This provides full visibility into API interactions during test execution.

### Complete Example

```java
@Test
void shouldCreateAndVerifyUser() {
    alice.attemptsTo(Open.url("about:blank"));

    // Create user via API
    alice.attemptsTo(
        APIRequest.post("https://jsonplaceholder.typicode.com/users")
            .withJsonBody(Map.of(
                "name", "Test User",
                "email", "test@example.com",
                "username", "testuser"
            ))
    );

    // Verify creation
    assertThat(alice.asksFor(LastAPIResponse.statusCode())).isEqualTo(201);

    Map<String, Object> createdUser = alice.asksFor(LastAPIResponse.jsonBody());
    assertThat(createdUser.get("name")).isEqualTo("Test User");
    assertThat(createdUser.get("id")).isNotNull();

    // Fetch the created user
    String userId = String.valueOf(((Double) createdUser.get("id")).intValue());
    alice.attemptsTo(
        APIRequest.get("https://jsonplaceholder.typicode.com/users/" + userId)
    );

    assertThat(alice.asksFor(LastAPIResponse.statusCode())).isEqualTo(200);
}
```

## Handling Downloads

Wait for and handle file downloads:

```java
import net.serenitybdd.screenplay.playwright.interactions.WaitForDownload;
import net.serenitybdd.screenplay.playwright.questions.DownloadedFile;

// Wait for download triggered by clicking
alice.attemptsTo(
    WaitForDownload.whilePerforming(Click.on("#download-btn"))
);

// Query download information
String filename = alice.asksFor(DownloadedFile.suggestedFilename());
String url = alice.asksFor(DownloadedFile.url());
Path path = alice.asksFor(DownloadedFile.path());

// Check for failures
String error = alice.asksFor(DownloadedFile.failure());
if (error == null) {
    // Download succeeded
}

// Save to specific location
alice.attemptsTo(
    WaitForDownload.whilePerforming(Click.on("#export-btn"))
        .andSaveTo(Paths.get("/downloads/report.pdf"))
);
```

## Console Message Capture

Capture and query browser console messages for debugging:

```java
import net.serenitybdd.screenplay.playwright.interactions.CaptureConsoleMessages;
import net.serenitybdd.screenplay.playwright.questions.ConsoleMessages;

// Start capturing console messages
alice.attemptsTo(CaptureConsoleMessages.duringTest());

// ... perform actions that may log to console ...

// Query captured messages
List<String> allMessages = alice.asksFor(ConsoleMessages.all());
List<String> errors = alice.asksFor(ConsoleMessages.errors());
List<String> warnings = alice.asksFor(ConsoleMessages.warnings());
List<String> logs = alice.asksFor(ConsoleMessages.logs());

// Filter by content
List<String> apiErrors = alice.asksFor(ConsoleMessages.containing("API error"));

// Get message counts
int totalCount = alice.asksFor(ConsoleMessages.count());
int errorCount = alice.asksFor(ConsoleMessages.errorCount());

// Clear captured messages between test phases
alice.attemptsTo(CaptureConsoleMessages.clear());
```

### Checking for Console Errors

:::info New in 5.2.2
`CheckConsole` was added in Serenity BDD 5.2.2.
:::

Use `CheckConsole` to automatically fail tests when JavaScript errors or warnings occur. This is the recommended way to ensure your application doesn't have console errors during user flows:

```java
import net.serenitybdd.screenplay.playwright.interactions.CheckConsole;

// Start capturing, then check for errors at the end of the flow
alice.attemptsTo(
    CaptureConsoleMessages.duringTest(),

    // Perform user actions
    Navigate.to("https://myapp.com/checkout"),
    Enter.theValue("4111111111111111").into("#card-number"),
    Click.on(Button.withText("Pay")),

    // Fail the test if any JavaScript errors occurred
    CheckConsole.forErrors()
);
```

#### CheckConsole Options

| Method | Description |
|--------|-------------|
| `CheckConsole.forErrors()` | Fail if any console errors are found |
| `CheckConsole.forWarnings()` | Fail if any console warnings are found |
| `CheckConsole.forErrorsAndWarnings()` | Fail if any errors OR warnings are found |

#### Report-Only Mode

Sometimes you want to document console issues without failing the test (e.g., for known issues or when monitoring error trends):

```java
// Report errors to Serenity but don't fail the test
alice.attemptsTo(
    CheckConsole.forErrors().andReportOnly()
);
```

When errors are found, they are automatically attached to the Serenity report as evidence, whether the test fails or not.

### Reporting Console Messages

:::info New in 5.2.2
`ReportConsoleMessages` was added in Serenity BDD 5.2.2.
:::

Use `ReportConsoleMessages` to explicitly add captured console messages to the Serenity report:

```java
import net.serenitybdd.screenplay.playwright.interactions.ReportConsoleMessages;

alice.attemptsTo(
    CaptureConsoleMessages.duringTest(),

    // ... perform actions ...

    // Report errors and warnings to Serenity
    ReportConsoleMessages.errorsAndWarnings()
);
```

#### ReportConsoleMessages Options

| Method | Description |
|--------|-------------|
| `ReportConsoleMessages.all()` | Report all console messages |
| `ReportConsoleMessages.errors()` | Report only errors |
| `ReportConsoleMessages.warnings()` | Report only warnings |
| `ReportConsoleMessages.errorsAndWarnings()` | Report errors and warnings |

### Example: Complete Console Error Checking

Here's a typical pattern for ensuring no JavaScript errors occur during a critical user flow:

```java
@Test
void checkoutFlowShouldHaveNoJavaScriptErrors() {
    alice.attemptsTo(
        // Start capturing at the beginning
        CaptureConsoleMessages.duringTest(),

        // Complete the checkout flow
        Navigate.to("https://myapp.com/cart"),
        Click.on(Button.withText("Checkout")),
        Enter.theValue("john@example.com").into(InputField.withLabel("Email")),
        Enter.theValue("4111111111111111").into(InputField.withLabel("Card Number")),
        Click.on(Button.withText("Place Order")),

        // Verify order confirmation
        WaitFor.theElement(".order-confirmation").toBeVisible(),

        // Fail the test if any JavaScript errors occurred during the flow
        CheckConsole.forErrors()
    );
}
```

## Network Request Capture

:::info New in 5.2.2
Network request capture was added in Serenity BDD 5.2.2.
:::

Capture and analyze all network requests made during tests. This is useful for debugging, verifying API calls made by the frontend, and detecting failed requests.

```java
import net.serenitybdd.screenplay.playwright.interactions.CaptureNetworkRequests;
import net.serenitybdd.screenplay.playwright.interactions.CaptureNetworkRequests.CapturedRequest;
import net.serenitybdd.screenplay.playwright.questions.NetworkRequests;

// Start capturing network requests
alice.attemptsTo(CaptureNetworkRequests.duringTest());

// Perform actions that trigger network requests
alice.attemptsTo(Navigate.to("https://example.com"));

// Query all captured requests
List<CapturedRequest> allRequests = alice.asksFor(NetworkRequests.all());
int requestCount = alice.asksFor(NetworkRequests.count());

// Filter by HTTP method
List<CapturedRequest> getRequests = alice.asksFor(NetworkRequests.withMethod("GET"));
List<CapturedRequest> postRequests = alice.asksFor(NetworkRequests.withMethod("POST"));

// Filter by URL
List<CapturedRequest> apiRequests = alice.asksFor(
    NetworkRequests.toUrlContaining("/api/")
);

// Filter by glob pattern
List<CapturedRequest> cssRequests = alice.asksFor(
    NetworkRequests.matching("**/*.css")
);

// Find failed requests (4xx, 5xx, or network errors)
List<CapturedRequest> failedRequests = alice.asksFor(NetworkRequests.failed());
int failedCount = alice.asksFor(NetworkRequests.failedCount());

// Find client errors (4xx)
List<CapturedRequest> clientErrors = alice.asksFor(NetworkRequests.clientErrors());

// Find server errors (5xx)
List<CapturedRequest> serverErrors = alice.asksFor(NetworkRequests.serverErrors());

// Clear captured requests between test phases
alice.attemptsTo(CaptureNetworkRequests.clear());
```

### CapturedRequest Properties

Each `CapturedRequest` contains:

| Property | Description |
|----------|-------------|
| `getUrl()` | The request URL |
| `getMethod()` | HTTP method (GET, POST, etc.) |
| `getResourceType()` | Resource type (document, xhr, fetch, stylesheet, etc.) |
| `getRequestHeaders()` | Map of request headers |
| `getStatus()` | Response status code (or null if pending/failed) |
| `getStatusText()` | Response status text |
| `getFailureText()` | Failure reason for network errors |
| `isFailed()` | True if request failed (4xx, 5xx, or network error) |
| `isClientError()` | True if 4xx status |
| `isServerError()` | True if 5xx status |

### Example: Verifying API Calls

```java
@Test
void shouldMakeCorrectApiCalls() {
    alice.attemptsTo(
        CaptureNetworkRequests.duringTest(),
        Navigate.to("https://myapp.com"),
        Click.on(Button.withText("Load Data"))
    );

    // Verify the expected API call was made
    List<CapturedRequest> apiCalls = alice.asksFor(
        NetworkRequests.toUrlContaining("/api/data")
    );

    assertThat(apiCalls).hasSize(1);
    assertThat(apiCalls.get(0).getMethod()).isEqualTo("GET");
    assertThat(apiCalls.get(0).getStatus()).isEqualTo(200);
}
```

## Failure Evidence Capture

:::info New in 5.2.2
Automatic failure evidence capture was added in Serenity BDD 5.2.2.
:::

When a test fails, Serenity Playwright automatically captures diagnostic information and attaches it to the report. This makes debugging test failures much easier.

### Automatic Evidence Collection

When console message or network request capture is enabled, the following evidence is automatically collected on test failure:

- **Page Information**: Current URL and page title
- **Console Errors**: All `console.error()` and `console.warn()` messages
- **Failed Network Requests**: Requests that returned 4xx/5xx status or network errors

This evidence is attached to the Serenity report as "Playwright Failure Evidence".

### Enabling Evidence Capture

Simply enable console and/or network capture at the start of your tests:

```java
@BeforeEach
void setup(Page page) {
    alice = Actor.named("Alice");
    alice.can(BrowseTheWebWithPlaywright.withPage(page));

    // Enable capture for failure evidence
    alice.attemptsTo(
        CaptureConsoleMessages.duringTest(),
        CaptureNetworkRequests.duringTest()
    );
}
```

### Programmatic Access to Evidence

You can also query evidence programmatically for assertions or custom reporting:

```java
import net.serenitybdd.screenplay.playwright.evidence.PlaywrightFailureEvidence;

// Get console errors
List<String> consoleErrors = PlaywrightFailureEvidence.getConsoleErrors(alice);

// Get failed network requests
List<String> failedRequests = PlaywrightFailureEvidence.getFailedRequests(alice);

// Use in assertions
assertThat(consoleErrors).isEmpty();
assertThat(failedRequests).isEmpty();
```

### Example: Detecting JavaScript Errors

```java
@Test
void pageShouldNotHaveJavaScriptErrors() {
    alice.attemptsTo(
        CaptureConsoleMessages.duringTest(),
        Navigate.to("https://myapp.com"),
        Click.on(Button.withText("Submit"))
    );

    // Verify no JavaScript errors occurred
    List<String> errors = alice.asksFor(ConsoleMessages.errors());
    assertThat(errors)
        .describedAs("JavaScript errors on page")
        .isEmpty();
}
```

### Example: Detecting Failed API Calls

```java
@Test
void allApiCallsShouldSucceed() {
    alice.attemptsTo(
        CaptureNetworkRequests.duringTest(),
        Navigate.to("https://myapp.com/dashboard")
    );

    // Verify no API calls failed
    List<CapturedRequest> failedRequests = alice.asksFor(NetworkRequests.failed());
    assertThat(failedRequests)
        .describedAs("Failed network requests")
        .isEmpty();
}
```

## Accessibility Testing

Test accessibility compliance using ARIA snapshots:

```java
import net.serenitybdd.screenplay.playwright.questions.AccessibilitySnapshot;
import com.microsoft.playwright.options.AriaRole;

// Get accessibility snapshot of the entire page
String pageSnapshot = alice.asksFor(AccessibilitySnapshot.ofThePage());

// Get accessibility snapshot of a specific element
String navSnapshot = alice.asksFor(AccessibilitySnapshot.of("#main-nav"));
String formSnapshot = alice.asksFor(AccessibilitySnapshot.of(LOGIN_FORM));

// Get all elements with a specific ARIA role
List<String> buttons = alice.asksFor(AccessibilitySnapshot.allWithRole(AriaRole.BUTTON));
List<String> links = alice.asksFor(AccessibilitySnapshot.allWithRole(AriaRole.LINK));
List<String> headings = alice.asksFor(AccessibilitySnapshot.allWithRole(AriaRole.HEADING));
```

## Visual Regression Testing

Compare screenshots against baseline images:

```java
import net.serenitybdd.screenplay.playwright.assertions.visual.CompareScreenshot;

// Full page comparison
alice.attemptsTo(
    CompareScreenshot.ofPage()
        .againstBaseline("homepage-baseline.png")
        .withThreshold(0.01)  // 1% difference allowed
);

// Element comparison
alice.attemptsTo(
    CompareScreenshot.of("#product-card")
        .againstBaseline("product-card-baseline.png")
);

// With mask for dynamic content
alice.attemptsTo(
    CompareScreenshot.ofPage()
        .againstBaseline("dashboard.png")
        .withMask("#timestamp", "#user-avatar")
);
```

## Device Emulation

Test responsive designs with device emulation:

```java
import net.serenitybdd.screenplay.playwright.interactions.EmulateDevice;

// Emulate specific device
alice.attemptsTo(EmulateDevice.device("iPhone 14"));
alice.attemptsTo(EmulateDevice.device("Pixel 7"));
alice.attemptsTo(EmulateDevice.device("iPad Pro 11"));

// Custom viewport
alice.attemptsTo(EmulateDevice.withViewport(375, 812));

// With device scale factor
alice.attemptsTo(
    EmulateDevice.withViewport(375, 812).andDeviceScaleFactor(2)
);

// With mobile user agent
alice.attemptsTo(
    EmulateDevice.withViewport(375, 812).asMobile()
);
```

## Geolocation

Test location-based features:

```java
import net.serenitybdd.screenplay.playwright.interactions.SetGeolocation;
import net.serenitybdd.screenplay.playwright.interactions.GrantPermissions;

// First grant geolocation permission
alice.attemptsTo(GrantPermissions.for_("geolocation"));

// Set specific coordinates
alice.attemptsTo(SetGeolocation.to(51.5074, -0.1278));  // London

// Use predefined locations
alice.attemptsTo(SetGeolocation.toNewYork());
alice.attemptsTo(SetGeolocation.toLondon());
alice.attemptsTo(SetGeolocation.toTokyo());
alice.attemptsTo(SetGeolocation.toSanFrancisco());
alice.attemptsTo(SetGeolocation.toSydney());
alice.attemptsTo(SetGeolocation.toParis());

// With accuracy
alice.attemptsTo(
    SetGeolocation.to(40.7128, -74.0060).withAccuracy(100)
);

// Clear geolocation
alice.attemptsTo(SetGeolocation.clear());
```

## Permission Management

Grant or clear browser permissions:

```java
import net.serenitybdd.screenplay.playwright.interactions.GrantPermissions;
import net.serenitybdd.screenplay.playwright.interactions.ClearPermissions;

// Grant specific permissions
alice.attemptsTo(GrantPermissions.for_("geolocation"));
alice.attemptsTo(GrantPermissions.for_("notifications", "camera", "microphone"));

// Clear all permissions
alice.attemptsTo(ClearPermissions.all());
```

## Clock Control

Test time-dependent functionality:

```java
import net.serenitybdd.screenplay.playwright.interactions.ControlClock;
import java.time.Instant;

// Install fake clock
alice.attemptsTo(ControlClock.install());

// Set to specific time
alice.attemptsTo(
    ControlClock.setTo(Instant.parse("2024-01-15T10:30:00Z"))
);

// Advance time
alice.attemptsTo(ControlClock.advanceBy(Duration.ofHours(2)));
alice.attemptsTo(ControlClock.advanceBy(Duration.ofMinutes(30)));

// Resume normal time flow
alice.attemptsTo(ControlClock.resume());
```

## Tracing

Record detailed traces for debugging:

```java
import net.serenitybdd.screenplay.playwright.interactions.tracing.StartTracing;
import net.serenitybdd.screenplay.playwright.interactions.tracing.StopTracing;

// Start tracing with options
alice.attemptsTo(
    StartTracing.withScreenshots()
        .andSnapshots()
        .named("login-flow")
);

// ... perform test actions ...

// Stop and save trace
alice.attemptsTo(
    StopTracing.andSaveTo(Paths.get("traces/login-flow.zip"))
);

// View trace: npx playwright show-trace traces/login-flow.zip
```

Trace options:
- `withScreenshots()` - Include screenshots in trace
- `andSnapshots()` - Include DOM snapshots
- `andSources()` - Include source files
- `named(String)` - Set trace name

## Session State Persistence

:::info New in 5.2.2
Session state persistence was added in Serenity BDD 5.2.2.
:::

Save and restore browser session state (cookies, localStorage, sessionStorage) to speed up tests and share authenticated sessions.

### Saving Session State

```java
import net.serenitybdd.screenplay.playwright.interactions.SaveSessionState;

// Save to a specific path
Path sessionPath = Paths.get("target/sessions/authenticated.json");
alice.attemptsTo(
    SaveSessionState.toPath(sessionPath)
);

// Save to default location with a name
// Saves to: target/playwright/session-state/{name}.json
alice.attemptsTo(
    SaveSessionState.toFile("admin-session")
);
```

### Restoring Session State

```java
import net.serenitybdd.screenplay.playwright.interactions.RestoreSessionState;

// Restore from a specific path
alice.attemptsTo(
    RestoreSessionState.fromPath(Paths.get("target/sessions/authenticated.json"))
);

// Restore from default location
alice.attemptsTo(
    RestoreSessionState.fromFile("admin-session")
);
```

### Use Case: Reusing Authenticated Sessions

A common pattern is to log in once and reuse the session across multiple tests:

```java
public class AuthenticationSetup {

    private static final Path SESSION_FILE = Paths.get("target/sessions/logged-in.json");

    @BeforeAll
    static void setupAuthenticatedSession() {
        Actor setup = Actor.named("Setup")
            .whoCan(BrowseTheWebWithPlaywright.usingTheDefaultConfiguration());

        setup.attemptsTo(
            Navigate.to("https://myapp.com/login"),
            Enter.theValue("admin@example.com").into("#email"),
            Enter.theValue("password123").into("#password"),
            Click.on(Button.withText("Login")),

            // Save the authenticated session
            SaveSessionState.toPath(SESSION_FILE)
        );

        setup.wrapUp();
    }
}

// In your tests
@Test
void shouldAccessDashboard() {
    alice.attemptsTo(
        // Restore the pre-authenticated session
        RestoreSessionState.fromPath(SESSION_FILE),

        // Navigate directly to protected page
        Navigate.to("https://myapp.com/dashboard")
    );

    // User is already logged in!
    assertThat(alice.asksFor(Text.of("h1"))).isEqualTo("Dashboard");
}
```

### Session State Contents

The saved session state is a JSON file containing:
- **Cookies**: All cookies for the browser context
- **Origins**: localStorage and sessionStorage data for each origin

This allows you to:
- Skip login steps in tests (faster execution)
- Share authentication across test classes
- Create session fixtures for different user roles
- Test session expiration and refresh scenarios

### Example: Multiple User Roles

```java
public class SessionFixtures {

    public static void createAdminSession() {
        // Login as admin and save session
        Actor admin = createActor();
        admin.attemptsTo(
            Navigate.to("https://myapp.com/login"),
            Enter.theValue("admin@example.com").into("#email"),
            Enter.theValue("adminpass").into("#password"),
            Click.on(Button.withText("Login")),
            SaveSessionState.toFile("admin-session")
        );
        admin.wrapUp();
    }

    public static void createUserSession() {
        // Login as regular user and save session
        Actor user = createActor();
        user.attemptsTo(
            Navigate.to("https://myapp.com/login"),
            Enter.theValue("user@example.com").into("#email"),
            Enter.theValue("userpass").into("#password"),
            Click.on(Button.withText("Login")),
            SaveSessionState.toFile("user-session")
        );
        user.wrapUp();
    }
}

// In admin tests
@Test
void adminShouldSeeAdminPanel() {
    alice.attemptsTo(
        RestoreSessionState.fromFile("admin-session"),
        Navigate.to("https://myapp.com/admin")
    );
    assertThat(alice.asksFor(Presence.of("#admin-panel"))).isTrue();
}

// In user tests
@Test
void userShouldNotSeeAdminPanel() {
    alice.attemptsTo(
        RestoreSessionState.fromFile("user-session"),
        Navigate.to("https://myapp.com/admin")
    );
    assertThat(alice.asksFor(Text.of("h1"))).isEqualTo("Access Denied");
}
```

## PDF Generation

Generate PDFs from pages (Chromium only, headless mode):

```java
import net.serenitybdd.screenplay.playwright.interactions.GeneratePDF;

// Basic PDF generation
alice.attemptsTo(
    GeneratePDF.ofCurrentPage()
        .andSaveTo(Paths.get("output/report.pdf"))
);

// With options
alice.attemptsTo(
    GeneratePDF.ofCurrentPage()
        .withFormat("A4")
        .inLandscape()
        .withMargins("1cm", "1cm", "1cm", "1cm")
        .withHeaderTemplate("<div>Header</div>")
        .withFooterTemplate("<div>Page <span class='pageNumber'></span></div>")
        .displayHeaderAndFooter()
        .printBackground()
        .andSaveTo(Paths.get("output/report.pdf"))
);
```

## Switching Contexts

### Frames

Work with iframes:

```java
// Switch to frame by name or ID
alice.attemptsTo(Switch.toFrame("payment-iframe"));

// Switch to frame by Target
alice.attemptsTo(Switch.toFrame(Target.the("payment").locatedBy("#payment-frame")));

// Switch back to main frame
alice.attemptsTo(Switch.toMainFrame());
```

### Windows and Tabs

Handle multiple windows and tabs:

```java
// Switch to new window/tab
alice.attemptsTo(Switch.toNewWindow());

// Close current window
alice.attemptsTo(CloseCurrentWindow.now());
```

## Best Practices

### Use Target Constants

Define targets as constants for reusability and maintainability:

```java
public class LoginPage {
    public static Target EMAIL_FIELD = Target.the("email field")
        .locatedBy("#email");
    public static Target PASSWORD_FIELD = Target.the("password field")
        .locatedBy("#password");
    public static Target LOGIN_BUTTON = Target.the("login button")
        .locatedBy("role=button[name='Log in']");
}
```

### Prefer Role Selectors

Use ARIA role selectors for more resilient tests:

```java
// Instead of CSS
Target.the("Submit").locatedBy("button.primary-btn")

// Prefer role selector
Target.the("Submit").locatedBy("role=button[name='Submit']")
```

### Use UI Element Factories

For common elements, use the UI element factories:

```java
// Instead of
Click.on(Target.the("Add button").locatedBy("role=button[name='Add to Cart']"))

// Use
Click.on(Button.withText("Add to Cart"))
```

### Network Mocking for Isolation

Mock API responses to isolate UI tests:

```java
@BeforeEach
void setupMocks() {
    actor.attemptsTo(
        InterceptNetwork.requestsTo("**/api/products")
            .andRespondWithJson(200, mockProducts)
    );
}
```

### Use Tracing for Debugging

Enable tracing when debugging test failures:

```java
alice.attemptsTo(
    StartTracing.withScreenshots().andSnapshots()
);

// Run your test...

alice.attemptsTo(
    StopTracing.andSaveTo(Paths.get("trace.zip"))
);
// View with: npx playwright show-trace trace.zip
```

## Quick Reference Tables

### All Interactions

The following tables provide a complete reference of all available Playwright Screenplay interactions.

#### Element Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Click.on(target)` | Click on an element | `Click.on("#submit")` |
| `DoubleClick.on(target)` | Double-click on an element | `DoubleClick.on("#item")` |
| `RightClick.on(target)` | Right-click (context menu) on an element | `RightClick.on("#file")` |
| `Hover.over(target)` | Move mouse over an element | `Hover.over("#menu")` |
| `Focus.on(target)` | Set focus to an element | `Focus.on("#search")` |

#### Text Input Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Enter.theValue(text).into(target)` | Type text into a field | `Enter.theValue("john@test.com").into("#email")` |
| `Clear.field(target)` | Clear an input field | `Clear.field("#search")` |
| `Press.key(key)` | Press a keyboard key | `Press.key("Enter")` |
| `Press.key(combo)` | Press a key combination | `Press.key("Control+a")` |
| `Press.keys(keys...)` | Press multiple keys in sequence | `Press.keys("Tab", "Tab", "Enter")` |

#### Checkbox & Radio Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Check.checkbox(target)` | Check a checkbox | `Check.checkbox("#agree")` |
| `Uncheck.checkbox(target)` | Uncheck a checkbox | `Uncheck.checkbox("#newsletter")` |

#### Dropdown Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `SelectFromOptions.byVisibleText(text).from(target)` | Select by visible text | `SelectFromOptions.byVisibleText("Red").from("#color")` |
| `SelectFromOptions.byValue(value).from(target)` | Select by value attribute | `SelectFromOptions.byValue("red").from("#color")` |
| `SelectFromOptions.byIndex(index).from(target)` | Select by index (0-based) | `SelectFromOptions.byIndex(2).from("#color")` |
| `DeselectFromOptions.byValue(value).from(target)` | Deselect by value | `DeselectFromOptions.byValue("red").from("#colors")` |
| `DeselectFromOptions.byVisibleText(text).from(target)` | Deselect by visible text | `DeselectFromOptions.byVisibleText("Red").from("#colors")` |
| `DeselectFromOptions.byIndex(index).from(target)` | Deselect by index | `DeselectFromOptions.byIndex(0).from("#colors")` |
| `DeselectFromOptions.all().from(target)` | Deselect all options | `DeselectFromOptions.all().from("#colors")` |

#### Scrolling Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Scroll.to(target)` | Scroll element into view | `Scroll.to("#footer")` |
| `Scroll.to(target).andAlignToTop()` | Scroll with top alignment | `Scroll.to("#section").andAlignToTop()` |
| `Scroll.to(target).andAlignToCenter()` | Scroll with center alignment | `Scroll.to("#section").andAlignToCenter()` |
| `Scroll.to(target).andAlignToBottom()` | Scroll with bottom alignment | `Scroll.to("#section").andAlignToBottom()` |
| `Scroll.toTop()` | Scroll to page top | `Scroll.toTop()` |
| `Scroll.toBottom()` | Scroll to page bottom | `Scroll.toBottom()` |
| `Scroll.by(deltaX, deltaY)` | Scroll by pixel amount | `Scroll.by(0, 500)` |
| `Scroll.toPosition(x, y)` | Scroll to absolute position | `Scroll.toPosition(0, 1000)` |

#### Drag and Drop Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Drag.from(source).to(target)` | Drag from source to target | `Drag.from("#item").to("#dropzone")` |
| `Drag.the(source).onto(target)` | Alternative fluent syntax | `Drag.the("#card").onto("#column")` |

#### Navigation Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Navigate.to(url)` | Navigate to a URL | `Navigate.to("https://example.com")` |
| `Navigate.toTheBaseUrl()` | Navigate to configured base URL | `Navigate.toTheBaseUrl()` |

#### Frame & Window Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Switch.toFrame(nameOrId)` | Switch to iframe by name/ID | `Switch.toFrame("payment-iframe")` |
| `Switch.toFrame(target)` | Switch to iframe by Target | `Switch.toFrame(PAYMENT_FRAME)` |
| `Switch.toMainFrame()` | Switch back to main frame | `Switch.toMainFrame()` |
| `Switch.toNewWindow()` | Switch to new window/tab | `Switch.toNewWindow()` |
| `CloseCurrentWindow.now()` | Close current window | `CloseCurrentWindow.now()` |

#### File Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Upload.file(path).to(target)` | Upload a file | `Upload.file(Paths.get("doc.pdf")).to("#upload")` |
| `WaitForDownload.whilePerforming(action)` | Wait for download during action | `WaitForDownload.whilePerforming(Click.on("#download"))` |
| `WaitForDownload...andSaveTo(path)` | Save download to path | `WaitForDownload.whilePerforming(...).andSaveTo(path)` |

#### JavaScript Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `Evaluate.javascript(script)` | Execute JavaScript | `Evaluate.javascript("window.scrollTo(0,0)")` |

#### Wait Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `WaitUntil.the(target).isVisible()` | Wait for element visibility | `WaitUntil.the("#modal").isVisible()` |
| `WaitUntil.the(target).isNotVisible()` | Wait for element to hide | `WaitUntil.the("#spinner").isNotVisible()` |
| `WaitUntil.the(target).isHidden()` | Wait for element to be hidden | `WaitUntil.the("#loading").isHidden()` |
| `WaitUntil...forNoMoreThan(duration)` | Set custom timeout | `WaitUntil.the("#data").isVisible().forNoMoreThan(Duration.ofSeconds(10))` |

#### Network Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `InterceptNetwork.requestsTo(pattern).andRespondWith(options)` | Mock response with options | `InterceptNetwork.requestsTo("**/api/**").andRespondWith(...)` |
| `InterceptNetwork.requestsTo(pattern).andRespondWithJson(status, data)` | Mock JSON response | `InterceptNetwork.requestsTo("**/users").andRespondWithJson(200, users)` |
| `InterceptNetwork.requestsTo(pattern).andHandle(handler)` | Custom request handler | `InterceptNetwork.requestsTo("**/api/**").andHandle(route -> ...)` |
| `InterceptNetwork.requestsTo(pattern).andAbort()` | Block requests | `InterceptNetwork.requestsTo("**/analytics/**").andAbort()` |
| `RemoveRoutes.all()` | Remove all route handlers | `RemoveRoutes.all()` |
| `RemoveRoutes.forUrl(pattern)` | Remove routes for pattern | `RemoveRoutes.forUrl("**/api/**")` |

#### Device & Environment Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `EmulateDevice.device(name)` | Emulate a device | `EmulateDevice.device("iPhone 14")` |
| `EmulateDevice.withViewport(width, height)` | Set custom viewport | `EmulateDevice.withViewport(375, 812)` |
| `EmulateDevice...andDeviceScaleFactor(factor)` | Set device scale | `EmulateDevice.withViewport(375, 812).andDeviceScaleFactor(2)` |
| `EmulateDevice...asMobile()` | Add mobile user agent | `EmulateDevice.withViewport(375, 812).asMobile()` |
| `SetGeolocation.to(lat, lng)` | Set geolocation | `SetGeolocation.to(51.5074, -0.1278)` |
| `SetGeolocation.to(lat, lng).withAccuracy(m)` | Set geolocation with accuracy | `SetGeolocation.to(40.7128, -74.0060).withAccuracy(100)` |
| `SetGeolocation.toNewYork()` | Set to New York | `SetGeolocation.toNewYork()` |
| `SetGeolocation.toLondon()` | Set to London | `SetGeolocation.toLondon()` |
| `SetGeolocation.toTokyo()` | Set to Tokyo | `SetGeolocation.toTokyo()` |
| `SetGeolocation.toSanFrancisco()` | Set to San Francisco | `SetGeolocation.toSanFrancisco()` |
| `SetGeolocation.toSydney()` | Set to Sydney | `SetGeolocation.toSydney()` |
| `SetGeolocation.toParis()` | Set to Paris | `SetGeolocation.toParis()` |
| `SetGeolocation.clear()` | Clear geolocation | `SetGeolocation.clear()` |
| `GrantPermissions.for_(permissions...)` | Grant browser permissions | `GrantPermissions.for_("geolocation", "camera")` |
| `ClearPermissions.all()` | Clear all permissions | `ClearPermissions.all()` |

#### Clock Control Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `ControlClock.install()` | Install fake clock | `ControlClock.install()` |
| `ControlClock.setTo(instant)` | Set clock to specific time | `ControlClock.setTo(Instant.parse("2024-01-15T10:30:00Z"))` |
| `ControlClock.advanceBy(duration)` | Advance clock | `ControlClock.advanceBy(Duration.ofHours(2))` |
| `ControlClock.resume()` | Resume normal time flow | `ControlClock.resume()` |

#### Debugging & Tracing Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `StartTracing.withScreenshots()` | Start trace with screenshots | `StartTracing.withScreenshots()` |
| `StartTracing...andSnapshots()` | Include DOM snapshots | `StartTracing.withScreenshots().andSnapshots()` |
| `StartTracing...andSources()` | Include source files | `StartTracing.withScreenshots().andSources()` |
| `StartTracing...named(name)` | Set trace name | `StartTracing.withScreenshots().named("login-test")` |
| `StopTracing.andSaveTo(path)` | Stop and save trace | `StopTracing.andSaveTo(Paths.get("trace.zip"))` |
| `CaptureConsoleMessages.duringTest()` | Start capturing console | `CaptureConsoleMessages.duringTest()` |
| `CaptureConsoleMessages.clear()` | Clear captured messages | `CaptureConsoleMessages.clear()` |
| `CheckConsole.forErrors()` | Fail if console errors found | `CheckConsole.forErrors()` |
| `CheckConsole.forWarnings()` | Fail if console warnings found | `CheckConsole.forWarnings()` |
| `CheckConsole.forErrorsAndWarnings()` | Fail if errors or warnings found | `CheckConsole.forErrorsAndWarnings()` |
| `CheckConsole...andReportOnly()` | Report without failing | `CheckConsole.forErrors().andReportOnly()` |
| `ReportConsoleMessages.all()` | Report all console messages | `ReportConsoleMessages.all()` |
| `ReportConsoleMessages.errors()` | Report console errors | `ReportConsoleMessages.errors()` |
| `ReportConsoleMessages.errorsAndWarnings()` | Report errors and warnings | `ReportConsoleMessages.errorsAndWarnings()` |
| `CaptureNetworkRequests.duringTest()` | Start capturing network | `CaptureNetworkRequests.duringTest()` |
| `CaptureNetworkRequests.clear()` | Clear captured requests | `CaptureNetworkRequests.clear()` |

#### Session State Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `SaveSessionState.toPath(path)` | Save session to specific path | `SaveSessionState.toPath(Paths.get("session.json"))` |
| `SaveSessionState.toFile(name)` | Save session to default location | `SaveSessionState.toFile("admin-session")` |
| `RestoreSessionState.fromPath(path)` | Restore session from path | `RestoreSessionState.fromPath(Paths.get("session.json"))` |
| `RestoreSessionState.fromFile(name)` | Restore session from default location | `RestoreSessionState.fromFile("admin-session")` |

#### API Request Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `APIRequest.get(url)` | Make GET request | `APIRequest.get("https://api.example.com/users")` |
| `APIRequest.post(url)` | Make POST request | `APIRequest.post("https://api.example.com/users")` |
| `APIRequest.put(url)` | Make PUT request | `APIRequest.put("https://api.example.com/users/1")` |
| `APIRequest.patch(url)` | Make PATCH request | `APIRequest.patch("https://api.example.com/users/1")` |
| `APIRequest.delete(url)` | Make DELETE request | `APIRequest.delete("https://api.example.com/users/1")` |
| `APIRequest.head(url)` | Make HEAD request | `APIRequest.head("https://api.example.com/users/1")` |
| `APIRequest...withJsonBody(object)` | Set JSON request body | `APIRequest.post(url).withJsonBody(Map.of("name", "John"))` |
| `APIRequest...withBody(string)` | Set string request body | `APIRequest.post(url).withBody("<xml>data</xml>")` |
| `APIRequest...withHeader(name, value)` | Add request header | `APIRequest.get(url).withHeader("Authorization", "Bearer token")` |
| `APIRequest...withQueryParam(name, value)` | Add query parameter | `APIRequest.get(url).withQueryParam("page", "1")` |
| `APIRequest...withContentType(type)` | Set Content-Type | `APIRequest.post(url).withContentType("application/xml")` |
| `APIRequest...withTimeout(ms)` | Set request timeout | `APIRequest.get(url).withTimeout(30000)` |
| `APIRequest...failOnStatusCode(boolean)` | Fail on non-2xx status | `APIRequest.get(url).failOnStatusCode(true)` |

#### PDF Generation Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `GeneratePDF.ofCurrentPage().andSaveTo(path)` | Generate PDF | `GeneratePDF.ofCurrentPage().andSaveTo(Paths.get("page.pdf"))` |
| `GeneratePDF...withFormat(format)` | Set paper format | `GeneratePDF.ofCurrentPage().withFormat("A4")` |
| `GeneratePDF...inLandscape()` | Use landscape orientation | `GeneratePDF.ofCurrentPage().inLandscape()` |
| `GeneratePDF...withMargins(t, r, b, l)` | Set margins | `GeneratePDF.ofCurrentPage().withMargins("1cm", "1cm", "1cm", "1cm")` |
| `GeneratePDF...printBackground()` | Include background graphics | `GeneratePDF.ofCurrentPage().printBackground()` |
| `GeneratePDF...displayHeaderAndFooter()` | Show header/footer | `GeneratePDF.ofCurrentPage().displayHeaderAndFooter()` |

#### Visual Testing Interactions

| Interaction | Description | Example |
|-------------|-------------|---------|
| `CompareScreenshot.ofPage().againstBaseline(name)` | Compare full page | `CompareScreenshot.ofPage().againstBaseline("home.png")` |
| `CompareScreenshot.of(target).againstBaseline(name)` | Compare element | `CompareScreenshot.of("#card").againstBaseline("card.png")` |
| `CompareScreenshot...withThreshold(threshold)` | Set diff threshold | `CompareScreenshot.ofPage().againstBaseline("x.png").withThreshold(0.01)` |
| `CompareScreenshot...withMask(targets...)` | Mask dynamic elements | `CompareScreenshot.ofPage().againstBaseline("x.png").withMask("#time")` |

---

### All Questions

The following tables provide a complete reference of all available Playwright Screenplay questions.

#### Element State Questions

| Question | Return Type | Description | Example |
|----------|-------------|-------------|---------|
| `Presence.of(target)` | `Boolean` | Element exists in DOM | `actor.asksFor(Presence.of("#modal"))` |
| `Absence.of(target)` | `Boolean` | Element not present | `actor.asksFor(Absence.of("#error"))` |
| `Visibility.of(target)` | `Boolean` | Element is visible | `actor.asksFor(Visibility.of("#popup"))` |
| `Enabled.of(target)` | `Boolean` | Element is enabled | `actor.asksFor(Enabled.of("#submit"))` |
| `SelectedStatus.of(target)` | `Boolean` | Checkbox/radio is selected | `actor.asksFor(SelectedStatus.of("#agree"))` |

#### Element Content Questions

| Question | Return Type | Description | Example |
|----------|-------------|-------------|---------|
| `Text.of(target)` | `String` | Get element text content | `actor.asksFor(Text.of("#title"))` |
| `Text.ofEach(target)` | `List<String>` | Get text of all matching elements | `actor.asksFor(Text.ofEach(".item"))` |
| `Value.of(target)` | `String` | Get input field value | `actor.asksFor(Value.of("#email"))` |
| `Attribute.of(target).named(attr)` | `String` | Get attribute value | `actor.asksFor(Attribute.of("#link").named("href"))` |
| `CSSValue.of(target).named(prop)` | `String` | Get CSS property value | `actor.asksFor(CSSValue.of("#box").named("color"))` |

#### Page Information Questions

| Question | Return Type | Description | Example |
|----------|-------------|-------------|---------|
| `CurrentUrl.ofThePage()` | `String` | Get current page URL | `actor.asksFor(CurrentUrl.ofThePage())` |
| `PageTitle.ofThePage()` | `String` | Get page title | `actor.asksFor(PageTitle.ofThePage())` |

#### Download Questions

| Question | Return Type | Description | Example |
|----------|-------------|-------------|---------|
| `DownloadedFile.suggestedFilename()` | `String` | Get suggested filename | `actor.asksFor(DownloadedFile.suggestedFilename())` |
| `DownloadedFile.url()` | `String` | Get download URL | `actor.asksFor(DownloadedFile.url())` |
| `DownloadedFile.path()` | `Path` | Get download file path | `actor.asksFor(DownloadedFile.path())` |
| `DownloadedFile.failure()` | `String` | Get failure reason (null if success) | `actor.asksFor(DownloadedFile.failure())` |
| `DownloadedFile.download()` | `Download` | Get Playwright Download object | `actor.asksFor(DownloadedFile.download())` |

#### Console Message Questions

| Question | Return Type | Description | Example |
|----------|-------------|-------------|---------|
| `ConsoleMessages.all()` | `List<String>` | Get all console messages | `actor.asksFor(ConsoleMessages.all())` |
| `ConsoleMessages.errors()` | `List<String>` | Get console errors | `actor.asksFor(ConsoleMessages.errors())` |
| `ConsoleMessages.warnings()` | `List<String>` | Get console warnings | `actor.asksFor(ConsoleMessages.warnings())` |
| `ConsoleMessages.logs()` | `List<String>` | Get console logs | `actor.asksFor(ConsoleMessages.logs())` |
| `ConsoleMessages.info()` | `List<String>` | Get console info messages | `actor.asksFor(ConsoleMessages.info())` |
| `ConsoleMessages.containing(text)` | `List<String>` | Get messages containing text | `actor.asksFor(ConsoleMessages.containing("error"))` |
| `ConsoleMessages.count()` | `Integer` | Get total message count | `actor.asksFor(ConsoleMessages.count())` |
| `ConsoleMessages.errorCount()` | `Integer` | Get error count | `actor.asksFor(ConsoleMessages.errorCount())` |
| `ConsoleMessages.allCaptured()` | `List<CapturedConsoleMessage>` | Get full message objects | `actor.asksFor(ConsoleMessages.allCaptured())` |

#### Accessibility Questions

| Question | Return Type | Description | Example |
|----------|-------------|-------------|---------|
| `AccessibilitySnapshot.ofThePage()` | `String` | Get page accessibility tree | `actor.asksFor(AccessibilitySnapshot.ofThePage())` |
| `AccessibilitySnapshot.of(target)` | `String` | Get element accessibility tree | `actor.asksFor(AccessibilitySnapshot.of("#nav"))` |
| `AccessibilitySnapshot.allWithRole(role)` | `List<String>` | Get elements by ARIA role | `actor.asksFor(AccessibilitySnapshot.allWithRole(AriaRole.BUTTON))` |

#### Network Request Questions

| Question | Return Type | Description | Example |
|----------|-------------|-------------|---------|
| `NetworkRequests.all()` | `List<CapturedRequest>` | Get all captured requests | `actor.asksFor(NetworkRequests.all())` |
| `NetworkRequests.count()` | `Integer` | Get total request count | `actor.asksFor(NetworkRequests.count())` |
| `NetworkRequests.withMethod(method)` | `List<CapturedRequest>` | Filter by HTTP method | `actor.asksFor(NetworkRequests.withMethod("POST"))` |
| `NetworkRequests.toUrlContaining(text)` | `List<CapturedRequest>` | Filter by URL substring | `actor.asksFor(NetworkRequests.toUrlContaining("/api/"))` |
| `NetworkRequests.matching(pattern)` | `List<CapturedRequest>` | Filter by glob pattern | `actor.asksFor(NetworkRequests.matching("**/*.js"))` |
| `NetworkRequests.failed()` | `List<CapturedRequest>` | Get failed requests | `actor.asksFor(NetworkRequests.failed())` |
| `NetworkRequests.failedCount()` | `Integer` | Get failed request count | `actor.asksFor(NetworkRequests.failedCount())` |
| `NetworkRequests.clientErrors()` | `List<CapturedRequest>` | Get 4xx errors | `actor.asksFor(NetworkRequests.clientErrors())` |
| `NetworkRequests.serverErrors()` | `List<CapturedRequest>` | Get 5xx errors | `actor.asksFor(NetworkRequests.serverErrors())` |

#### API Response Questions

| Question | Return Type | Description | Example |
|----------|-------------|-------------|---------|
| `LastAPIResponse.statusCode()` | `Integer` | Get response status code | `actor.asksFor(LastAPIResponse.statusCode())` |
| `LastAPIResponse.ok()` | `Boolean` | Check if status is 2xx | `actor.asksFor(LastAPIResponse.ok())` |
| `LastAPIResponse.body()` | `String` | Get response body as string | `actor.asksFor(LastAPIResponse.body())` |
| `LastAPIResponse.jsonBody()` | `Map<String, Object>` | Parse JSON response as Map | `actor.asksFor(LastAPIResponse.jsonBody())` |
| `LastAPIResponse.jsonBodyAsList()` | `List<Map<String, Object>>` | Parse JSON array response | `actor.asksFor(LastAPIResponse.jsonBodyAsList())` |
| `LastAPIResponse.headers()` | `Map<String, String>` | Get all response headers | `actor.asksFor(LastAPIResponse.headers())` |
| `LastAPIResponse.header(name)` | `String` | Get specific header | `actor.asksFor(LastAPIResponse.header("Content-Type"))` |
| `LastAPIResponse.url()` | `String` | Get final URL (after redirects) | `actor.asksFor(LastAPIResponse.url())` |

---

### UI Element Factories

Factory classes for locating common UI elements.

| Factory | Methods | Example |
|---------|---------|---------|
| `Button` | `withText(text)`, `withNameOrId(id)`, `withAriaLabel(label)`, `containingText(text)`, `locatedBy(selector)` | `Button.withText("Submit")` |
| `InputField` | `withNameOrId(id)`, `withPlaceholder(text)`, `withLabel(label)`, `withAriaLabel(label)`, `locatedBy(selector)` | `InputField.withPlaceholder("Email")` |
| `Link` | `withText(text)`, `containingText(text)`, `withTitle(title)`, `locatedBy(selector)` | `Link.withText("Learn more")` |
| `Checkbox` | `withLabel(label)`, `withNameOrId(id)`, `withValue(value)`, `locatedBy(selector)` | `Checkbox.withLabel("I agree")` |
| `RadioButton` | `withLabel(label)`, `withNameOrId(id)`, `withValue(value)`, `locatedBy(selector)` | `RadioButton.withValue("express")` |
| `Dropdown` | `withLabel(label)`, `withNameOrId(id)`, `locatedBy(selector)` | `Dropdown.withLabel("Country")` |
| `Label` | `withText(text)`, `withExactText(text)`, `forFieldId(id)`, `locatedBy(selector)` | `Label.forFieldId("email")` |
| `Image` | `withAltText(alt)`, `withSrc(src)`, `withSrcContaining(text)`, `locatedBy(selector)` | `Image.withAltText("Logo")` |

---

## Migration from WebDriver

When migrating from `serenity-screenplay-webdriver`:

1. **Ability Change**:
   - Replace `BrowseTheWeb` with `BrowseTheWebWithPlaywright`

2. **Selector Syntax**:
   - CSS and XPath work similarly
   - Add role selectors for more robust tests
   - Use `>>` for chaining selectors instead of nesting

3. **Waiting**:
   - Playwright auto-waits; explicit waits are less necessary
   - Remove most `WaitUntil` calls

4. **Locator Methods**:
   - `By.id("x")` becomes `"#x"`
   - `By.cssSelector("x")` becomes `"x"`
   - `By.xpath("x")` becomes `"xpath=x"`

5. **New Capabilities**:
   - Use network interception for mocking APIs
   - Use tracing for debugging
   - Use device emulation for responsive testing

## Complete Example

```java
import com.microsoft.playwright.Page;
import net.serenitybdd.annotations.SerenityPlaywright;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import net.serenitybdd.screenplay.playwright.interactions.*;
import net.serenitybdd.screenplay.playwright.questions.*;
import net.serenitybdd.screenplay.playwright.ui.*;
import com.microsoft.playwright.junit.UsePlaywright;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import static org.assertj.core.api.Assertions.assertThat;

@SerenityPlaywright
@UsePlaywright
class ShoppingCartTest {

    Actor alice;

    @BeforeEach
    void setup(Page page) {
        alice = Actor.named("Alice");
        alice.can(BrowseTheWebWithPlaywright.withPage(page));
    }

    @Test
    void shouldAddItemToCart() {
        alice.attemptsTo(
            Navigate.to("https://shop.example.com"),
            Click.on(Button.withText("Electronics")),
            Click.on(Link.containingText("Laptop")),
            SelectFromOptions.byVisibleText("16GB").from(Dropdown.withLabel("Memory")),
            Click.on(Button.withText("Add to Cart"))
        );

        String cartCount = alice.asksFor(Text.of("#cart-count"));
        assertThat(cartCount).isEqualTo("1");

        List<String> cartItems = alice.asksFor(Text.ofEach(".cart-item-name"));
        assertThat(cartItems).contains("Laptop");
    }
}
```

## Further Reading

- [Playwright Java Documentation](https://playwright.dev/java/docs/intro)
- [Serenity Screenplay Pattern](screenplay_fundamentals)
- [Web Testing with WebDriver](screenplay_webdriver)


---

<!-- https://serenity-bdd.github.io/docs/screenplay/screenplay_rest -->

# Working with REST APIs using Serenity Screenplay

The Screenplay pattern is an approach to writing automated acceptance tests that helps us write cleaner, more maintainable, more scalable automation code. A Screenplay test talks first and foremost about the tasks a user performs, in business language, rather than diving into the details about buttons, clicks and input fields. Focusing on the business tasks makes our tests more readable, more maintainable, and easier to scale.

Screenplay is often associated with UI testing. Interestingly, the name of the pattern is actually unrelated to screens or user interfaces; it comes from a theatre metaphor, where actors play roles on a stage following a predefined script (the "screenplay"), and was coined by Antony Marcano and Andy Palmer around 2015. The pattern itself goes back further than that, and has been around in various forms since it was first proposed by Antony Marcano in 2007.

But Screenplay is also a great fit for API or web service tests. In particular, Screenplay is ideal when we want to include API and UI activities in the same test. For example, we might have an API task to set up some test data, a UI task to illustrate how a user interacts with this data, then another API task to check the new state of the database.

You can get a taste of what REST API interactions using Serenity Screenplay look like here:

```java
@Test
public void list_all_users() {

    Actor sam = Actor.named("Sam the supervisor")
                     .whoCan(CallAnApi.at(theRestApiBaseUrl));

    sam.attemptsTo(
            Get.resource("/users")
    );

    sam.should(
            seeThatResponse("all the expected users should be returned",
                    response -> response.statusCode(200)
                                        .body("data.first_name", hasItems("George", "Janet", "Emma")))
    );
}
```

Serenity Screenplay uses [Rest-Assured](https://rest-assured.io) to interact with rest endpoints, and to query the responses. Rest-Assured provides us with a simple but extremely powerful Java DSL that allows us to test and virtually any kind of REST end point. Its highly readable code is also an ideal fit for Screenplay.

## Setting up your project

To test REST API services with Screenplay, you need to add the `serenity-screenplay-rest` dependency to your project. In Maven, add the following to the dependencies in your `pom.xml` file:

```xml
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-screenplay-rest</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
```

And for Gradle, you can add the same dependency to your `build.gradle` file:

```groovy
testCompile "net.serenity-bdd:serenity-screenplay-rest:${serenityVersion}"
```

## Defining a base URI

When you test a REST API, it is convenient to be able to use the same tests against different environments. You may want to run your tests against a server running on your local machine, against a QA server, or even against a production box. And you don't want to have to change your tests whenever you test against a different environment.

For example, in this chapter, we will be demonstrating the features of `serenity-screenplay-rest` using the [ResReq](https://reqres.in) application (see below). If you have a reliable internet connection, you can run your tests against the live ResReq server at https://reqres.in/api/. Or if you are running the ResReq server locally, you would access endpoints at http://localhost:5000/api.


**The ResReq test application**

The [ResReq](https://reqres.in) application is an open source application written by [Ben Howdle](http://benhowdle.im/) that makes it easy to experiment with REST APIs. It is hosted on Digital Ocean, where you can access it online at https://reqres.in/api/. Alternatively, you can also download the application from the project's [repository on Github](https://github.com/benhowdle89/reqres), and run it locally. When you run the application on your own machine, the REST API will be available at http://localhost:5000/api.



### Reading from the Serenity config file

In Serenity BDD, you can define the base URL for your REST API directly in the `serenity.properties` or `serenity.conf` file for your project.
Here is an example from a `serenity.conf` file:

```json
restapi {
      baseurl = "https://reqres.in/api"
}
```

Any test can read values from the Serenity configuration files simply by creating a field of type `EnvironmentVariables` in the test.
You can then fetch the property, and provide a default value to use if the property hasn't been defined, as shown below:

```java
theRestApiBaseUrl = environmentVariables.optionalProperty("restapi.baseurl")
                                        .orElse("https://reqres.in/api");
```

### Setting the API Url from the command line

You can override the default URL defined this way simply by providing a system property on the command line, like this:

```
mvn verify -Drestapi.baseurl=http://localhost:5000/api
```

### Configuring the base API URL in Maven

If you are using Maven, a more convenient approach may be to use [Maven Profiles](http://maven.apache.org/guides/introduction/introduction-to-profiles.html).
In your `pom.xml` file, you define up different Maven profiles for each environment, and set the `restapi.baseurl` property accordingly:

```xml
<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <restapi.baseurl>http://localhost:5000/api</restapi.baseurl>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <restapi.baseurl>https://reqres.in/api</restapi.baseurl>
        </properties>
    </profile>
</profiles>
```

For this to work properly, you also need to ensure that the `restapi.baseurl` is passed correctly to your tests.
You do this by using the `systemPropertyVariables` tag in the `maven-failsafe-plugin' configuration, as shown here:

```xml
<build>
    <plugins>
        <plugin>
            <artifactId>maven-failsafe-plugin</artifactId>
            <version>2.20</version>
            <configuration>
                <includes>
                    <include>**/When*.java</include>
                    <include>**/*Feature.java</include>
                </includes>
                <systemPropertyVariables>
                    <restapi.baseurl>${restapi.baseurl}</restapi.baseurl>
                </systemPropertyVariables>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>integration-test</goal>
                        <goal>verify</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        ...
```

You can then run the tests with Maven using the `-P` option:

```
$ mvn verify -Pdev
```

## Configuring the actor - the CallAnApi ability

In Screenplay, tests describe behaviour in terms of _actors_, who achieve their business goals by performing _tasks_.
These tasks usually involve _interacting_ with the application in some way.
And to perform these tasks, we give the actors various _abilities_.

The `CallAnApi` ability gives actors the ability to interact with a REST web service using [Rest-Assured](https://rest-assured.io).
This includes both invoking REST end-points and querying the results.

```java
private String theRestApiBaseUrl;
private EnvironmentVariables environmentVariables; 
private Actor sam; 

@Before
public void configureBaseUrl() {
    theRestApiBaseUrl = environmentVariables.optionalProperty("restapi.baseurl") 
                                                   .orElse("https://reqres.in/api");

    sam = Actor.named("Sam the supervisor").whoCan(CallAnApi.at(theRestApiBaseUrl)); 
}
```

The `CallAnApi` ability allows the actor to perform the bundled Serenity REST interaction classes. This include:

* Get.resource()
* Post.to()
* Put.to()
* Delete.from()

The simplest of these is `Get`.

## GET Interactions

In a REST API, GET requests are used to query a REST resource.
Let's see how we can do this using Serenity Screenplay.

### Simple GET requests

In our demo application, the `/users` resource represents application users.
We can retrieve the details of a particular user by appending the user ID, like this: `/users/1`.
The structure of a user record is shown below:

```json
{
  "data": {
    "id": 1,
    "first_name": "George",
    "last_name": "Bluth",
    "avatar": "https://s3.amazonaws.com/uifaces/faces/twitter/calebogden/128.jpg"
  }
}
```

Suppose we need to write a scenario that retrieves a particular user, and checks some of the user's details, such as first_name and last_name.
Such a test might look like this:

```java
@Test
public void find_an_individual_user() {

    sam.attemptsTo(
            Get.resource("/users/1") 
    );

    sam.should(
            seeThatResponse( "User details should be correct", 
                    response -> response.statusCode(200) 
                                        .body("data.first_name", equalTo("George")) 
                                        .body("data.last_name", equalTo("Bluth")) 
            )
    );
}
```

As you can see, this code is fairly self-explanatory.
Like any other Screenplay test, we use the actor's `attemptsTo()` method to perform the action we want to test.
In this case, we use the `Get` interaction class, which comes bundled with `serenity-screenplay-rest`.

Next we check the response using the `seeThatResponse` method.
This method takes a Lambda expression and allows us to access the full RestAssured API.
In particular, we can use [jsonPath](http://static.javadoc.io/io.restassured/json-path/3.1.0/io/restassured/path/json/JsonPath.html) expressions to query the JSON structure we receive.


### Retrieving objects

Sometimes we need to fetch a value from a REST response, and keep it for use later on. RestAssured makes it relatively easy to convert a JSON structure to a Java object, which you can use later on in your tests.

For example, suppose we have a class like the one below, which corresponds to the user details returned by our endpoint:

```java
package examples.screenplay.rest.model;

public class User {
    private String id;
    private String first_name;
    private String last_name;


    public User(String first_name, String last_name) {
        this.first_name = first_name;
        this.last_name = last_name;
    }

    public String getId() {
        return id;
    }

    public String getFirstName() {
        return first_name;
    }

    public String getLastName() {
        return last_name;
    }
}
```

We could retrieve the user as an instance of this class by calling the `jsonPath().getObject()` method on the received response. This method will convert the JSON data on a given path to a corresponding Java structure:

```java
@Test
public void retrieve_an_element_from_the_json_structure() {

    sam.attemptsTo(
            Get.resource("/users/1")
    );

    User user = SerenityRest.lastResponse() 
                            .jsonPath()
                            .getObject("data", User.class); 

    assertThat(user.getFirstName()).isEqualTo("George");
    assertThat(user.getLastName()).isEqualTo("Bluth");

}
```

### Retrieving lists

Oftentimes we need to retrieve not a single item, but a list of items.
Retrieving a list is little different to retrieving a single item:

```java
sam.attemptsTo(
        Get.resource("/users") 
);

sam.should(
        seeThatResponse("all the expected users should be returned",
                response -> response.body("data.first_name", hasItems("George", "Janet", "Emma"))) 
);
```

The difference happens when we query the results.
In this case, we use a jsonPath expression (`data.first_name`) that will return _all_ of the first_name field values.
The Hamcrest matcher `hasItems` will compare the collection of first names that the jsonPath query returns, and check that it contains (at least) the names "George", "Janet" and "Emma".

But what if we want to capture the data we retrieve, rather than simply make an assertion about the contents?
We can do that using the `SerenityRest.lastResponse()` method, like this:

```java
List<String> userSurnames = SerenityRest.lastResponse().path("data.last_name"); 
assertThat(userSurnames).contains("Bluth", "Weaver", "Wong");
```

We can also retrieve lists of objects, just as we retrieved a single `User` instance in the previous section.
Simply use the `jsonPath.getList()` method as shown below:

```java
sam.attemptsTo(
        Get.resource("/users") 
);

sam.should(
        seeThatResponse("all the expected users should be returned",
                response -> response.body("data.first_name", hasItems("George", "Janet", "Emma"))) 
);
```

### Using Path Parameters

In the previous example, we hard-coded the path element in the request.
For a more flexible approach, we can supply the path parameter when we submit the query:

```java
sam.attemptsTo(
        Get.resource("/users/{id}").with( request -> request.pathParam("id", 1)) 
);
```

Here we are using the `Get.resource(...).with(...)` structure to pass the RestAssured `RequestSpecification` object into a lambda expression.
Once again, this gives us access to all the richness of the RestAssert library

### Using Query Parameters

Some REST APIs take query parameters as well as path parameters. Query parameters are commonly used to filter results or implement pagination. For example, we could get the second page of users from our `/users` API by using the `page` query parameter like this:

```
/users?page=2
```

In our test code, we use the `queryParam()` method to provide a value for the `page` parameter:

```java
sam.attemptsTo(
        Get.resource("/users").with( request -> request.queryParam("page", 2)) 
);

sam.should(
        seeThatResponse("All users on page 2 should be returned",
                response -> response.body("data.first_name",
                                     hasItems("Eve", "Charles", "Tracey"))) 
);
```

## Post queries

We can send POST requests to a REST end-point using the `Post` interaction class. Here is a simple example:

```java
sam.attemptsTo(
        Post.to("/users")
                .with(request -> request.header("Content-Type", "application/json") 
                                        .body("{\"firstName\": \"Sarah-Jane\",\"lastName\": \"Smith\"}") 
                )
);

sam.should(
        seeThatResponse("The user should have been successfully added",
                        response -> response.statusCode(201))
);
```

Alternatively, we can post an object, letting RestAssured convert the object fields into JSON for us:

```java
User newUser = new User("Sarah-Jane", "Smith");

sam.attemptsTo(
        Post.to("/users")
                .with(request -> request.header("Content-Type", "application/json")
                                        .body(newUser) 
                )
);
```

## Other types of queries

Other query types are similar to `GET` and `POST` queries.
For example, `PUT` requests are often used to update resources.
In the following example, we use a `PUT` request to update a user's details:

```java
sam.attemptsTo(
        Put.to("/users")
                .with(request -> request.header("Content-Type", "application/json")
                        .body("{\"firstName\": \"jack\",\"lastName\": \"smith\"}")
                )
);

sam.should(
        seeThatResponse(response -> response.statusCode(200)
                                            .body("updatedAt", not(isEmptyString())))
);
```

Or you can delete a user using the `DELETE` query as shown here:

```java
sam.attemptsTo(
        Delete.from("/users/1")
);

sam.should(
        seeThatResponse(response -> response.statusCode(204))
);
```

## Higher level tasks

The interactions we have seen so far are readable but still quite low level.
Screenplay allows us to build higher level tasks that represent the business intent behind these interactions.

For example, you could define a task that encapsulates listing all users like this:

```java
package examples.screenplay.rest.tasks;

import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.rest.interactions.Get;

public class UserTasks {
    public static Task listAllUsers() {
        return Task.where("{0} lists all users",  
                Get.resource("/users") 
        );
    }
}
```

We can then use a static import to refactor our first test as follows:

```java
sam.attemptsTo(
        listAllUsers()
);
```

For a bit more flexibility, we can also write a custom `Task` class. For example, we could write a `FindAUser` task to find a user by ID:

```java
package examples.screenplay.rest.tasks;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.rest.interactions.Get;
import net.serenitybdd.annotations.Step;

import static net.serenitybdd.screenplay.Tasks.instrumented;

public class FindAUser implements Task{
    private final int id;

    public FindAUser(int id) {
        this.id = id;
    }

    public static FindAUser withId(int id) {
        return instrumented(FindAUser.class, id);
    }

    @Override
    @Step("{0} fetches the user with id #id")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
                Get.resource("/users/{id}")
                   .with(request -> request.pathParam("id", id))
        );
    }
}
```

Using this class, we could refactor our original class to read like this:

```java
sam.attemptsTo(
        FindAUser.withId(1)
);
```

Using tasks to encapsulate REST interactions results in a clear, layered reporting structure, that first describes what the user is doing, and they how they go about it. The test report for the previous scenario is shown here:

![](img/find-a-user-by-id.png)


---

<!-- https://serenity-bdd.github.io/docs/screenplay/screenplay_ensure -->

# Making Screenplay Assertions with Serenity Ensure
## Introduction
Web tests are a common use case for Screenplay scenarios, where we try to model user behaviour and interactions with the system. In this section, we will learn how to interact with a web application using the Screenplay WebDriver integration.

We have seen how make assertions using the `should()` method with
targets or questions combined with Hamcrest matchers, like this:

```java
sam.attemptsTo(
  Enter.theValue("40").into(AGE_FIELD).thenHit(Keys.ENTER)
);

sam.should(
    seeThat(the(AGE_FIELD), hasValue("40"))
);
```

In the code shown here, the `the()` method is a static import from the
`WebElementQuestion` class, and the `hasValue()` is a static import from
the `WebElementStateMatchers` class. This is quite flexible, as you can
add custom matchers quite easily. However, it means you need to know
what matchers exist, and which ones can be used in different
circumstances.

## Introducing Serenity Ensure 
Serenity Screenplay also provides an alternative approach, which many developers find easier to use and faster to write. This approach uses the `Ensure` class. The `Ensure` class produces a `Performable`, so you can integrate them directly into the `attemptsTo()` method. It also has a very readable DSL and lets you use code completion to discover the assertions you can use for different values, making writing assertions easier and quicker. An example of code equivalent to the above can be seen here:

```java
sam.attemptsTo(
    Enter.theValue("40").into(AGE_FIELD).thenHit(Keys.ENTER),
    Ensure.that(AGE).text().isEqualTo("40")
);
```

In this section, you will learn how to use _Serenity Ensure_ to write fluent assertions for your own projects.

## Adding Serenity Ensure to your project

Serenity Ensure needs an extra dependency in your build script. For
Maven, add the `serenity-enusre` dependency to your `pom.xml` file:

```xml
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-ensure</artifactId>
    <version>${serenity.version}</version>
    <scope>test</scope>
</dependency>
```

And in Gradle, you need to add the following dependency:

```groovy
testCompile "net.serenity-bdd:serenity-screenplay-webdriver:${serenity.version}"
```

## Your first Ensure test

A very simple `Ensure` test can be seen here:

```java
Actor aster = Actor.named("Aster");

int age = 20;

aster.attemptsTo(
    Ensure.that(age).isEqualTo(20)              
);
```

Almost all `Ensure` assertions start with the `Ensure.that()` method. This method takes the value being tested as a parameter (in this
case an integer). Following this comes the actual assertion method.

## Assertions about numbers

You can use auto-complete in your IDE to see the range of assertions
available. For integers, longs and floating point numbers, the
assertions include:

| Assertion          | Example     |
| -----------        | ----------- |
| isEqualTo          | `Ensure.that(age).isEqualTo(18)`                |
| isNotEqualTo       | `Ensure.that(age).isNotEqualTo(65)`             |
| isGreaterThan      | `Ensure.that(age).isGreaterThan(18)`            |
| isGreaterThanOrEqualTo | `Ensure.that(age).isGreaterThanOrEqualTo(20)` |
| isLessThan         | `Ensure.that(age).isLessThan(100)`              |
| isBetween          | `Ensure.that(age).isBetween(18,25)`             |
| isStrictlyBetween  | `Ensure.that(age).isStrictlyBetween(20,25)`     |

For doubles and floats, you can also use the `isCloseTo()` assertion:

```java
float creditScore = 9.8F;

aster.attemptsTo(
    Ensure.that(creditScore).isCloseTo(9.81F, 0.01F)
);
```

## Assertions about Strings

Another common requirement is to make assertions about Strings. An
example is shown here:

```java
String name = "Bill";
aster.attemptsTo(
    Ensure.that(name).isEqualToIgnoringCase("BILL")
);
```

Other basic comparison assertions about Strings include the following:

| Assertion          | Example     |
| -----------        | ----------- |
| isEqualTo          | `Ensure.that(name).isEqualTo("Bill")`           |
| isNotEqualTo       | `Ensure.that(name).isNotEqualTo("Joe")`         |
| isGreaterThan      | `Ensure.that(name).isGreaterThan("Alfred")`     |
| isGreaterThanOrEqualTo | `Ensure.that(name).isGreaterThanOrEqualTo("Al")` |
| isLessThan         | `Ensure.that(name).isLessThan("Carrie")`        |
| isBetween          | `Ensure.that(name).isBetween("Bill","Carrie")`  |
| isStrictlyBetween  | `Ensure.that(name).isStrictlyBetween("Al",25)`  |

### String contents

The `Ensure` class also has a number of assertions related to string
contents. For example:

```java
String colors = "Red Green Blue";
aster.attemptsTo(
    Ensure.that(colors).contains("Green")
);
```

| Assertion          | Example     |
| -----------        | ----------- |
| containsIgnoringCase | `Ensure.that(colors).containsIgnoringCase("RED")` |
| containsOnlyDigits | `Ensure.that("123").containsOnlyDigits()`       |
| containsOnlyLettersOrDigits | `Ensure.that("abc123").containsOnlyLettersOrDigits()` |
| containsOnlyLetters | `Ensure.that("abc").containsOnlyLetters()`      |
| containsWhitespaces | `Ensure.that("Red Green").containsWhitespaces() |
| containsOnlyWhitespaces | `Ensure.that("   ").containsOnlyWhitespaces()`  |
| startsWith         | `Ensure.that(colors).startsWith("Red")`         |
| endsWith           | `Ensure.that(colors).endsWith("Blue")`          |
| matches            | `Ensure.that(colors).matches("Red (.*) Blue")`  |
| doesNotContain     | `Ensure.that(colors).doesNotContain("cyan")`    |
| isBlank()          | `Ensure.that("  ").isBlank()`                   |
| isNotBlank()       | `Ensure.that(colors).isNotBlank()`              |
| isEmpty()          | `Ensure.that("").isEmpty()`                     |
| isNotEmpty()       | `Ensure.that(colors).isNotEmpty()`              |
| isInLowerCase()    | `Ensure.that("red").isInLowerCase()`            |
| isInUpperCase()    | `Ensure.that("RED").isInUpperCase()`            |
| isSubstringOf      | `Ensure.that("Green").isSubstringOf(colors)`    |

### String Size 
There are also some assertions to check the length of the
string For example:

```java
String colors = "Red Green Blue";
aster.attemptsTo(
    Ensure.that(colors).hasSizeGreaterThan(3)
);
```

| Assertion          | Example     |
| -----------        | ----------- |
| hasSize            | `Ensure.that("red").hasSize(3)`                 |
| hasSizeGreaterThan | `Ensure.that("red").hasSizeGreaterThan(2)`      |
| hasSizeGreaterThanOrEqualTo | `Ensure.that("red").hasSizeGreaterThanOrEqualTo(3)` |
| hasSizeLessThan    | `Ensure.that("red").hasSizeLessThan(4)`         |
| hasSizeLessThanOrEqualTo | `Ensure.that("red").hasSizeLessThanOrEqualTo(3)` |
| hasSizeBetween     | `Ensure.that("red").hasSizeBetween(1,5)`        |
| hasLineCount       | `Ensure.that(colors).hasLineCount(1)`           |

## Assertions using Lambda expressions

Another useful trick is to use a Java 8 Lambda expression to do the
check. You can use the `Ensure.that(...).matches(...)` construct to pass
in a lambda predicate which will determine whether the `Ensure`
statement should pass or fail.

For example:

```java
String actualColor = "green";

aster.attemptsTo(
    Ensure.that(actualColor).matches("is an RGB color",        
                              color -> color.equals("red")     
                                       || color.equals("blue")
                                       || color.equals("green"))
);
```

### Assertions with Questions and predicates

You can also use a lambda predicate directly with a `Question` using the `Ensure.that(question, predicate)` form. This is useful when you need to check a value that comes from the system under test using custom logic:

```java
aster.attemptsTo(
    Ensure.that(TheColor.displayed(), color -> color.startsWith("R"))
);
```

You can provide a description for clearer reporting:

```java
aster.attemptsTo(
    Ensure.that("the color starts with R",
                TheColor.displayed(),
                color -> color.startsWith("R"))
);
```

This form fully supports [soft assertions](#soft-assertions), so all failures will be collected and reported together when soft assertions are enabled.

## Negative assertions

You can negate an `Ensure.that()` statement simply by including the
`not()` method. For example:

```java
String colors = "Red Green Blue";
aster.attemptsTo(
    Ensure.that(colors).not().contains("Cyan")
);
```

## Working with dates and times

The `Ensure` class provides a few special methods for dates and times.
For `LocalTime` variables, we can use `Ensure.that(...).isBefore()` and
`Ensure.that(...).isAfter()` to compare two times, as we can see here:

```java
LocalTime tenInTheMorning = LocalTime.of(10,0);
LocalTime twoInTheAfternoon = LocalTime.of(14,0);

aster.attemptsTo(
    Ensure.that(tenInTheMorning).isBefore(twoInTheAfternoon)
);
```

For `LocalDate` variables, we have `isBefore()` and `isAfter()`, as well
as a number of others, such as the `isDayOfWeek()` method illustrated
here:

```java
LocalDate firstOfJanuary = LocalDate.of(2000,1,1);

aster.attemptsTo(
    Ensure.that(firstOfJanuary).isDayOfWeek(DayOfWeek.SATURDAY)
);
```

Other date-related assertions include:

| Assertion          | Example     |
| -----------        | ----------- |
| isDayOfWeek        | `Ensure.that(firstOfJanuary).isDayOfWeek(SATURDAY)` |
| isDayOfMonth       | `Ensure.that(firstOfJanuary).isDayOfMonth(1)`   |
| isInTheMonthOf     | `Ensure.that(firstOfJanuary).isInTheMonthOf(JANUARY)` |
| isTheYear          | `Ensure.that(firstOfJanuary).isTheYear(2000)`   |

## Working with collections

The `Ensure` class gives you a range of methods to make assertions about
collections. This can be as simple as checking whether an element
appears in a collection: we can do this using the
`Ensure.that(...).isIn(...)` construct:

```java
List<String> colors = Arrays.asList("red", "green", "blue");

aster.attemptsTo(
    Ensure.that("red").isIn(colors)
);
```

Suppose we had the following lists:

```java
List<String> sameColors = Arrays.asList("red", "green", "blue");
List<String> differentColors = Arrays.asList("red", "green", "cyan");
List<String> allColors = Arrays.asList("red", "green", "blue","yellow","cyan");
List<String> lastColors = Arrays.asList("yellow","cyan");
List<String> redAndPink = Arrays.asList("red", "pink");
List<String> noColors = Arrays.asList();
```

Here are some examples of other assertion methods using these
collections:

## Assertions about list equality and size

The following assertions are useful if you need to check the size of a
collection, or whether it is equivalent to another collection.

| Assertion          | Example     |
| -----------        | ----------- |
| isEqualTo          | `Ensure.that(colors).isEqualTo(sameColors)`     |
| isEmpty            | `Ensure.that(noColors).isEmpty()`               |
| isNotEmpty         | `Ensure.that(colors).isNotEmpty()`              |
| hasSize            | `Ensure.that(colors).hasSize(3)`                |
| hasSizeGreaterThan | `Ensure.that(colors).hasSizeGreaterThan(2)`     |
| hasSizeLessThan    | `Ensure.that(colors).hasSizeLessThan(4)`        |
| hasSizeBetween     | `Ensure.that(colors).hasSizeBetween(2,4)`       |
| hasSameSizeAs      | `Ensure.that(colors).hasSameSize(differentColors)`  |

# Assertions about list contents

Often we need to check the contents of a collection. We can do this
using a range of *contains* assertions, as illustrated here:

```java
List<String> colors = Arrays.asList("red", "green", "blue");

aster.attemptsTo(
    Ensure.that(contains).contains("red")
);
```

Some of the other *contains* assertions are listed in the table below:

| Assertion          | Example     |
| -----------        | ----------- |
| contains           | `Ensure.that(colors).contains("red","blue")`    |
| containsAnyOf      | `Ensure.that(colors).anyOf("red","pink")`       |
| containsOnly       | `Ensure.that(colors).containsOnly("blue","green","red")`   |
| containsExactly    | `Ensure.that(colors).containsExactly("red","blue","green")`  |
| containsExactlyInAnyOrder | `Ensure.that(colors).containsExactly("red","blue","green")`|
| doesNotContain     | `Ensure.that(colors).doesNotContain("pink")`    |
| containsElementsFrom | `Ensure.that(allColors).containsElementsFrom(colors)`  |
| containsAnyElementsOf   | `Ensure.that(colors).containsAnyElementsOf(redAndPink)` |
| containsExactlyElementsOf | `Ensure.that(colors).containsExactlyElementsOf(sameColors)`  |
| isASubsetOf        | `Ensure.that(colors).isASubsetOf(allColors)`    |
| doesNotHaveDuplicates | `Ensure.that(colors).doesNotHaveDuplicates()`   |
| startsWith         | `Ensure.that(colors).startsWith("red", "green")` |
| startsWithElementsFrom | `Ensure.that(allColors).startsWithElementsFrom(colors)`  |
| endsWith           | `Ensure.that(colors).endsWith("green","blue")`  |
| endWithElementsFrom | `Ensure.that(allColors).endWithElementsFrom(lastColors)`  |

## Matching list elements with Java 8 Lambdas

Lambda expressions provide a powerful way of making arbitrary assertions
about the contents of a collection. We can use the
`Ensure.that(...).allMatch()`, `Ensure.that(...).anyMatch()` and
`Ensure.that(...).noneMatch()` to do this. For example, the following
code asserts that each element in a collection is 4 characters long:

```java
List<String> colors = ImmutableList.of("blue", "cyan", "pink");

aster.attemptsTo(
    Ensure.that(colors).allMatch("4 characters long",
                                 it -> it.length() == 4)
);
```

Note that when we use a Lambda expression, we need to include a
description of the expectation before providing the lambda expression
itself. This description will be used in the reports should the
assertion fail.

The *anyMatch* method checks that there exists at least one element in a
collection that matches a specified predicate. An example is shown here:

```java
@Test
public void shouldContainAtLeastOnePrimaryColor() {
    Actor aster = Actor.named("Aster");
    List<String> colors = ImmutableList.of("blue", "cyan", "pink");

    aster.attemptsTo(
        Ensure.that(colors).anyMatch("is a primary color",
                                     it ->  isAPrimaryColor(it))
    );
}

private boolean isAPrimaryColor(String color) {
    return  (color == "red")
            || (color == "green")
            || (color == "blue");
}
```

The *noneMatch* method checks that no elements exist in a collection
that match a certain condition.

```java
List<String> colors = ImmutableList.of("orange", "cyan", "pink");

aster.attemptsTo(
    Ensure.that(colors).noneMatch("is a primary color",
                                  it ->  isAPrimaryColor(it))
);
```

You can also check for specific numbers of elements, using `atLeast`,
`noMoreThan`, and `exactly`. For example:

```java
List<String> colors = ImmutableList.of("blue", "cyan", "red","pink");

aster.attemptsTo(
    Ensure.that(colors).atLeast(2, "is a primary color",
                                it ->  isAPrimaryColor(it))
);
```

## Using Named Expectations

If you have commonly used predicates in your test code, you can use the
`NamedExpectation` to make your code more concise. For example, here we
define a `NamedExpectation` that matches primary colors:

```java
private static final  NamedExpectation<String> IS_A_PRIMARY_COLOR
        = new NamedExpectation<>("is a primary color",
                               color -> (color.equals("red"))
                                        || (color.equals("green"))
                                        || (color.equals("blue")));
```

We could use this in the `Ensure.that()` method like this:

```java
aster.attemptsTo(
    Ensure.that(colors).anyMatch(IS_A_PRIMARY_COLOR)
);
```

## Working with web elements

When writing UI tests, we need to make assertions about the state of
elements on a web page. The `Ensure` class makes this an easy task.

We can make assertions about `Target` elements directly using the
`Ensure.that()` method.

```java
Target FIRST_NAME = Target.the("First name field").locatedBy("#firstName")

aster.attemptsTo(
    Ensure.that(FIRST_NAME).value().isEqualTo("Joe"),
);
```

A more flexible approach is to use the `ElementLocated` class to
identify an element. We can also locate elements using `By` locators or
CSS/XPath strings. The following code uses the `Ensure.that()` and
`ElementLocated.by()` methods to check whether the element located by
the CSS selector \"#firstName\" is displayed:

```java
aster.attemptsTo(
    Ensure.that(ElementLocated.by("#firstName")).isDisplayed(),
);
```

The `ElementLocated.by()` will work with `By` locators, XPath/CSS
strings or `Target` elements, which means that you can easily decouple
your locator strategy from your assertions.

### Simple web element assertions

The most simple assertions about web elements are boolean checks about
the state of the element. The `Ensure.that(...).is...` assertions let
you make assertions about whether an element is displayed or disabled.

| Assertion          | Example     |
| -----------        | ----------- |
| isDisplayed        | `Ensure.that(FIRST_NAME).isDisplayed()`         |
| isDisabled         | `Ensure.that(FIRST_NAME).isDisabled()`          |
| isEnabled          | `Ensure.that(FIRST_NAME).isEnabled()`           |


# Checking text content and field values

Checking field values and text content is the bread-and-butter of many
web tests. You can use `Ensure.that(...).value()` to read the value
attribute of a field, as shown here:

```java
aster.attemptsTo(
    Ensure.that(FIRST_NAME).value().startsWith("Joe"),
);
```

The `Ensure.that(...).text()` method lets you read the text of the
element:

```java
aster.attemptsTo(
    Ensure.that(SEARCH_RESULTS_SUMMARY)
          .text()
          .endsWith("results for 'Serenity'"),
);
```

You can also read the text contents of an element using
`Ensure.that(...).textContent()`. The text content is the value of the
`textContent` CSS attribute.

This value is available even when an element is not visible, making it
useful in cases where you need to read a full set of values, even those
not currently visible on the page.

The most important `Ensure.that(...)` methods for web elements include
the following:

| Assertion          | Example     |
| -----------        | ----------- |
| value              | `Ensure.that(FIRST_NAME).value().isEqualTo("Joe")`                                             |
| text               | `Ensure.that(DESCRIPTION).text().isNotEmpty()`  |
| textContent        | `Ensure.that(DESCRIPTION).textContent().isNotEmpty()`  |
| attribute          | `Ensure.that(FIRST_NAME).attribute("title").isEqualTo("First name")`|
| selectedValue      | `Ensure.that(COLORS).selectedValue().isEqualTo("green")`   |
| selectedVisibleText | `Ensure.that(COLORS).selectedVisibleText().isEqualTo("Green")`   |
| hasCssClass        | `Ensure.that(COLORS).hasCssClass("color-list")` |
| containsElements   | `Ensure.that(RESULT_LIST).containsElements(".result-details")`|


All of these methods allow you to make all of the String assertions we
saw earlier.

# Converting values to different types

Sometimes it is useful to be able to make assertions about non-String
types. For example:

```java
aster.attemptsTo(
    Ensure.that(ElementLocated.by("#itemCount"))
          .value()
          .asAnInteger()
          .isGreaterThanOrEqualTo(2)
);
```

The main conversion methods include:

| Assertion          | Example     |
| -----------        | ----------- |
| asAnInteger        | `Ensure.that(ITEM_COUNT).value().asAnInteger().isEqualTo(2)`   |
| asADouble          | `Ensure.that(TOTAL_COST).value().asADouble().isEqualTo(99.99d)` |
| asAFloat           | `Ensure.that(TOTAL_COST).value().asAFloat().isCloseTo(99.99f,0.01f)`|
| asABigDecimal      | `Ensure.that(TOTAL_COST).value().asABigDecimal().isEqualTo(new BigDecimal("99.99"))` |
| asADate            | `Ensure.that(CURRENT_DATE).value().asADate().isEqualTo(expectedLocalDate)`  |
| asATime            | `Ensure.that(CURRENT_TIME).value().asATime().isEqualTo(expectedLocalTime)` |
| asABoolean         | `Ensure.that(SOME_FLAG).value().asABoolean().is True()`   |


If a date or time value uses as non-standard format, we can pass a
format string to the `asADate()` or `asATime()` methods:

```java
aster.attemptsTo(
    Ensure.that(ElementLocated.by("#currentDate"))
          .value()
          .asADate("dd-MM-yyyy")
          .isBefore(dateLimit)
);
```

# Making assertions about collections of web elements

You can make assertions about multiple values, for example, all the
titles of a list of search results.

One way to do this is to use the `Ensure.thatTheSetOf()` method (or its
synonym, `Ensure.thatAmongst()`). This method takes a `Target` or a
locator, and lets you apply the

```java
aster.attemptsTo(
        Ensure.thatTheSetOf(ElementsLocated.by(".train-line"))
              .hasSizeGreaterThan(5)
);
```

We can also use static methods defined in `TheMatchingElement` to
perform commonly used checks on web elements, e.g.

```java
aster.attemptsTo(
        Ensure.thatTheSetOf(ElementsLocated.by(".train-line"))
              .allMatch(TheMatchingElement.containsText("Line"))
);
```

The main methods defined in the `TheMatchingElement` class include:

| Assertion          | Example     |
| -----------        | ----------- |
| isDisplayed        | `Ensure.thatTheSetOf(RESULTS).allMatch(isDisplayed())` |
| isNotDisplayed     | `Ensure.thatTheSetOf(RESULTS).noneMatch(isNotDisplayed())` |
| isDisabled         | `Ensure.thatTheSetOf(INPUT_FIELDS).atLeast(1, isDisabled())`    |
| isNotDisabled      | `Ensure.thatTheSetOf(INPUT_FIELDS).atLeast(1, isNotDisabled())`   |
| isEnabled          | `Ensure.thatTheSetOf(INPUT_FIELDS).atLeast(1, isEnabled())`      |
|                    |                                |
| isNotEnabled       | `Ensure.thatTheSetOf(INPUT_FIELDS).atLeast(1, isNotEnabled())`  |
| hasCssClass        | `Ensure.thatTheSetOf(RESULTS).noMoreThan(1, hasCssClass("selected"))` |
| hasValue           | `Ensure.thatTheSetOf(RESULTS).anyMatch(hasValue("red"))`   |
| containsText       | `Ensure.thatTheSetOf(RESULTS).anyMatch(containsText("Red"))`  |
| containsOnlyText   | `Ensure.thatTheSetOf(RESULTS).anyMatch(containsOnlyText("Red Car"))`    |
| containsElementsLo | `Ensure.thatTheSetOf(RESULTS).anyMatch(containsElementsLocatedBy(".model"))`  |


We can also make assertions about collections of matching values or the
text contents of matching elements. We can do this using the
`Ensure.that(...).values()`, `Ensure.that(...).textValues()` and
`Ensure.that(...).textContentValues()`. For example:

```java
aster.attemptsTo(
    Ensure.that(ElementLocated.by("#colors option"))
          .values()
          .contains("red","blue","green")
);
```

### Waiting for elements and defining timeouts

When working with asynchronous web applications, an element may not be
immediately ready when a test interacts with it. By default, Serenity
will wait for 5 seconds for an element to be present. Using the `Ensure`
class, we can fine-tune the amount of time we need to wait for an
element to become available. For example:

```java
Target SLOW_FIELD = Target.the("Slow field")
                          .locatedBy("#slow")

aster.attemptsTo(
        Ensure.that(SLOW_FIELD.waitingForNoMoreThan(Duration.ofSeconds(10)))
              .value()
              .isEqualTo("Marseille")
);
```

We can also build a delay into a `Target` field, if the same delay
should be applied everywhere the element is used:

```java
Target SLOW_FIELD = Target.the("Slow field")
                      .locatedBy("#slow")
                      .waitingForNoMoreThan(Duration.ofSeconds(5))
```

### Making assertions about the current page

There are also some `Ensure` methods that allow us to make basic
assertions about the page itself. For example, you can check the page
title like this:

```java
aster.attemptsTo(
        Ensure.thatTheCurrentPage().title().isEqualTo("Some Title")
);
```

Page-level assertions also include `currentUrl()`, `pageSource()` and
`windowHandle()`.

## Working with Screenplay Questions

So far we have been using the `Ensure.that*` methods with web page
locators and with field values. We can also use `Ensure.that*` methods
with arbitrary Screenplay questions. This can be used to write custom
`Question` classes or methods that query the state of the application
without using the UI, or which do more tailored queries of the UI.

For example,

```java
public Question<Integer> countOf(String todoItem) {
    return Question.about("todo status").answeredBy(
            actor -> // return some value related to a particular todo item
    );
}
```

We could then use the `Ensure.thatTheAnswerTo()` method to check the
result of this question:

```java
aster.attemptsTo(
        Ensure.thatTheAnswerTo("the count",
                               countOf("some-todo-item"))
              .isEqualTo(1)
);
```

We can also work with `Question` classes that return collections, using
the `Ensure.thatTheAnswersTo()` method. Suppose we had a Question that
returned a list of Strings:

```java
Question<Collection<String>> colors() {
    return Question.about("colors").answeredBy(
            actor -> // returns "red","green","blue"
    );
}
```

We could then use the `Ensure.thatTheAnswersTo()` method to make an
assertion about this question:

```java
aster.attemptsTo(
        Ensure.thatTheAnswersTo(colors()).contains("red")
);
```

## Soft Assertions

By default, an `Ensure` assertion that fails will immediately throw an error and stop the test. Sometimes you want to check multiple things and report all failures together rather than stopping at the first one. You can do this with **soft assertions**.

Enable soft assertions before your checks, and report them afterwards:

```java
Ensure.enableSoftAssertions();

aster.attemptsTo(
    Ensure.that(name).isEqualTo("Alice"),
    Ensure.that(age).isGreaterThan(18),
    Ensure.that(status).isEqualTo("ACTIVE")
);

Ensure.reportSoftAssertions(); // throws with all failures combined
```

When soft assertions are enabled, each failed `Ensure` statement records the error but allows execution to continue. When `reportSoftAssertions()` is called, all accumulated errors are thrown together as a single assertion error with a numbered list of failures.

In JUnit tests, you would typically enable soft assertions in a `@Before` method and report them in an `@After` method:

```java
@Before
public void enableSoftAsserts() {
    Ensure.enableSoftAssertions();
}

@After
public void reportSoftAsserts() {
    Ensure.reportSoftAssertions();
}
```

All `Ensure` assertion forms support soft assertions, including:
- Type-specific assertions: `Ensure.that(value).isEqualTo(...)`
- Lambda predicates: `Ensure.that(value).matches(...)`
- Question-based assertions: `Ensure.that(question).isEqualTo(...)`
- Question with predicate: `Ensure.that(question, predicate)`

## Reporting and hiding Ensure steps

Each `Ensure` performable will be reported in the Serenity report as a
separate step, including a short description of the expectation.
Sometimes, however, we want to use the `Ensure` statement as a way to
make sure the application is ready to continue the tests. In these
cases, we may prefer to leave the `Ensure` statement out of the reports.

We can do this using the `silently()` method:

```java
aster.attemptsTo(
    Ensure.that(ElementLocated.by("#firstName"))
          .silently()
          .isDisplayed()
);
```


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_intro -->

# Serenity BDD with Playwright

The `serenity-playwright` module provides seamless integration between Serenity BDD's powerful reporting capabilities and [Playwright](https://playwright.dev/)'s modern browser automation. This combination gives you the best of both worlds:

- **Playwright's Speed and Reliability** - Modern, auto-waiting browser automation
- **Serenity's Rich Reporting** - Step-by-step documentation with screenshots
- **Page Object Pattern Support** - Clean, maintainable test architecture
- **Cross-Browser Testing** - Chromium, Firefox, and WebKit support

## Why Playwright with Serenity?

Playwright is a modern browser automation library developed by Microsoft that offers several advantages:

- **Auto-waiting** - Playwright automatically waits for elements to be actionable before performing actions
- **Multiple Browser Contexts** - Run tests in isolated browser contexts for true parallelization
- **Network Interception** - Mock and modify network requests easily
- **Mobile Emulation** - Test responsive designs with device emulation
- **Modern Web Support** - First-class support for Shadow DOM, iframes, and web components

Combined with Serenity BDD, you get:

- **Automatic Screenshot Capture** - Screenshots at each step completion
- **Rich HTML Reports** - Interactive reports with step-by-step documentation
- **Living Documentation** - Tests that document how your application works
- **Page Source Capture** - HTML snapshots for debugging failed tests

## Two Approaches: Page Objects or Screenplay

Serenity Playwright supports two architectural approaches:

### Page Object Pattern (Traditional)

The classic three-layer pattern familiar to most test automation engineers:

```
Test Class (business scenarios)
    └── Step Library (@Step methods for Serenity reporting)
          └── Page Object (encapsulates locators and page interactions)
```

This separation ensures:
- **Tests** read like business requirements with no technical details
- **Step Libraries** provide Serenity's rich reporting with `@Step` annotations
- **Page Objects** encapsulate all locator strategies and page-specific logic

### Screenplay Pattern (Modern)

The Screenplay Pattern is a more modern, actor-centric approach:

```
Test Class (business scenarios)
    └── Actor performs Tasks and asks Questions
          └── Tasks use Targets to interact with the UI
```

With Screenplay:
- **Actors** represent users with abilities (like browsing the web)
- **Tasks** express high-level actions in business language
- **Questions** query the state of the application
- **Targets** define UI elements using Playwright selectors

Both approaches integrate seamlessly with Serenity's reporting.

## Quick Examples

### Page Object Approach

Here's what a Page Object-based Serenity Playwright test looks like, using Playwright's `@UsePlaywright` annotation to manage the browser lifecycle:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(ChromeHeadlessOptions.class)
class SearchTest {

    @Steps
    WikipediaSteps wikipedia;

    @Test
    void shouldSearchForATerm(Page page) {
        wikipedia.openWikipedia(page);
        wikipedia.searchFor(page, "Playwright");
        wikipedia.verifyTitleContains(page, "Playwright");
    }
}
```

The `@UsePlaywright` annotation handles the full browser lifecycle — creating and closing `Playwright`, `Browser`, `BrowserContext`, and `Page` instances automatically. The `SerenityPlaywrightExtension` registers the `Page` with Serenity for screenshot capture at each step.

### Screenplay Approach

Here's the same test using the Screenplay Pattern:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class SearchTest {

    Actor researcher;

    @BeforeEach
    void setup() {
        researcher = Actor.named("Researcher");
        researcher.can(BrowseTheWebWithPlaywright.usingTheDefaultConfiguration());
    }

    @Test
    void shouldSearchForATerm() {
        researcher.attemptsTo(
            Open.url("https://en.wikipedia.org"),
            SearchFor.term("Playwright"),
            Ensure.that(ThePageTitle.displayed()).contains("Playwright")
        );
    }
}
```

Both approaches read like specifications - no CSS selectors or low-level Playwright API calls, just clear business language.

## Getting Started

Ready to start? Head to the [Getting Started](playwright_getting_started) guide to set up your first Serenity Playwright project.

For a complete worked example:
- **Page Object approach**: Check out the [TodoMVC Tutorial](playwright_tutorial_todomvc) which walks through building a full test suite step by step
- **Screenplay approach**: See the [Screenplay with Playwright](playwright_screenplay) guide for the actor-centric pattern with comprehensive examples


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_getting_started -->

# Getting Started with Serenity Playwright

This guide will help you set up a new Serenity Playwright project from scratch.

## Prerequisites

Before you begin, ensure you have:

- **Java 17** or higher
- **Maven 3.8+** or Gradle
- An IDE (IntelliJ IDEA recommended)

## Project Setup

### Maven Configuration

Add the following dependencies to your `pom.xml`:

```xml
<properties>
    <serenity.version>5.3.11</serenity.version>
    <playwright.version>1.58.0</playwright.version>
    <junit.version>6.0.3</junit.version>
</properties>

<dependencies>
    <!-- Serenity Playwright Integration -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-playwright</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity JUnit 5 -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-junit5</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Playwright -->
    <dependency>
        <groupId>com.microsoft.playwright</groupId>
        <artifactId>playwright</artifactId>
        <version>${playwright.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- JUnit 5 -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- AssertJ (recommended for assertions) -->
    <dependency>
        <groupId>org.assertj</groupId>
        <artifactId>assertj-core</artifactId>
        <version>3.27.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

### Maven Plugins

Configure the Failsafe plugin and Serenity Maven plugin:

```xml
<build>
    <plugins>
        <!-- Run tests with Failsafe -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-failsafe-plugin</artifactId>
            <version>3.5.0</version>
            <configuration>
                <includes>
                    <include>**/*Test.java</include>
                </includes>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>integration-test</goal>
                        <goal>verify</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

        <!-- Generate Serenity reports -->
        <plugin>
            <groupId>net.serenity-bdd.maven.plugins</groupId>
            <artifactId>serenity-maven-plugin</artifactId>
            <version>${serenity.version}</version>
            <executions>
                <execution>
                    <id>serenity-reports</id>
                    <phase>post-integration-test</phase>
                    <goals>
                        <goal>aggregate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

## Installing Playwright Browsers

Playwright needs to download browser binaries on first use. Run this command:

```bash
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install"
```

Or let Playwright install them automatically on first test run.

## Your First Test

### Step 1: Create a Page Object

Create a Page Object to encapsulate page interactions:

```java
package com.example.pages;

import com.microsoft.playwright.Locator;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.options.AriaRole;

public class WikipediaHomePage {
    private final Page page;
    private static final String URL = "https://en.wikipedia.org";

    public WikipediaHomePage(Page page) {
        this.page = page;
    }

    // Locators are private - encapsulated
    private Locator searchBox() {
        return page.getByRole(AriaRole.SEARCHBOX,
            new Page.GetByRoleOptions().setName("Search Wikipedia"));
    }

    // Actions are public
    public void open() {
        page.navigate(URL);
    }

    public void searchFor(String term) {
        searchBox().fill(term);
        searchBox().press("Enter");
    }

    public String getTitle() {
        return page.title();
    }
}
```

### Step 2: Create a Step Library

Create a step library with `@Step` annotations for reporting:

```java
package com.example.steps;

import com.example.pages.WikipediaHomePage;
import com.microsoft.playwright.Page;
import net.serenitybdd.annotations.Step;

import static org.assertj.core.api.Assertions.assertThat;

public class WikipediaSteps {
    private WikipediaHomePage homePage;

    private void ensurePageObject(Page page) {
        if (homePage == null) {
            homePage = new WikipediaHomePage(page);
        }
    }

    @Step("Open Wikipedia")
    public void openWikipedia(Page page) {
        ensurePageObject(page);
        homePage.open();
    }

    @Step("Search for '{1}'")
    public void searchFor(Page page, String term) {
        ensurePageObject(page);
        homePage.searchFor(term);
    }

    @Step("Verify page title contains '{1}'")
    public void verifyTitleContains(Page page, String expected) {
        ensurePageObject(page);
        assertThat(homePage.getTitle())
            .containsIgnoringCase(expected);
    }
}
```

### Step 3: Write the Test

The recommended approach uses Playwright's `@UsePlaywright` annotation to manage the browser lifecycle automatically, combined with Serenity extensions for reporting:

```java
package com.example;

import com.example.steps.WikipediaSteps;
import com.microsoft.playwright.*;
import com.microsoft.playwright.junit.Options;
import com.microsoft.playwright.junit.OptionsFactory;
import com.microsoft.playwright.junit.UsePlaywright;
import net.serenitybdd.annotations.Steps;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.playwright.junit5.SerenityPlaywrightExtension;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.ExtendWith;

import java.util.Arrays;

@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(WikipediaSearchTest.ChromeOptions.class)
class WikipediaSearchTest {

    @Steps
    WikipediaSteps wikipedia;

    // OptionsFactory configures how Playwright launches the browser
    public static class ChromeOptions implements OptionsFactory {
        @Override
        public Options getOptions() {
            return new Options()
                .setHeadless(true)
                .setLaunchOptions(
                    new BrowserType.LaunchOptions()
                        .setArgs(Arrays.asList("--no-sandbox", "--disable-gpu"))
                );
        }
    }

    @Test
    @DisplayName("Should search Wikipedia successfully")
    void shouldSearchWikipedia(Page page) {
        wikipedia.openWikipedia(page);
        wikipedia.searchFor(page, "Playwright");
        wikipedia.verifyTitleContains(page, "Playwright");
    }
}
```

With this approach:
- **`@UsePlaywright`** creates and manages the Playwright instance, Browser, BrowserContext, and Page automatically
- **`SerenityPlaywrightExtension`** intercepts the Page and registers it with Serenity for screenshot capture
- **`SerenityJUnit5Extension`** handles `@Steps` injection and Serenity reporting
- The `Page` is injected as a method parameter — no manual setup or teardown needed

:::tip Using @SerenityPlaywright
You can use the `@SerenityPlaywright` meta-annotation as a shorthand for both Serenity extensions:

```java
@SerenityPlaywright
@UsePlaywright(ChromeOptions.class)
class WikipediaSearchTest {
    // ...
}
```

This is equivalent to adding both `@ExtendWith(SerenityJUnit5Extension.class)` and `@ExtendWith(SerenityPlaywrightExtension.class)`.
:::

### Alternative: Manual Lifecycle Management

If you need full control over the browser lifecycle, you can manage Playwright directly:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class WikipediaSearchTest {

    @Steps
    WikipediaSteps wikipedia;

    private static Playwright playwright;
    private static Browser browser;
    private Page page;

    @BeforeAll
    static void setupBrowser() {
        playwright = Playwright.create();
        browser = playwright.chromium().launch(
            new BrowserType.LaunchOptions().setHeadless(true)
        );
    }

    @AfterAll
    static void closeBrowser() {
        if (browser != null) browser.close();
        if (playwright != null) playwright.close();
    }

    @BeforeEach
    void setupPage() {
        page = browser.newPage();
        PlaywrightSerenity.registerPage(page);  // Enable screenshot capture
    }

    @AfterEach
    void closePage() {
        PlaywrightSerenity.unregisterPage(page);
        if (page != null) page.close();
    }

    @Test
    @DisplayName("Should search Wikipedia successfully")
    void shouldSearchWikipedia() {
        wikipedia.openWikipedia(page);
        wikipedia.searchFor(page, "Playwright");
        wikipedia.verifyTitleContains(page, "Playwright");
    }
}
```

## Running the Tests

Run your tests and generate reports:

```bash
mvn clean verify
```

## Viewing Reports

After the tests complete, open the Serenity report:

```bash
open target/site/serenity/index.html
```

You'll see a rich HTML report with:
- Test results summary
- Step-by-step execution details
- Screenshots captured at each step
- Page source snapshots for debugging

## Next Steps

- Follow the [TodoMVC Tutorial](playwright_tutorial_todomvc) for a complete worked example
- Learn about [Page Objects](playwright_page_objects) for maintainable test architecture
- Explore [Step Libraries](playwright_step_libraries) for better reporting
- Review [Configuration Options](playwright_configuration) for customization
- Check out [Best Practices](playwright_best_practices) for production-ready tests


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_page_objects -->

# Page Objects with Playwright

Page Objects are a design pattern that encapsulates the structure and behavior of a web page. With Playwright and Serenity, Page Objects provide a clean separation between your test logic and page implementation details.

## Why Page Objects?

Without Page Objects, tests become brittle and hard to maintain:

```java
// ❌ Bad: Locators scattered throughout tests
@Test
void searchTest() {
    page.locator("input[name='q']").fill("search term");
    page.locator("button.search-btn").click();
    assertThat(page.locator(".results-count").textContent()).contains("10");
}
```

With Page Objects, tests are clean and maintainable:

```java
// ✅ Good: Locators encapsulated in Page Object
@Test
void searchTest() {
    searchPage.searchFor("search term");
    assertThat(searchPage.getResultCount()).isEqualTo(10);
}
```

## Page Object Structure

A well-designed Page Object has three sections:

```java
public class ProductPage {
    private final Page page;

    public ProductPage(Page page) {
        this.page = page;
    }

    // ========== LOCATORS (private) ==========
    // Encapsulate how elements are found

    private Locator productTitle() {
        return page.locator("h1.product-title");
    }

    private Locator addToCartButton() {
        return page.getByRole(AriaRole.BUTTON,
            new Page.GetByRoleOptions().setName("Add to Cart"));
    }

    private Locator quantityInput() {
        return page.locator("#quantity");
    }

    // ========== ACTIONS (public) ==========
    // Represent user interactions

    public void addToCart() {
        addToCartButton().click();
    }

    public void setQuantity(int quantity) {
        quantityInput().fill(String.valueOf(quantity));
    }

    // ========== QUERIES (public) ==========
    // Return information about page state

    public String getProductTitle() {
        return productTitle().textContent();
    }

    public boolean isAddToCartEnabled() {
        return addToCartButton().isEnabled();
    }
}
```

### Key Principles

1. **Locators are private** - Only the Page Object knows how to find elements
2. **Actions are public** - Expose meaningful user interactions
3. **Queries are public** - Expose ways to check page state
4. **No assertions in Page Objects** - Let the caller decide what to verify

## Playwright Locator Strategies

Playwright offers several ways to locate elements. Use the most resilient strategy for each case:

### Role-Based Locators (Recommended)

These are the most resilient as they use accessibility semantics:

```java
// Find by ARIA role and accessible name
private Locator searchButton() {
    return page.getByRole(AriaRole.BUTTON,
        new Page.GetByRoleOptions().setName("Search"));
}

private Locator emailField() {
    return page.getByRole(AriaRole.TEXTBOX,
        new Page.GetByRoleOptions().setName("Email"));
}

private Locator mainNavigation() {
    return page.getByRole(AriaRole.NAVIGATION);
}
```

### Text-Based Locators

Good for finding elements by visible text:

```java
private Locator submitButton() {
    return page.getByText("Submit Order");
}

private Locator welcomeMessage() {
    return page.getByText("Welcome back", new Page.GetByTextOptions().setExact(false));
}
```

### Label-Based Locators

Find form fields by their associated labels:

```java
private Locator usernameField() {
    return page.getByLabel("Username");
}

private Locator rememberMeCheckbox() {
    return page.getByLabel("Remember me");
}
```

### Test ID Locators

Use data-testid attributes for elements without good semantic identifiers:

```java
private Locator shoppingCart() {
    return page.getByTestId("shopping-cart");
}

private Locator productCard(String productId) {
    return page.getByTestId("product-" + productId);
}
```

### CSS and XPath (Last Resort)

Use only when other strategies aren't available:

```java
private Locator legacyWidget() {
    return page.locator("div.legacy-widget > span.value");
}

private Locator complexElement() {
    return page.locator("xpath=//div[@class='container']//span[contains(text(),'Total')]");
}
```

## Page Object Patterns

### Navigation Methods

Include methods to navigate to the page:

```java
public class LoginPage {
    private final Page page;
    private static final String URL = "/login";

    public void open() {
        page.navigate(URL);
    }

    public void openWithRedirect(String returnUrl) {
        page.navigate(URL + "?redirect=" + returnUrl);
    }
}
```

### Page Transitions

Return new Page Objects when actions navigate to different pages:

```java
public class LoginPage {
    public DashboardPage loginAs(String username, String password) {
        usernameField().fill(username);
        passwordField().fill(password);
        loginButton().click();
        return new DashboardPage(page);
    }
}

// Usage:
DashboardPage dashboard = loginPage.loginAs("user", "pass");
assertThat(dashboard.getWelcomeMessage()).contains("Welcome");
```

### Component Objects

Reuse common UI components across pages:

```java
public class HeaderComponent {
    private final Page page;

    public HeaderComponent(Page page) {
        this.page = page;
    }

    private Locator searchBox() {
        return page.locator("header input[type='search']");
    }

    private Locator cartIcon() {
        return page.locator("header .cart-icon");
    }

    public void search(String term) {
        searchBox().fill(term);
        searchBox().press("Enter");
    }

    public int getCartItemCount() {
        String text = cartIcon().textContent();
        return Integer.parseInt(text);
    }
}

// Use in Page Objects:
public class ProductPage {
    private final Page page;
    private final HeaderComponent header;

    public ProductPage(Page page) {
        this.page = page;
        this.header = new HeaderComponent(page);
    }

    public HeaderComponent header() {
        return header;
    }
}
```

### Waiting Strategies

Playwright auto-waits, but sometimes you need explicit waits:

```java
public class SearchResultsPage {
    public void waitForResults() {
        // Wait for results to load
        resultsContainer().waitFor();
    }

    public void waitForMinimumResults(int count) {
        // Wait until we have enough results
        page.waitForCondition(() -> getResultCount() >= count);
    }

    public void waitForLoadingToComplete() {
        // Wait for loading spinner to disappear
        loadingSpinner().waitFor(new Locator.WaitForOptions()
            .setState(WaitForSelectorState.HIDDEN));
    }
}
```

## Integrating with Step Libraries

Page Objects work alongside Step Libraries. The Step Library handles Serenity reporting while the Page Object handles page interactions:

```java
public class CheckoutSteps {
    private CheckoutPage checkoutPage;
    private OrderConfirmationPage confirmationPage;

    @Step("Enter shipping address")
    public void enterShippingAddress(Address address) {
        checkoutPage.enterAddress(address);
    }

    @Step("Complete the order")
    public void completeOrder() {
        confirmationPage = checkoutPage.submitOrder();
    }

    @Step("Verify order confirmation number is displayed")
    public void verifyOrderConfirmationDisplayed() {
        assertThat(confirmationPage.getOrderNumber())
            .isNotEmpty();
    }
}
```

### Initializing Page Objects with @UsePlaywright

When using `@UsePlaywright`, Page Objects are typically initialized in a `@BeforeEach` method with the injected `Page`:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(ChromeHeadlessOptions.class)
class CheckoutTest {

    @Steps CheckoutSteps checkout;
    @Steps ProductSteps products;

    @BeforeEach
    void setUp(Page page) {
        checkout = new CheckoutSteps(page);
        products = new ProductSteps(page);
    }

    @Test
    void shouldCompleteCheckout(Page page) {
        products.selectProduct("Laptop Pro");
        checkout.enterShippingAddress(address);
        checkout.completeOrder();
        checkout.verifyOrderConfirmationDisplayed();
    }
}
```

## Best Practices

### 1. One Page Object Per Page/View

Don't try to represent multiple pages in one class:

```java
// ❌ Bad
public class AllPages { /* too many responsibilities */ }

// ✅ Good
public class LoginPage { /* login only */ }
public class DashboardPage { /* dashboard only */ }
```

### 2. Use Descriptive Method Names

Method names should describe the user intent:

```java
// ❌ Bad
public void click1() { ... }
public void fillForm() { ... }

// ✅ Good
public void addToWishlist() { ... }
public void submitContactForm(String name, String email, String message) { ... }
```

### 3. Avoid Exposing Locators

Never return raw Locator objects:

```java
// ❌ Bad - exposes implementation
public Locator getSubmitButton() {
    return page.locator("#submit");
}

// ✅ Good - exposes behavior
public void submitForm() {
    submitButton().click();
}

public boolean isSubmitEnabled() {
    return submitButton().isEnabled();
}
```

### 4. Handle Dynamic Content

Use parameterized locators for dynamic elements:

```java
public class ProductListPage {
    public void selectProduct(String productName) {
        page.getByRole(AriaRole.LINK,
            new Page.GetByRoleOptions().setName(productName)).click();
    }

    public String getPriceFor(String productName) {
        return page.locator(String.format(
            "[data-product='%s'] .price", productName)).textContent();
    }
}
```


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_screenplay -->

# Screenplay Pattern with Playwright

The Screenplay Pattern is a modern, actor-centric approach to writing automated tests. When combined with Playwright, it provides a powerful, expressive way to write browser automation tests that read like living documentation.

The `serenity-screenplay-playwright` module brings together:
- **Screenplay's expressiveness** - Actor-centric, task-based test design
- **Playwright's reliability** - Modern browser automation with auto-waiting
- **Serenity's rich reporting** - Step-by-step documentation with screenshots

## Why Screenplay with Playwright?

The Screenplay Pattern offers several advantages over traditional Page Object approaches:

| Page Objects | Screenplay |
|-------------|------------|
| Tests call page methods directly | Actors perform tasks and ask questions |
| Procedural code style | Declarative, behavior-focused style |
| Tests tied to UI structure | Tests express business intent |
| Harder to compose actions | Tasks easily compose into workflows |

With Playwright, you also get:
- **Auto-waiting** built into all interactions
- **Built-in assertions** with automatic retry
- **Network interception** for mocking APIs
- **Multiple browser support** (Chromium, Firefox, WebKit)

## Project Setup

### Maven Dependencies

Add these dependencies to your `pom.xml`:

```xml
<properties>
    <serenity.version>5.3.11</serenity.version>
    <playwright.version>1.58.0</playwright.version>
</properties>

<dependencies>
    <!-- Serenity Screenplay with Playwright -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay-playwright</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity Screenplay Core -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity Ensure (for fluent assertions) -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-ensure</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity JUnit 5 -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-junit5</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Playwright -->
    <dependency>
        <groupId>com.microsoft.playwright</groupId>
        <artifactId>playwright</artifactId>
        <version>${playwright.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- JUnit 5 -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>6.0.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

## Core Concepts

### Actors and Abilities

In Screenplay, tests are written from the perspective of **Actors** who have **Abilities**. For Playwright tests, actors need the `BrowseTheWebWithPlaywright` ability:

```java
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;

Actor toby = Actor.named("Toby");
toby.can(BrowseTheWebWithPlaywright.usingTheDefaultConfiguration());
```

The ability manages the Playwright browser lifecycle automatically:
- Creates the browser, context, and page on demand
- **Automatically cleans up** when the test completes (no explicit teardown needed)
- Subscribes to Serenity's test lifecycle events for seamless resource management

If you're already using `@UsePlaywright` to manage the browser lifecycle, you can wrap the injected `Page` instead of creating a new browser:

```java
// In a @UsePlaywright test, the Page is injected as a parameter
toby.can(BrowseTheWebWithPlaywright.withPage(page));
```

See [Using `@UsePlaywright` with Screenplay](#using-useplaywright-with-screenplay) for details.

### Tasks

**Tasks** represent high-level actions that an actor performs. They express _what_ the actor does in business terms:

```java
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.playwright.interactions.Open;
import net.serenitybdd.annotations.Step;

public class OpenTodoMvcApp implements Task {

    @Override
    @Step("{0} opens the TodoMVC application")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Open.url("https://todomvc.com/examples/react/dist/")
        );
    }

    public static OpenTodoMvcApp onTheHomePage() {
        return new OpenTodoMvcApp();
    }
}
```

Tasks can be composed from other tasks and interactions:

```java
public class AddATodoItem implements Task {
    private final String todoItem;

    public AddATodoItem(String todoItem) {
        this.todoItem = todoItem;
    }

    @Override
    @Step("{0} adds a todo item called '#todoItem'")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Enter.theValue(todoItem).into(TodoList.NEW_TODO_INPUT),
            Press.keys("Enter")
        );
    }

    public static AddATodoItem called(String todoItem) {
        return new AddATodoItem(todoItem);
    }
}
```

### Questions

**Questions** allow actors to query the state of the application:

```java
import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;

public class TheVisibleTodos {

    public static Question<Collection<String>> displayed() {
        return Question.about("the visible todos").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(".todo-list li label")
                .allTextContents()
        );
    }

    public static Question<Integer> count() {
        return Question.about("visible todo count").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(".todo-list li")
                .count()
        );
    }
}
```

### Targets

**Targets** define UI elements using Playwright selectors:

```java
import net.serenitybdd.screenplay.playwright.Target;

public class TodoList {

    public static final Target NEW_TODO_INPUT =
        Target.the("new todo input")
              .locatedBy("[placeholder='What needs to be done?']");

    public static final Target TODO_ITEMS =
        Target.the("todo items")
              .locatedBy(".todo-list li");

    public static Target todoItemCalled(String todoText) {
        return Target.the("todo item '" + todoText + "'")
                     .locatedBy(".todo-list li:has-text('" + todoText + "')");
    }

    public static Target checkboxFor(String todoText) {
        return Target.the("checkbox for '" + todoText + "'")
                     .locatedBy(".todo-list li:has-text('" + todoText + "') .toggle");
    }
}
```

Targets support:
- **Parameterized selectors**: `Target.the("item {0}").locatedBy("[data-id='{0}']").of("123")`
- **Nested targets**: `button.inside(form)`
- **Frame support**: `Target.the("editor").inFrame("#iframe").locatedBy("#content")`

## Writing Tests

### Basic Test Structure

Here's a complete example of a Screenplay test with Playwright:

```java
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.ensure.Ensure;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("When adding todos")
class WhenAddingTodosTest {

    Actor toby;

    @BeforeEach
    void setUp() {
        toby = Actor.named("Toby");
        toby.can(BrowseTheWebWithPlaywright.usingTheDefaultConfiguration());
    }

    // No @AfterEach needed - cleanup happens automatically!

    @Test
    @DisplayName("should add a single todo item")
    void shouldAddSingleTodoItem() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Buy milk"),
            Ensure.that(TheVisibleTodos.count()).isEqualTo(1),
            Ensure.that(TheTodoItem.called("Buy milk").exists()).isTrue()
        );
    }

    @Test
    @DisplayName("should add multiple todo items")
    void shouldAddMultipleTodoItems() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Buy milk"),
            AddATodoItem.called("Walk the dog"),
            AddATodoItem.called("Do laundry"),
            Ensure.that(TheVisibleTodos.displayed())
                .containsExactly("Buy milk", "Walk the dog", "Do laundry")
        );
    }
}
```

### Using Ensure for Assertions

The `Ensure` class provides fluent assertions that integrate with Screenplay's task-based model:

```java
toby.attemptsTo(
    // Numeric comparisons
    Ensure.that(TheRemainingCount.value()).isEqualTo(3),
    Ensure.that(TheVisibleTodos.count()).isGreaterThan(0),

    // Boolean checks
    Ensure.that(TheTodoItem.called("Buy milk").isCompleted()).isTrue(),
    Ensure.that(TheClearCompletedButton.isVisible()).isFalse(),

    // String comparisons
    Ensure.that(TheCurrentFilter.selected()).isEqualTo("All"),

    // Collection assertions
    Ensure.that(TheVisibleTodos.displayed())
        .containsExactly("Buy milk", "Walk the dog"),
    Ensure.that(TheVisibleTodos.displayed())
        .contains("Buy milk")
);
```

## Built-in Interactions

The `serenity-screenplay-playwright` module provides many built-in interactions:

### Navigation

```java
// Open a URL
actor.attemptsTo(Open.url("https://example.com"));

// Navigate back/forward
actor.attemptsTo(Navigate.back());
actor.attemptsTo(Navigate.forward());

// Refresh the page
actor.attemptsTo(Navigate.refresh());
```

### Clicking

```java
// Simple click
actor.attemptsTo(Click.on(TodoList.SUBMIT_BUTTON));

// Double-click
actor.attemptsTo(DoubleClick.on(TodoList.TODO_LABEL));

// Right-click
actor.attemptsTo(RightClick.on(TodoList.CONTEXT_MENU_TRIGGER));
```

### Form Interactions

```java
// Enter text
actor.attemptsTo(Enter.theValue("Hello").into(TodoList.INPUT_FIELD));

// Clear a field
actor.attemptsTo(Clear.field(TodoList.INPUT_FIELD));

// Press keys
actor.attemptsTo(Press.keys("Enter"));
actor.attemptsTo(Press.keys("Control+a"));

// Check/uncheck checkboxes
actor.attemptsTo(Check.checkbox(TodoList.AGREE_CHECKBOX));
actor.attemptsTo(Uncheck.checkbox(TodoList.AGREE_CHECKBOX));

// Select from dropdown
actor.attemptsTo(SelectFromOptions.byVisibleText("Option 1").from(TodoList.DROPDOWN));
actor.attemptsTo(SelectFromOptions.byValue("opt1").from(TodoList.DROPDOWN));
```

### Mouse Actions

```java
// Hover over an element
actor.attemptsTo(Hover.over(TodoList.DELETE_BUTTON));

// Drag and drop
actor.attemptsTo(Drag.from(SOURCE).to(TARGET));

// Scroll into view
actor.attemptsTo(ScrollIntoView.element(TodoList.FOOTER));
```

### Waiting

```java
// Wait for an element
actor.attemptsTo(WaitFor.the(TodoList.LOADING_SPINNER).toDisappear());
```

### JavaScript Execution

```java
// Execute JavaScript
actor.attemptsTo(
    ExecuteJavaScript.withScript("window.scrollTo(0, document.body.scrollHeight)")
);
```

### Dialog Handling

```java
// Accept alert
actor.attemptsTo(HandleDialog.byAccepting());

// Dismiss alert
actor.attemptsTo(HandleDialog.byDismissing());

// Enter text in prompt
actor.attemptsTo(HandleDialog.byEntering("my response"));
```

## Playwright-Specific Assertions

The `Ensure` class also provides Playwright-specific assertions with auto-retry:

```java
import net.serenitybdd.screenplay.playwright.assertions.Ensure;

actor.attemptsTo(
    // Element visibility
    Ensure.that(TodoList.MAIN_SECTION).isVisible(),
    Ensure.that(TodoList.LOADING_SPINNER).isHidden(),

    // Text content
    Ensure.that(TodoList.HEADER).hasText("todos"),
    Ensure.that(TodoList.HEADER).containsText("todo"),

    // Element count
    Ensure.that(TodoList.TODO_ITEMS).hasCount(3),

    // Attributes and classes
    Ensure.that(TodoList.TODO_ITEM).hasClass("completed"),
    Ensure.that(TodoList.INPUT).hasAttribute("placeholder", "What needs to be done?"),

    // Element state
    Ensure.that(TodoList.SUBMIT_BUTTON).isEnabled(),
    Ensure.that(TodoList.CHECKBOX).isChecked(),

    // Page URL and title
    Ensure.thatTheCurrentUrl().contains("/dashboard"),
    Ensure.thatThePageTitle().isEqualTo("My App")
);
```

:::caution Page URL and title assertions in 5.3.11 and earlier
In the Playwright modules up to 5.3.11, the objects returned by `Ensure.thatTheCurrentUrl()` and `Ensure.thatThePageTitle()` are not public classes, so calling `contains(...)` or `isEqualTo(...)` on them from your own code fails to compile. This is fixed in later releases. Until then, write a small task that reads the page directly:

```java
static Performable currentUrlContains(String text) {
    return Task.where("the current URL should contain '" + text + "'", actor -> {
        String url = BrowseTheWebWithPlaywright.as(actor).getCurrentPage().url();
        if (!url.contains(text)) {
            throw new AssertionError("Expected URL to contain '" + text + "' but was: " + url);
        }
    });
}
```

The page title works the same way with `getCurrentPage().title()`.
:::

## Advanced Features

### Using `@UsePlaywright` with Screenplay

If you're already using Playwright's `@UsePlaywright` annotation for lifecycle management, you can have Screenplay actors reuse the same browser session instead of creating a separate one. The `BrowseTheWebWithPlaywright.withPage(Page)` factory method wraps an externally-provided `Page`, so both `@UsePlaywright` and Screenplay share a single browser instance.

```java
import com.microsoft.playwright.Page;
import com.microsoft.playwright.junit.UsePlaywright;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.playwright.junit5.SerenityPlaywrightExtension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import net.serenitybdd.screenplay.playwright.interactions.Open;
import net.serenitybdd.screenplay.playwright.assertions.Ensure;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright
@DisplayName("TodoMVC with @UsePlaywright")
class WhenUsingPlaywrightWithScreenplayTest {

    Actor toby;

    @BeforeEach
    void setUp(Page page) {
        toby = Actor.named("Toby");
        toby.can(BrowseTheWebWithPlaywright.withPage(page));
    }

    @Test
    void should_add_a_todo(Page page) {
        toby.attemptsTo(
            Open.url("https://todomvc.com/examples/react/dist/"),
            Ensure.thatThePageTitle().containsIgnoringCase("TodoMVC")
        );

        // The Screenplay actor uses the same browser as @UsePlaywright
        assert BrowseTheWebWithPlaywright.as(toby).getCurrentPage() == page;
    }
}
```

Three annotations work together here:

| Annotation | Purpose |
|-----------|---------|
| `@ExtendWith(SerenityJUnit5Extension.class)` | Serenity BDD reporting and step injection |
| `@ExtendWith(SerenityPlaywrightExtension.class)` | Registers Playwright pages with Serenity for automatic screenshots |
| `@UsePlaywright` | Manages the full Playwright lifecycle (Playwright, Browser, BrowserContext, Page) |

:::tip Using @SerenityPlaywright
You can use `@SerenityPlaywright` as a shorthand for both Serenity extensions:
```java
@SerenityPlaywright
@UsePlaywright
class WhenUsingPlaywrightWithScreenplayTest {
    // ...
}
```
:::

Key points about `withPage()`:
- **Shared browser session** — the actor reuses the `Page`, `BrowserContext`, and `Browser` that `@UsePlaywright` created, avoiding a duplicate browser process.
- **No resource conflicts** — on teardown, Screenplay only unregisters its internal references. It does _not_ close the `Page`, `BrowserContext`, `Browser`, or `Playwright` instance, since `@UsePlaywright` owns their lifecycle.
- **Full Screenplay support** — all built-in interactions (`Open`, `Click`, `Enter`, `Ensure`, etc.), questions, cookie management, and screenshot capture work exactly as they do with `usingTheDefaultConfiguration()`.
- **Failure evidence** — screenshots and failure evidence (console errors, failed network requests) are still captured for Serenity reports.

:::tip When to use `withPage()`
Use `withPage(page)` when an external framework (like `@UsePlaywright`) already manages the Playwright lifecycle and you want Screenplay actors to work with that existing session. If you don't use `@UsePlaywright`, stick with `BrowseTheWebWithPlaywright.usingTheDefaultConfiguration()` — it handles everything automatically.
:::

### Direct Playwright API Access

For advanced scenarios, you can access the Playwright API directly:

```java
Page page = BrowseTheWebWithPlaywright.as(actor).getCurrentPage();

// Use Playwright's native API
page.locator(".my-element").click();

// Access browser context
BrowserContext context = page.context();

// Network interception
page.route("**/api/**", route -> {
    route.fulfill(new Route.FulfillOptions()
        .setBody("{\"mocked\": true}")
        .setContentType("application/json"));
});
```

### Custom Tasks

Create domain-specific tasks for your application:

```java
public class CompleteCheckout implements Task {

    private final PaymentDetails paymentDetails;

    public CompleteCheckout(PaymentDetails paymentDetails) {
        this.paymentDetails = paymentDetails;
    }

    @Override
    @Step("{0} completes checkout with #paymentDetails")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            EnterShippingAddress.forCurrentUser(),
            EnterPaymentDetails.using(paymentDetails),
            Click.on(CheckoutPage.PLACE_ORDER_BUTTON),
            WaitFor.the(CheckoutPage.CONFIRMATION_MESSAGE).toAppear()
        );
    }

    public static CompleteCheckout using(PaymentDetails details) {
        return new CompleteCheckout(details);
    }
}
```

### Custom Questions

Create reusable questions for your domain:

```java
public class TheOrderTotal {

    public static Question<BigDecimal> displayed() {
        return Question.about("the order total").answeredBy(actor -> {
            String totalText = BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(".order-total")
                .textContent();
            return new BigDecimal(totalText.replace("$", ""));
        });
    }
}

// Usage
actor.attemptsTo(
    Ensure.that(TheOrderTotal.displayed()).isGreaterThan(new BigDecimal("100.00"))
);
```

### Multiple Pages/Tabs

Handle multiple browser tabs:

```java
// Open a new page
BrowseTheWebWithPlaywright.as(actor).openNewPage();

// Switch between pages
BrowseTheWebWithPlaywright.as(actor).switchToPage(0);
BrowseTheWebWithPlaywright.as(actor).switchToPageWithTitle("Dashboard");

// Close current page
BrowseTheWebWithPlaywright.as(actor).closeCurrentPage();
```

### Cookie Management

Manage browser cookies:

```java
// Get all cookies
List<Cookie> cookies = BrowseTheWebWithPlaywright.as(actor).getCookies();

// Add a cookie
Cookie cookie = new Cookie("session", "abc123")
    .setDomain("example.com")
    .setPath("/");
BrowseTheWebWithPlaywright.as(actor).addCookie(cookie);

// Clear cookies
BrowseTheWebWithPlaywright.as(actor).clearCookies();
```

### Frame Handling

Interact with elements inside iframes:

```java
// Define a target inside a frame
Target EDITOR_CONTENT = Target.the("editor content")
    .inFrame("#editor-iframe")
    .locatedBy("#content");

// Interact with it normally
actor.attemptsTo(
    Enter.theValue("Hello World").into(EDITOR_CONTENT)
);
```

### Screenshots

Take screenshots explicitly:

```java
// The notifyScreenChange() method captures a screenshot
BrowseTheWebWithPlaywright.as(actor).notifyScreenChange();

// Or take a screenshot explicitly
ScreenshotAndHtmlSource screenshot = BrowseTheWebWithPlaywright.as(actor).takeScreenShot();
```

## Configuration

### Browser Options

Configure Playwright browser options via system properties or programmatically:

```properties
# serenity.properties
playwright.browsertype=chromium
playwright.headless=true
playwright.channel=chrome
playwright.baseurl=https://staging.example.com
playwright.slowmo=200
```

Or programmatically with explicit launch options:

```java
actor.can(
    BrowseTheWebWithPlaywright
        .withOptions(new BrowserType.LaunchOptions().setHeadless(false))
        .withBrowserType("firefox")
);
```

### Using an OptionsFactory

If you already have a Playwright `OptionsFactory` (e.g. the same one you use with `@UsePlaywright`), you can reuse it with Screenplay via `withOptions(OptionsFactory)`. This applies the full set of Options — browser type, launch options, context options, `testIdAttribute`, `wsEndpoint`, etc.:

```java
public class ChromeHeadlessOptions implements OptionsFactory {
    @Override
    public Options getOptions() {
        return new Options()
            .setHeadless(true)
            .setChannel("chrome")
            .setContextOptions(
                new Browser.NewContextOptions()
                    .setViewportSize(1920, 1080)
            )
            .setTestIdAttribute("data-test");
    }
}

// In your test setup
actor.can(
    BrowseTheWebWithPlaywright.withOptions(new ChromeHeadlessOptions())
);
```

Serenity properties (`playwright.headless`, `playwright.browsertype`, `playwright.channel`, `playwright.baseurl`, `playwright.slowmo`) are used as fallbacks when the corresponding option is not set in the factory.

### Screenshot Configuration

Control screenshot capture:

```properties
# serenity.conf
serenity {
    take.screenshots = FOR_EACH_ACTION  # or FOR_FAILURES, DISABLED
}
```

## Complete Example: TodoMVC Test Suite

Here's a comprehensive example showing all the concepts together:

### UI Targets

```java
public class TodoList {

    public static final Target NEW_TODO_INPUT =
        Target.the("new todo input")
              .locatedBy("[placeholder='What needs to be done?']");

    public static final Target TODO_ITEMS =
        Target.the("todo items")
              .locatedBy(".todo-list li");

    public static final Target TODO_COUNT =
        Target.the("todo count")
              .locatedBy(".todo-count");

    public static final Target CLEAR_COMPLETED_BUTTON =
        Target.the("clear completed button")
              .locatedBy(".clear-completed");

    public static final Target ALL_FILTER =
        Target.the("All filter")
              .locatedBy(".filters a:has-text('All')");

    public static final Target ACTIVE_FILTER =
        Target.the("Active filter")
              .locatedBy(".filters a:has-text('Active')");

    public static final Target COMPLETED_FILTER =
        Target.the("Completed filter")
              .locatedBy(".filters a:has-text('Completed')");

    public static Target todoItemCalled(String text) {
        return Target.the("todo '" + text + "'")
                     .locatedBy(".todo-list li:has-text('" + text + "')");
    }

    public static Target checkboxFor(String text) {
        return Target.the("checkbox for '" + text + "'")
                     .locatedBy(".todo-list li:has-text('" + text + "') .toggle");
    }

    public static Target deleteButtonFor(String text) {
        return Target.the("delete button for '" + text + "'")
                     .locatedBy(".todo-list li:has-text('" + text + "') .destroy");
    }
}
```

### Tasks

```java
// AddATodoItem.java
public class AddATodoItem implements Task {
    private final List<String> items;

    public AddATodoItem(List<String> items) {
        this.items = items;
    }

    @Override
    @Step("{0} adds todo items: #items")
    public <T extends Actor> void performAs(T actor) {
        for (String item : items) {
            actor.attemptsTo(
                Enter.theValue(item).into(TodoList.NEW_TODO_INPUT),
                Press.keys("Enter")
            );
        }
    }

    public static AddATodoItem called(String item) {
        return new AddATodoItem(List.of(item));
    }

    public static AddATodoItem withItems(String... items) {
        return new AddATodoItem(Arrays.asList(items));
    }
}

// Complete.java
public class Complete implements Task {
    private final String todoItem;

    public Complete(String todoItem) {
        this.todoItem = todoItem;
    }

    @Override
    @Step("{0} completes the todo item '#todoItem'")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Click.on(TodoList.checkboxFor(todoItem))
        );
    }

    public static Complete todoItem(String item) {
        return new Complete(item);
    }
}

// Delete.java
public class Delete implements Task {
    private final String todoItem;

    public Delete(String todoItem) {
        this.todoItem = todoItem;
    }

    @Override
    @Step("{0} deletes the todo item '#todoItem'")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Hover.over(TodoList.todoItemCalled(todoItem)),
            Click.on(TodoList.deleteButtonFor(todoItem))
        );
    }

    public static Delete theTodoItem(String item) {
        return new Delete(item);
    }
}

// FilterTodos.java
public class FilterTodos {

    public static Task toShowAll() {
        return Task.where("{0} filters to show all todos",
            Click.on(TodoList.ALL_FILTER)
        );
    }

    public static Task toShowActive() {
        return Task.where("{0} filters to show active todos",
            Click.on(TodoList.ACTIVE_FILTER)
        );
    }

    public static Task toShowCompleted() {
        return Task.where("{0} filters to show completed todos",
            Click.on(TodoList.COMPLETED_FILTER)
        );
    }
}
```

### Questions

```java
// TheVisibleTodos.java
public class TheVisibleTodos {

    public static Question<Collection<String>> displayed() {
        return Question.about("the visible todos").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(".todo-list li label")
                .allTextContents()
        );
    }

    public static Question<Integer> count() {
        return Question.about("visible todo count").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(".todo-list li")
                .count()
        );
    }
}

// TheRemainingCount.java
public class TheRemainingCount {

    public static Question<Integer> value() {
        return Question.about("the remaining count").answeredBy(actor -> {
            String text = BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(".todo-count")
                .textContent();
            Matcher matcher = Pattern.compile("(\\d+)").matcher(text);
            return matcher.find() ? Integer.parseInt(matcher.group(1)) : 0;
        });
    }
}
```

### Test Class

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("When managing todos")
class WhenManagingTodosTest {

    Actor toby;

    @BeforeEach
    void setUp() {
        toby = Actor.named("Toby");
        toby.can(BrowseTheWebWithPlaywright.usingTheDefaultConfiguration());
    }

    // No @AfterEach needed - BrowseTheWebWithPlaywright automatically
    // cleans up browser resources when the test finishes

    @Test
    @DisplayName("should add and complete todos")
    void shouldAddAndCompleteTodos() {
        toby.attemptsTo(
            Open.url("https://todomvc.com/examples/react/dist/"),
            AddATodoItem.withItems("Buy milk", "Walk the dog", "Do laundry"),

            Ensure.that(TheVisibleTodos.count()).isEqualTo(3),
            Ensure.that(TheRemainingCount.value()).isEqualTo(3),

            Complete.todoItem("Buy milk"),

            Ensure.that(TheRemainingCount.value()).isEqualTo(2),

            FilterTodos.toShowCompleted(),

            Ensure.that(TheVisibleTodos.displayed()).containsExactly("Buy milk"),

            FilterTodos.toShowActive(),

            Ensure.that(TheVisibleTodos.displayed())
                .containsExactly("Walk the dog", "Do laundry")
        );
    }

    @Test
    @DisplayName("should delete a todo item")
    void shouldDeleteTodoItem() {
        toby.attemptsTo(
            Open.url("https://todomvc.com/examples/react/dist/"),
            AddATodoItem.withItems("Item 1", "Item 2", "Item 3"),

            Delete.theTodoItem("Item 2"),

            Ensure.that(TheVisibleTodos.displayed())
                .containsExactly("Item 1", "Item 3")
        );
    }
}
```

## Best Practices

### 1. Keep Tasks Business-Focused

Tasks should express _what_ the user is trying to achieve, not _how_ they achieve it:

```java
// Good - expresses intent
actor.attemptsTo(
    AddItemToCart.called("Blue T-Shirt"),
    ProceedToCheckout.withStandardShipping()
);

// Avoid - too technical
actor.attemptsTo(
    Click.on(ProductPage.ADD_TO_CART_BUTTON),
    Click.on(Header.CART_ICON),
    Click.on(CartPage.CHECKOUT_BUTTON)
);
```

### 2. Use Meaningful Target Names

Target names appear in reports, so make them descriptive:

```java
// Good
Target SUBMIT_ORDER_BUTTON = Target.the("submit order button")
    .locatedBy("#checkout-submit");

// Avoid
Target BUTTON = Target.the("button").locatedBy("#checkout-submit");
```

### 3. Create Domain-Specific Questions

Questions should return meaningful domain objects:

```java
// Good
Question<Money> orderTotal = TheOrderTotal.displayed();
Question<List<CartItem>> cartItems = TheCartContents.items();

// Avoid
Question<String> total = Text.of(OrderPage.TOTAL);
```

### 4. Leverage Ensure for Readable Assertions

Use `Ensure.that()` for assertions that read naturally:

```java
actor.attemptsTo(
    Ensure.that(TheOrderStatus.displayed()).isEqualTo(OrderStatus.CONFIRMED),
    Ensure.that(TheDeliveryDate.shown()).isAfter(LocalDate.now())
);
```

## Next Steps

- Explore the [TodoMVC Tutorial](playwright_tutorial_todomvc) for a step-by-step walkthrough
- Learn about [Configuration Options](playwright_configuration) for customization
- Review [Best Practices](playwright_best_practices) for production-ready tests


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_step_libraries -->

# Step Libraries with Playwright

Step Libraries are the bridge between your tests and Page Objects. They provide Serenity's rich reporting capabilities through `@Step` annotations while keeping your tests clean and readable.

## The Three-Layer Architecture

```
Test Class
    │  Uses @Steps to inject step libraries
    │  Focuses on business scenarios
    ▼
Step Library
    │  @Step methods appear in reports
    │  Orchestrates Page Object actions
    ▼
Page Object
       Encapsulates locators
       Handles page interactions
```

## Creating Step Libraries

### Basic Structure

```java
public class ShoppingCartSteps {

    private ShoppingCartPage cartPage;

    // Initialize Page Object when needed
    private void ensurePageObject(Page page) {
        if (cartPage == null) {
            cartPage = new ShoppingCartPage(page);
        }
    }

    @Step("Add product '{1}' to cart")
    public void addProductToCart(Page page, String productName) {
        ensurePageObject(page);
        cartPage.addProduct(productName);
    }

    @Step("Verify cart contains {1} items")
    public void verifyCartItemCount(Page page, int expectedCount) {
        ensurePageObject(page);
        assertThat(cartPage.getItemCount())
            .as("Cart item count")
            .isEqualTo(expectedCount);
    }

    @Step("Proceed to checkout")
    public void proceedToCheckout(Page page) {
        ensurePageObject(page);
        cartPage.clickCheckout();
    }
}
```

### Using Step Libraries in Tests

Inject step libraries using the `@Steps` annotation. When combined with `@UsePlaywright`, the `Page` is injected as a method parameter — no manual lifecycle management needed:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(ChromeHeadlessOptions.class)
class ShoppingTest {

    @Steps
    ShoppingCartSteps cart;

    @Steps
    ProductSteps products;

    @Steps
    CheckoutSteps checkout;

    @Test
    void shouldCompleteAPurchase(Page page) {
        products.browseCategory(page, "Electronics");
        products.selectProduct(page, "Laptop Pro");
        cart.addProductToCart(page, "Laptop Pro");
        cart.verifyCartItemCount(page, 1);
        cart.proceedToCheckout(page);
        checkout.completeOrder(page);
    }
}
```

The `@UsePlaywright` annotation manages the Playwright, Browser, BrowserContext, and Page lifecycle automatically, while `SerenityPlaywrightExtension` registers the Page with Serenity for screenshot capture.

## The @Step Annotation

### Step Descriptions

Use parameter placeholders in step descriptions:

```java
@Step("Search for '{1}'")
public void searchFor(Page page, String term) { ... }

@Step("Add {1} units of '{2}' to cart")
public void addToCart(Page page, int quantity, String product) { ... }

@Step("Verify total is ${1}")
public void verifyTotal(Page page, BigDecimal expectedTotal) { ... }
```

Parameter indices are zero-based: `{0}` is the first parameter, `{1}` is the second, etc.

### Nested Steps

Steps can call other steps for hierarchical reporting:

```java
@Step("Complete checkout with credit card")
public void completeCheckoutWithCreditCard(Page page, CreditCard card) {
    enterBillingAddress(page, card.getBillingAddress());
    enterCardDetails(page, card);
    submitPayment(page);
}

@Step("Enter billing address")
public void enterBillingAddress(Page page, Address address) {
    checkoutPage.enterAddress(address);
}

@Step("Enter card details")
public void enterCardDetails(Page page, CreditCard card) {
    checkoutPage.enterCardNumber(card.getNumber());
    checkoutPage.enterExpiry(card.getExpiry());
    checkoutPage.enterCvv(card.getCvv());
}

@Step("Submit payment")
public void submitPayment(Page page) {
    checkoutPage.clickPay();
}
```

## Page-Aware Steps

For cleaner step signatures, use `PlaywrightSerenity.getCurrentPage()`:

```java
public class NavigationSteps {

    @Step("Navigate to {0}")
    public void navigateTo(String url) {
        Page page = PlaywrightSerenity.getCurrentPage();
        page.navigate(url);
    }

    @Step("Refresh the page")
    public void refreshPage() {
        PlaywrightSerenity.getCurrentPage().reload();
    }

    @Step("Go back")
    public void goBack() {
        PlaywrightSerenity.getCurrentPage().goBack();
    }
}
```

Usage in tests:

```java
@Test
void shouldNavigateBetweenPages() {
    // No need to pass page parameter
    navigation.navigateTo("https://example.com");
    navigation.refreshPage();
    navigation.goBack();
}
```

:::caution
When using `getCurrentPage()`, ensure the page has been registered with Serenity. This happens automatically when using `@UsePlaywright` with `SerenityPlaywrightExtension`, or you can register manually with `PlaywrightSerenity.registerPage(page)`.
:::

## Screenshot Capture

### Automatic Screenshots

Screenshots are captured automatically after each `@Step` method completes. This is handled by the `PlaywrightStepListener`.

### Manual Screenshots

Trigger additional screenshots at specific points:

```java
@Step("Capture current state")
public void captureCurrentState(Page page) {
    // Do some actions
    performComplexAction(page);

    // Capture a screenshot manually
    PlaywrightSerenity.takeScreenshot();

    // Continue with more actions
    performAnotherAction(page);
}
```

## Organizing Step Libraries

### By Feature Area

```
steps/
├── authentication/
│   ├── LoginSteps.java
│   └── RegistrationSteps.java
├── shopping/
│   ├── ProductSteps.java
│   ├── CartSteps.java
│   └── CheckoutSteps.java
└── account/
    ├── ProfileSteps.java
    └── OrderHistorySteps.java
```

### By User Journey

```
steps/
├── BuyerSteps.java      // All steps for a buyer persona
├── SellerSteps.java     // All steps for a seller persona
└── AdminSteps.java      // All steps for an admin
```

## Best Practices

### 1. Keep Steps Focused

Each step should represent one logical user action:

```java
// ❌ Bad: Too many things in one step
@Step("Login and add product to cart")
public void loginAndAddToCart(Page page, User user, String product) {
    // Too much happening here
}

// ✅ Good: Focused, single-purpose steps
@Step("Login as {1}")
public void login(Page page, User user) { ... }

@Step("Add '{1}' to cart")
public void addToCart(Page page, String product) { ... }
```

### 2. Use Business Language

Steps should read like natural language:

```java
// ❌ Bad: Technical language
@Step("Click submit button")
@Step("Fill input field with value")

// ✅ Good: Business language
@Step("Submit the order")
@Step("Enter shipping address")
```

### 3. Handle State Carefully

Be mindful of state between step calls:

```java
public class AccountSteps {
    private AccountPage accountPage;
    private User currentUser;  // Track state when needed

    @Step("Login as {1}")
    public void loginAs(Page page, User user) {
        // Store for later steps
        this.currentUser = user;
        loginPage.loginAs(user.getEmail(), user.getPassword());
    }

    @Step("Verify welcome message shows user's name")
    public void verifyWelcomeMessage(Page page) {
        assertThat(accountPage.getWelcomeMessage())
            .contains(currentUser.getFirstName());
    }
}
```

### 4. Make Assertions Clear

Include descriptive assertions in verification steps:

```java
@Step("Verify order total is ${1}")
public void verifyOrderTotal(Page page, BigDecimal expectedTotal) {
    BigDecimal actualTotal = checkoutPage.getOrderTotal();
    assertThat(actualTotal)
        .as("Order total")
        .isEqualByComparingTo(expectedTotal);
}

@Step("Verify error message is displayed")
public void verifyErrorMessageDisplayed(Page page, String expectedMessage) {
    assertThat(errorPage.getMessage())
        .as("Error message")
        .containsIgnoringCase(expectedMessage);
}
```

### 5. Compose Higher-Level Steps

Build complex workflows from simpler steps:

```java
@Step("Complete guest checkout")
public void completeGuestCheckout(Page page, Address address, CreditCard card) {
    enterShippingAddress(page, address);
    selectShippingMethod(page, "Standard");
    enterPaymentDetails(page, card);
    confirmOrder(page);
}
```

This creates a hierarchical report showing both the high-level step and its constituent parts.


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_configuration -->

# Configuration Options

Serenity Playwright can be configured through various means to customize browser behavior, screenshot capture, and reporting.

## Serenity Configuration

### serenity.conf

Create a `serenity.conf` file in `src/test/resources`:

```hocon
serenity {
  # Project name shown in reports
  project.name = "My Playwright Tests"

  # Screenshot capture strategy
  # Options: FOR_EACH_ACTION, BEFORE_AND_AFTER_EACH_STEP, FOR_FAILURES, DISABLED
  take.screenshots = FOR_EACH_ACTION

  # Output directory for reports
  outputDirectory = target/site/serenity

  # Report title
  report.title = "Test Results"
}

# Environment-specific settings
environments {
  default {
    base.url = "https://www.example.com"
  }
  staging {
    base.url = "https://staging.example.com"
  }
  production {
    base.url = "https://www.example.com"
  }
}
```

### Screenshot Strategies

| Strategy | Description |
|----------|-------------|
| `FOR_EACH_ACTION` | Screenshot after every step (default) |
| `BEFORE_AND_AFTER_EACH_STEP` | Screenshot before and after each step |
| `FOR_FAILURES` | Screenshot only when a step fails |
| `DISABLED` | No automatic screenshots |

### Using Environment Properties

Access environment-specific configuration in your tests:

```java
import net.serenitybdd.model.environment.EnvironmentSpecificConfiguration;
import net.thucydides.model.environment.SystemEnvironmentVariables;
import net.thucydides.model.util.EnvironmentVariables;

public class ConfiguredSteps {
    private final String baseUrl;

    public ConfiguredSteps() {
        EnvironmentVariables env = SystemEnvironmentVariables.currentEnvironmentVariables();
        // Resolves the value for the environment chosen with -Denvironment=..., falling back to "default"
        this.baseUrl = EnvironmentSpecificConfiguration.from(env)
                .getOptionalProperty("base.url")
                .orElse("https://www.example.com");
    }

    @Step("Open the application")
    public void openApplication(Page page) {
        page.navigate(baseUrl);
    }
}
```

Run with a specific environment:

```bash
mvn verify -Denvironment=staging
```

Reading `environments.default.base.url` directly would always return the `default` value, whatever environment you chose. See [where Serenity reads configuration from](/docs/reference/serenity-properties) for how values are resolved, including how a `-D` option overrides an environment value.

## Playwright Configuration with @UsePlaywright

The recommended way to configure Playwright is with the `@UsePlaywright` annotation and an `OptionsFactory` class. This approach lets Playwright manage the full browser lifecycle while you declaratively specify the configuration.

### OptionsFactory

Create an `OptionsFactory` implementation to configure browser options:

```java
public class ChromeHeadlessOptions implements OptionsFactory {
    @Override
    public Options getOptions() {
        return new Options()
            .setHeadless(true)
            .setLaunchOptions(
                new BrowserType.LaunchOptions()
                    .setArgs(Arrays.asList("--no-sandbox", "--disable-extensions", "--disable-gpu"))
            )
            .setTestIdAttribute("data-test");
    }
}
```

Then use it in your test class:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(ChromeHeadlessOptions.class)
class MyTest {
    // Page is injected automatically
    @Test
    void myTest(Page page) { ... }
}
```

### Available Options

The `Options` class provides a fluent API for all Playwright configuration:

| Option | Type | Description |
|--------|------|-------------|
| `headless` | `Boolean` | Whether to run the browser in headless mode |
| `browserName` | `String` | `"chromium"`, `"firefox"`, or `"webkit"` |
| `channel` | `String` | Browser channel (e.g. `"chrome"`, `"msedge"`) |
| `baseUrl` | `String` | Base URL for `page.navigate()` with relative paths |
| `deviceName` | `String` | Device emulation name (e.g. `"iPhone 13"`) |
| `testIdAttribute` | `String` | Custom test ID attribute (default: `"data-testid"`) |
| `ignoreHTTPSErrors` | `Boolean` | Whether to ignore HTTPS errors |
| `launchOptions` | `BrowserType.LaunchOptions` | Full launch options (args, timeout, slowMo, etc.) |
| `contextOptions` | `Browser.NewContextOptions` | Context options (viewport, locale, geolocation, etc.) |
| `trace` | `Options.Trace` | Tracing: `OFF`, `ON`, or `RETAIN_ON_FAILURE` |
| `outputDir` | `Path` | Directory for test artifacts |

### Common OptionsFactory Examples

#### Chrome with Custom Viewport

```java
public class ChromeDesktopOptions implements OptionsFactory {
    @Override
    public Options getOptions() {
        return new Options()
            .setHeadless(true)
            .setChannel("chrome")
            .setContextOptions(
                new Browser.NewContextOptions()
                    .setViewportSize(1920, 1080)
                    .setLocale("en-US")
                    .setTimezoneId("America/New_York")
            );
    }
}
```

#### Firefox

```java
public class FirefoxOptions implements OptionsFactory {
    @Override
    public Options getOptions() {
        return new Options()
            .setBrowserName("firefox")
            .setHeadless(true);
    }
}
```

#### Mobile Device Emulation

```java
public class MobileOptions implements OptionsFactory {
    @Override
    public Options getOptions() {
        return new Options()
            .setDeviceName("iPhone 13")
            .setHeadless(true);
    }
}
```

#### With Tracing Enabled

```java
public class TracingOptions implements OptionsFactory {
    @Override
    public Options getOptions() {
        return new Options()
            .setHeadless(true)
            .setTrace(Options.Trace.RETAIN_ON_FAILURE);
    }
}
```

### Lifecycle with @UsePlaywright

When using `@UsePlaywright`, Playwright manages the following lifecycle automatically:

| Resource | Scope | Details |
|----------|-------|---------|
| `Playwright` | Per thread | Created once, shared across tests in the same thread |
| `Browser` | Per test class | Created once per class, closed after all tests in the class |
| `BrowserContext` | Per test method | Fresh context for each test, providing isolation |
| `Page` | Per test method | Fresh page for each test |

The `Page`, `BrowserContext`, `Browser`, and `Playwright` objects can all be injected as method parameters in `@BeforeEach` and `@Test` methods.

## Manual Playwright Configuration

If you need full control over the browser lifecycle (e.g. for custom context management or multi-tab testing), you can manage Playwright directly.

### Browser Options

Configure browser launch options in your test setup:

```java
@BeforeAll
static void setupBrowser() {
    playwright = Playwright.create();

    BrowserType.LaunchOptions options = new BrowserType.LaunchOptions()
        .setHeadless(true)           // Run headless
        .setSlowMo(100)              // Slow down actions by 100ms
        .setTimeout(30000)           // Browser launch timeout
        .setDevtools(false);         // Don't open DevTools

    browser = playwright.chromium().launch(options);
}
```

### Headless vs Headed Mode

Control headless mode via system property:

```java
@BeforeAll
static void setupBrowser() {
    boolean headless = Boolean.parseBoolean(
        System.getProperty("playwright.headless", "true")
    );

    browser = playwright.chromium().launch(
        new BrowserType.LaunchOptions().setHeadless(headless)
    );
}
```

Run with visible browser:

```bash
mvn verify -Dplaywright.headless=false
```

### Serenity Playwright Properties

The following properties can be set in `serenity.properties`, `serenity.conf`, or as `-D` system property flags. They act as fallbacks — values set programmatically (via `Options`, `LaunchOptions`, or `NewContextOptions`) always take precedence.

| Property | Type | Description |
|----------|------|-------------|
| `playwright.browsertype` | `String` | Browser engine: `"chromium"`, `"firefox"`, or `"webkit"` |
| `playwright.headless` | `Boolean` | Whether to run the browser in headless mode |
| `playwright.channel` | `String` | Browser channel (e.g. `"chrome"`, `"msedge"`) |
| `playwright.baseurl` | `String` | Base URL for `page.navigate()` with relative paths |
| `playwright.slowmo` | `Double` | Slows down Playwright operations by the given milliseconds |
| `playwright.tracing` | `Boolean` | Enable Playwright tracing for the trace viewer |

Example using command-line flags:

```bash
mvn verify -Dplaywright.channel=chrome -Dplaywright.baseurl=https://staging.example.com -Dplaywright.slowmo=200
```

Or in `serenity.properties`:

```properties
playwright.browsertype=chromium
playwright.headless=false
playwright.channel=chrome
playwright.baseurl=https://staging.example.com
playwright.slowmo=200
```

### Browser Context Options

Configure browser context for each test:

```java
@BeforeEach
void setupPage() {
    Browser.NewContextOptions contextOptions = new Browser.NewContextOptions()
        .setViewportSize(1920, 1080)        // Browser window size
        .setLocale("en-US")                  // Locale
        .setTimezoneId("America/New_York")   // Timezone
        .setGeolocation(40.7128, -74.0060)   // Geolocation
        .setPermissions(Arrays.asList("geolocation")); // Permissions

    BrowserContext context = browser.newContext(contextOptions);
    page = context.newPage();
    PlaywrightSerenity.registerPage(page);
}
```

### Device Emulation

Test on mobile devices:

```java
@BeforeEach
void setupMobilePage() {
    // Use Playwright's device descriptors
    BrowserContext context = browser.newContext(
        new Browser.NewContextOptions()
            .setUserAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)...")
            .setViewportSize(375, 812)
            .setDeviceScaleFactor(3)
            .setIsMobile(true)
            .setHasTouch(true)
    );

    page = context.newPage();
    PlaywrightSerenity.registerPage(page);
}
```

### Network Configuration

#### Request Interception

```java
@BeforeEach
void setupWithMocking() {
    page = browser.newPage();

    // Mock API responses
    page.route("**/api/products", route -> {
        route.fulfill(new Route.FulfillOptions()
            .setStatus(200)
            .setContentType("application/json")
            .setBody("[{\"id\": 1, \"name\": \"Test Product\"}]")
        );
    });

    PlaywrightSerenity.registerPage(page);
}
```

#### Timeout Configuration

```java
// Global timeout for all actions
page.setDefaultTimeout(30000);  // 30 seconds

// Timeout for navigation
page.setDefaultNavigationTimeout(60000);  // 60 seconds

// Per-action timeout
page.locator("#slow-element").click(
    new Locator.ClickOptions().setTimeout(10000)
);
```

## Multi-Browser Testing

### Running on Different Browsers

```java
@ParameterizedTest
@ValueSource(strings = {"chromium", "firefox", "webkit"})
void shouldWorkOnAllBrowsers(String browserType) {
    Browser browser = switch (browserType) {
        case "chromium" -> playwright.chromium().launch();
        case "firefox" -> playwright.firefox().launch();
        case "webkit" -> playwright.webkit().launch();
        default -> throw new IllegalArgumentException("Unknown browser: " + browserType);
    };

    Page page = browser.newPage();
    PlaywrightSerenity.registerPage(page);

    // Run test...

    PlaywrightSerenity.unregisterPage(page);
    page.close();
    browser.close();
}
```

### Browser Selection via Property

```java
@BeforeAll
static void setupBrowser() {
    String browserName = System.getProperty("browser", "chromium");

    browser = switch (browserName.toLowerCase()) {
        case "firefox" -> playwright.firefox().launch(launchOptions);
        case "webkit" -> playwright.webkit().launch(launchOptions);
        default -> playwright.chromium().launch(launchOptions);
    };
}
```

Run with specific browser:

```bash
mvn verify -Dbrowser=firefox
```

## Parallel Execution

### JUnit 5 Parallel Configuration

Create `junit-platform.properties` in `src/test/resources`:

```properties
junit.jupiter.execution.parallel.enabled = true
junit.jupiter.execution.parallel.mode.default = concurrent
junit.jupiter.execution.parallel.mode.classes.default = concurrent
junit.jupiter.execution.parallel.config.strategy = fixed
junit.jupiter.execution.parallel.config.fixed.parallelism = 4
```

### Thread-Safe Browser Management

When using `@UsePlaywright`, parallel execution is handled automatically — Playwright stores all resources in `ThreadLocal` variables, so each thread gets its own isolated Playwright, Browser, BrowserContext, and Page:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(ChromeHeadlessOptions.class)
class ParallelTest {

    @Steps MySteps steps;

    @Test
    void testOne(Page page) {
        // Each test gets its own isolated BrowserContext and Page
        steps.doSomething(page);
    }

    @Test
    void testTwo(Page page) {
        // Safe to run in parallel - no shared state
        steps.doSomethingElse(page);
    }
}
```

If managing the lifecycle manually, use `ThreadLocal` for thread safety:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class ParallelTest {

    // Use ThreadLocal for thread safety
    private static final ThreadLocal<Playwright> playwrightHolder = new ThreadLocal<>();
    private static final ThreadLocal<Browser> browserHolder = new ThreadLocal<>();

    private Page page;

    @BeforeEach
    void setup() {
        if (playwrightHolder.get() == null) {
            playwrightHolder.set(Playwright.create());
            browserHolder.set(playwrightHolder.get().chromium().launch());
        }

        page = browserHolder.get().newPage();
        PlaywrightSerenity.registerPage(page);
    }

    @AfterEach
    void cleanup() {
        PlaywrightSerenity.unregisterPage(page);
        if (page != null) page.close();
    }

    @AfterAll
    static void teardown() {
        // Cleanup happens per thread
    }
}
```

## Logging Configuration

### Logback Configuration

Create `logback-test.xml` in `src/test/resources`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Serenity logging -->
    <logger name="net.serenitybdd" level="INFO"/>
    <logger name="net.thucydides" level="INFO"/>

    <!-- Playwright logging -->
    <logger name="com.microsoft.playwright" level="WARN"/>

    <!-- Your test logging -->
    <logger name="com.example.tests" level="DEBUG"/>

    <root level="INFO">
        <appender-ref ref="STDOUT"/>
    </root>
</configuration>
```

### Debug Logging

Enable verbose logging for troubleshooting:

```bash
mvn verify -Dlogback.configurationFile=logback-debug.xml
```

With `logback-debug.xml`:

```xml
<logger name="net.serenitybdd" level="DEBUG"/>
<logger name="com.microsoft.playwright" level="DEBUG"/>
```


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_best_practices -->

# Best Practices

This guide covers best practices for writing maintainable, reliable, and efficient Serenity Playwright tests.

## Test Architecture

### Follow the Three-Layer Pattern

Always structure your code in three layers:

```
Tests (business scenarios)
    └── Step Libraries (reporting with @Step)
          └── Page Objects (locators and actions)
```

This separation provides:
- **Maintainability** - Changes to UI only affect Page Objects
- **Readability** - Tests read like specifications
- **Reusability** - Steps and Page Objects can be shared

### Keep Tests Focused

Each test should verify one specific behavior:

```java
// ❌ Bad: Testing too many things
@Test
void testEverything() {
    login();
    searchForProduct();
    addToCart();
    checkout();
    verifyOrderConfirmation();
    logout();
    verifyLoggedOut();
}

// ✅ Good: Focused tests
@Test
void shouldAddProductToCart() {
    // Given
    products.searchFor(page, "laptop");

    // When
    cart.addFirstResultToCart(page);

    // Then
    cart.verifyCartContains(page, "laptop");
}

@Test
void shouldCompleteCheckout() {
    // Given
    cart.hasItemsInCart(page);

    // When
    checkout.completeOrder(page);

    // Then
    checkout.verifyOrderConfirmation(page);
}
```

## Browser Management

### Share Browser, Isolate Pages

Create the browser once per test class, but create a fresh page for each test:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class ProductTests {

    private static Playwright playwright;
    private static Browser browser;
    private Page page;

    @BeforeAll
    static void setupBrowser() {
        // Create browser once - expensive operation
        playwright = Playwright.create();
        browser = playwright.chromium().launch(
            new BrowserType.LaunchOptions().setHeadless(true)
        );
    }

    @AfterAll
    static void closeBrowser() {
        // Close browser after all tests
        if (browser != null) browser.close();
        if (playwright != null) playwright.close();
    }

    @BeforeEach
    void setupPage() {
        // Fresh page for each test - test isolation
        page = browser.newPage();
        PlaywrightSerenity.registerPage(page);
    }

    @AfterEach
    void closePage() {
        // Clean up after each test
        PlaywrightSerenity.unregisterPage(page);
        if (page != null) page.close();
    }
}
```

### Use Browser Contexts for Isolation

For complete test isolation, use browser contexts:

```java
@BeforeEach
void setup() {
    // Each context is completely isolated
    BrowserContext context = browser.newContext();
    page = context.newPage();
    PlaywrightSerenity.registerPage(page);
}

@AfterEach
void cleanup() {
    PlaywrightSerenity.unregisterPage(page);
    BrowserContext context = page.context();
    page.close();
    context.close();  // Closes all pages and clears cookies/storage
}
```

### Extract Common Setup into a Base Class

To reduce boilerplate across test classes, create a base class that handles Playwright lifecycle:

```java
public abstract class SerenityPlaywrightTest {

    protected Playwright playwright;
    protected Browser browser;
    protected Page page;

    @BeforeEach
    void setUpPlaywright() {
        playwright = Playwright.create();
        browser = playwright.chromium().launch(
                new BrowserType.LaunchOptions().setHeadless(true)
        );
        page = browser.newPage();
        PlaywrightSerenity.registerPage(page);
    }

    @AfterEach
    void tearDownPlaywright() {
        PlaywrightSerenity.unregisterPage(page);
        if (page != null) page.close();
        if (browser != null) browser.close();
        if (playwright != null) playwright.close();
    }
}
```

Test classes then extend this base and just wire up their step libraries:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("When adding todos")
class WhenAddingTodosTest extends SerenityPlaywrightTest {

    @Steps
    TodoSteps todo;

    @BeforeEach
    void setUp() {
        todo.setPage(page);  // Wire step library to the page
    }

    @Test
    void shouldAddTodoItem() {
        todo.openApplication();
        todo.addTodo("Buy milk");

        assertThat(todo.visibleTodoCount()).isEqualTo(1);
    }
}
```

This pattern:
- **Centralizes lifecycle management** - Changes to browser setup only need to happen in one place
- **Ensures proper cleanup** - The base class guarantees resources are released
- **Reduces test class boilerplate** - Each test class focuses on test logic
- **Makes the `page` accessible** - Protected field is available to all subclasses

## Locator Strategies

### Prefer Resilient Locators

Use locators in this order of preference:

1. **Role-based** - Most resilient, uses accessibility semantics
2. **Text-based** - Good for user-visible text
3. **Label-based** - Good for form fields
4. **Test IDs** - Good for elements without semantic meaning
5. **CSS/XPath** - Last resort

```java
// 1. Role-based (best)
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Submit"));

// 2. Text-based
page.getByText("Add to Cart");

// 3. Label-based
page.getByLabel("Email address");

// 4. Test ID
page.getByTestId("checkout-button");

// 5. CSS (avoid if possible)
page.locator("button.submit-btn");
```

### Avoid Brittle Locators

```java
// ❌ Brittle locators
page.locator("div:nth-child(3) > button");
page.locator(".btn-primary");
page.locator("//div[@class='container']/form/button[2]");

// ✅ Resilient locators
page.getByRole(AriaRole.BUTTON, opts -> opts.setName("Place Order"));
page.getByTestId("place-order-button");
```

### Use Chained Locators for Context

When the same element type appears multiple times:

```java
// Find the "Add" button within the first product card
page.locator("[data-testid='product-card']").first()
    .getByRole(AriaRole.BUTTON, new GetByRoleOptions().setName("Add"));

// Find the email field in the shipping section
page.locator("#shipping-section")
    .getByLabel("Email");
```

## Waiting Strategies

### Trust Playwright's Auto-Waiting

Playwright automatically waits for elements to be actionable. Don't add unnecessary waits:

```java
// ❌ Unnecessary - Playwright already waits
Thread.sleep(2000);
page.locator("#button").waitFor();
page.locator("#button").click();

// ✅ Just click - Playwright waits automatically
page.locator("#button").click();
```

### Use Explicit Waits When Needed

For specific conditions, use explicit waits:

```java
// Wait for navigation to complete
page.waitForURL("**/checkout");

// Wait for network requests to finish
page.waitForLoadState(LoadState.NETWORKIDLE);

// Wait for a specific condition
page.waitForCondition(() -> getItemCount() >= 5);

// Wait for element to be hidden
loadingSpinner().waitFor(new WaitForOptions()
    .setState(WaitForSelectorState.HIDDEN));
```

## Error Handling

### Provide Clear Assertions

Use descriptive assertion messages:

```java
@Step("Verify cart total is ${1}")
public void verifyCartTotal(Page page, BigDecimal expected) {
    BigDecimal actual = cartPage.getTotal();
    assertThat(actual)
        .as("Cart total should be $%s but was $%s", expected, actual)
        .isEqualByComparingTo(expected);
}
```

### Handle Expected Failures Gracefully

```java
@Step("Verify error message is shown")
public void verifyErrorMessage(Page page, String expectedMessage) {
    Locator errorLocator = page.locator(".error-message");

    assertThat(errorLocator.isVisible())
        .as("Error message should be visible")
        .isTrue();

    assertThat(errorLocator.textContent())
        .as("Error message content")
        .contains(expectedMessage);
}
```

## Performance Tips

### Use Headless Mode in CI

```java
boolean isCI = System.getenv("CI") != null;
browser = playwright.chromium().launch(
    new BrowserType.LaunchOptions().setHeadless(isCI)
);
```

### Minimize Browser Launches

Browser launches are expensive. Share browsers across tests:

```java
// One browser per test class
@BeforeAll
static void launchBrowser() { ... }

// NOT: One browser per test
@BeforeEach
void launchBrowser() { ... }  // ❌ Slow!
```

### Use Network Mocking for Speed

Mock slow API calls in tests:

```java
@BeforeEach
void setupMocks() {
    // Mock slow API endpoint
    page.route("**/api/recommendations", route -> {
        route.fulfill(new FulfillOptions()
            .setStatus(200)
            .setBody("[]"));
    });
}
```

## Organizing Tests

### Use Descriptive Test Names

```java
@Test
@DisplayName("Should display error when login fails with invalid password")
void shouldDisplayErrorWhenLoginFailsWithInvalidPassword() {
    // ...
}

@Test
@DisplayName("Should redirect to dashboard after successful login")
void shouldRedirectToDashboardAfterSuccessfulLogin() {
    // ...
}
```

### Group Related Tests

```java
@Nested
@DisplayName("When user is logged in")
class WhenLoggedIn {

    @BeforeEach
    void login() {
        auth.loginAs(page, testUser);
    }

    @Test
    void shouldDisplayWelcomeMessage() { ... }

    @Test
    void shouldShowOrderHistory() { ... }
}

@Nested
@DisplayName("When user is not logged in")
class WhenNotLoggedIn {

    @Test
    void shouldShowLoginPrompt() { ... }

    @Test
    void shouldRedirectToLoginPage() { ... }
}
```

## CI/CD Integration

### Configure for CI Environments

```java
@BeforeAll
static void setup() {
    playwright = Playwright.create();

    BrowserType.LaunchOptions options = new BrowserType.LaunchOptions()
        .setHeadless(true)
        .setArgs(Arrays.asList(
            "--no-sandbox",
            "--disable-dev-shm-usage"
        ));

    browser = playwright.chromium().launch(options);
}
```

### Generate Reports in CI

```yaml
# GitHub Actions example
- name: Run Tests
  run: mvn verify

- name: Upload Serenity Reports
  uses: actions/upload-artifact@v3
  if: always()
  with:
    name: serenity-reports
    path: target/site/serenity/
```

## Common Pitfalls

### Avoid Test Interdependencies

```java
// ❌ Bad: Tests depend on each other
@Test
@Order(1)
void createUser() {
    createdUserId = userService.create(user);
}

@Test
@Order(2)
void verifyUser() {
    userService.get(createdUserId);  // Fails if first test fails
}

// ✅ Good: Each test is independent
@Test
void shouldCreateAndVerifyUser() {
    String userId = userService.create(user);
    User retrieved = userService.get(userId);
    assertThat(retrieved).isEqualTo(user);
}
```

### Don't Ignore Flaky Tests

Address flaky tests immediately:

```java
// ❌ Don't do this
@Disabled("Flaky - investigate later")
@Test
void sometimesFailingTest() { ... }

// ✅ Fix the root cause
@Test
void fixedTest() {
    // Wait for specific condition instead of arbitrary sleep
    page.waitForLoadState(LoadState.NETWORKIDLE);
    // Now perform assertion
}
```

### Clean Up Test Data

```java
@AfterEach
void cleanup() {
    // Clean up any test data created
    if (createdOrderId != null) {
        orderService.delete(createdOrderId);
    }
}
```


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_tutorial_todomvc -->

# Tutorial: Building a Test Suite Step by Step

This tutorial walks through building a Serenity Playwright test suite for the [TodoMVC application](https://todomvc.com/examples/react/dist/). Rather than showing you the finished code upfront, we'll build it iteratively—starting with a single test and adding only what we need as we go.

This reflects how you'd actually develop tests in practice: write a test, build the minimum infrastructure to support it, then expand.

## What We're Testing

TodoMVC is a simple todo list application where users can add, complete, edit, and delete items. We'll start with the most basic functionality and build up from there.

## Project Setup

First, create a Maven project with these dependencies in `pom.xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>serenity-playwright-todomvc</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <serenity.version>5.3.11</serenity.version>
        <playwright.version>1.58.0</playwright.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-playwright</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-junit5</artifactId>
            <version>${serenity.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>com.microsoft.playwright</groupId>
            <artifactId>playwright</artifactId>
            <version>${playwright.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>6.0.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.assertj</groupId>
            <artifactId>assertj-core</artifactId>
            <version>3.27.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-failsafe-plugin</artifactId>
                <version>3.5.0</version>
                <configuration>
                    <includes>
                        <include>**/*Test.java</include>
                    </includes>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>integration-test</goal>
                            <goal>verify</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>net.serenity-bdd.maven.plugins</groupId>
                <artifactId>serenity-maven-plugin</artifactId>
                <version>${serenity.version}</version>
                <executions>
                    <execution>
                        <id>serenity-reports</id>
                        <phase>post-integration-test</phase>
                        <goals>
                            <goal>aggregate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>
```

## Iteration 1: Our First Test

Let's start with the simplest possible test: adding a single todo item.

### Write the Test First

Create `src/test/java/todomvc/tests/WhenAddingTodosTest.java`:

```java
package todomvc.tests;

import com.microsoft.playwright.Page;
import net.serenitybdd.annotations.Steps;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.playwright.junit5.SerenityPlaywrightExtension;
import com.microsoft.playwright.junit.UsePlaywright;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.ExtendWith;
import todomvc.steps.TodoSteps;

import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright
@DisplayName("When adding todos")
class WhenAddingTodosTest {

    @Steps
    TodoSteps todo;

    @BeforeEach
    void setUp(Page page) {
        todo.setPage(page);
    }

    @Test
    @DisplayName("should add a single todo item")
    void shouldAddSingleTodoItem() {
        todo.openApplication();
        todo.addTodo("Buy milk");

        assertThat(todo.visibleTodoCount()).isEqualTo(1);
    }
}
```

Three annotations work together here:

| Annotation | Purpose |
|-----------|---------|
| `@ExtendWith(SerenityJUnit5Extension.class)` | Integrates Serenity BDD reporting and step injection |
| `@ExtendWith(SerenityPlaywrightExtension.class)` | Registers Playwright pages with Serenity for automatic screenshots |
| `@UsePlaywright` | Manages the full Playwright lifecycle (Playwright, Browser, BrowserContext, Page) |

With `@UsePlaywright`, you don't need to create or close `Playwright`, `Browser`, or `Page` yourself. JUnit 5 injects a fresh `Page` into your `@BeforeEach` and `@Test` methods automatically, and cleans everything up when the test finishes.

This test won't compile yet—we need to create the step library and page object. But notice we've defined exactly what we need:
- `openApplication()` - navigate to the app
- `addTodo(String)` - add an item
- `visibleTodoCount()` - return how many items are visible

### Create the Step Library

Create `src/test/java/todomvc/steps/TodoSteps.java` with only the methods we need:

```java
package todomvc.steps;

import com.microsoft.playwright.Page;
import net.serenitybdd.annotations.Step;
import todomvc.pages.TodoMvcPage;

public class TodoSteps {

    private TodoMvcPage todoMvcPage;

    public void setPage(Page page) {
        this.todoMvcPage = new TodoMvcPage(page);
    }

    @Step("Open the TodoMVC application")
    public void openApplication() {
        todoMvcPage.open();
    }

    @Step("Add a todo: '{0}'")
    public void addTodo(String todoText) {
        todoMvcPage.addTodo(todoText);
    }

    @Step("Get the number of visible todos")
    public int visibleTodoCount() {
        return todoMvcPage.getVisibleTodoCount();
    }
}
```

:::tip Steps Return Data, Tests Assert
Notice that `visibleTodoCount()` returns an `int`. The test makes the assertion, not the step library. This keeps steps reusable—the same step can be used in different tests with different expected values.
:::

### Create the Page Object

Create `src/test/java/todomvc/pages/TodoMvcPage.java` with only what we need:

```java
package todomvc.pages;

import com.microsoft.playwright.Locator;
import com.microsoft.playwright.Page;

public class TodoMvcPage {

    private final Page page;
    private static final String URL = "https://todomvc.com/examples/react/dist/";

    public TodoMvcPage(Page page) {
        this.page = page;
    }

    // Locators - keep private
    private Locator newTodoInput() {
        return page.getByPlaceholder("What needs to be done?");
    }

    private Locator todoItems() {
        return page.locator(".todo-list li");
    }

    // Actions
    public void open() {
        page.navigate(URL);
        page.waitForLoadState();
    }

    public void addTodo(String todoText) {
        newTodoInput().fill(todoText);
        newTodoInput().press("Enter");
    }

    // Queries
    public int getVisibleTodoCount() {
        return todoItems().count();
    }
}
```

### Run It

```bash
mvn clean verify
```

The test should pass. We now have a minimal working test suite.

## Iteration 2: Adding More Assertions

Let's enhance our test to verify the todo text appears correctly.

### Update the Test

```java
@Test
@DisplayName("should add a single todo item")
void shouldAddSingleTodoItem() {
    todo.openApplication();
    todo.addTodo("Buy milk");

    assertThat(todo.visibleTodoCount()).isEqualTo(1);
    assertThat(todo.todoExists("Buy milk")).isTrue();  // New assertion
}
```

### Add to Step Library

```java
@Step("Check if todo '{0}' exists")
public boolean todoExists(String todoText) {
    return todoMvcPage.hasTodo(todoText);
}
```

### Add to Page Object

```java
private Locator todoItemByText(String text) {
    return page.locator(".todo-list li").filter(
        new Locator.FilterOptions().setHasText(text)
    );
}

public boolean hasTodo(String todoText) {
    return todoItemByText(todoText).count() > 0;
}
```

We added a new locator method `todoItemByText()` because we needed to find a specific item. This locator will be reused for other operations later.

## Iteration 3: Testing Multiple Todos

### Add a New Test

```java
@Test
@DisplayName("should add multiple todo items")
void shouldAddMultipleTodoItems() {
    todo.openApplication();
    todo.addTodos("Buy milk", "Walk the dog", "Do laundry");

    assertThat(todo.visibleTodoCount()).isEqualTo(3);
    assertThat(todo.visibleTodos())
        .containsExactly("Buy milk", "Walk the dog", "Do laundry");
}
```

### Add to Step Library

```java
@Step("Add todos: {0}")
public void addTodos(String... todoTexts) {
    todoMvcPage.addTodos(todoTexts);
}

@Step("Get the visible todo items")
public List<String> visibleTodos() {
    return todoMvcPage.getVisibleTodoTexts();
}
```

### Add to Page Object

```java
public void addTodos(String... todoTexts) {
    for (String text : todoTexts) {
        addTodo(text);
    }
}

public List<String> getVisibleTodoTexts() {
    return todoItems().locator("label").allTextContents();
}
```

## Iteration 4: Extract a Base Test Class

We're about to create more test classes, and they'll all need the same annotations. Let's extract them into a base class. While we're at it, we'll configure the browser to run in headless mode using an `OptionsFactory`.

### Create the Base Class

Create `src/test/java/todomvc/tests/SerenityPlaywrightTest.java`:

```java
package todomvc.tests;

import com.microsoft.playwright.BrowserType;
import com.microsoft.playwright.junit.Options;
import com.microsoft.playwright.junit.OptionsFactory;
import com.microsoft.playwright.junit.UsePlaywright;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.playwright.junit5.SerenityPlaywrightExtension;
import org.junit.jupiter.api.extension.ExtendWith;

import java.util.Arrays;

@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(SerenityPlaywrightTest.ChromeHeadlessOptions.class)
public abstract class SerenityPlaywrightTest {

    public static class ChromeHeadlessOptions implements OptionsFactory {
        @Override
        public Options getOptions() {
            return new Options()
                    .setHeadless(true)
                    .setLaunchOptions(
                            new BrowserType.LaunchOptions()
                                    .setArgs(Arrays.asList(
                                        "--no-sandbox",
                                        "--disable-extensions",
                                        "--disable-gpu"))
                    );
        }
    }
}
```

The `@UsePlaywright` annotation accepts an `OptionsFactory` class to configure browser options. By passing `ChromeHeadlessOptions.class`, every test that extends this base class will run in headless Chromium with the specified launch arguments. Since `@UsePlaywright` is `@Inherited`, all three annotations are inherited by subclasses.

### Simplify the Test Class

```java
@DisplayName("When adding todos")
class WhenAddingTodosTest extends SerenityPlaywrightTest {

    @Steps
    TodoSteps todo;

    @BeforeEach
    void setUp(Page page) {
        todo.setPage(page);
    }

    @Test
    @DisplayName("should add a single todo item")
    void shouldAddSingleTodoItem() {
        todo.openApplication();
        todo.addTodo("Buy milk");

        assertThat(todo.visibleTodoCount()).isEqualTo(1);
        assertThat(todo.todoExists("Buy milk")).isTrue();
    }

    // ... other tests
}
```

Much cleaner! The base class handles all annotations and browser configuration. Each test class focuses purely on test logic—no lifecycle boilerplate, no manual cleanup.

## Iteration 5: Testing Completion

Now let's create a new test class for completing todos.

### Create the Test Class

Create `src/test/java/todomvc/tests/WhenCompletingTodosTest.java`:

```java
@DisplayName("When completing todos")
class WhenCompletingTodosTest extends SerenityPlaywrightTest {

    @Steps
    TodoSteps todo;

    @BeforeEach
    void setUp(Page page) {
        todo.setPage(page);
    }

    @Test
    @DisplayName("should mark a todo as completed")
    void shouldMarkTodoAsCompleted() {
        todo.openApplication();
        todo.addTodo("Buy milk");
        todo.completeTodo("Buy milk");

        assertThat(todo.todoIsCompleted("Buy milk")).isTrue();
    }
}
```

### Add to Step Library

```java
@Step("Complete the todo: '{0}'")
public void completeTodo(String todoText) {
    todoMvcPage.completeTodo(todoText);
}

@Step("Check if todo '{0}' is completed")
public boolean todoIsCompleted(String todoText) {
    return todoMvcPage.isCompleted(todoText);
}
```

### Add to Page Object

```java
private Locator todoCheckbox(String text) {
    return todoItemByText(text).locator(".toggle");
}

public void completeTodo(String todoText) {
    todoCheckbox(todoText).click();
}

public boolean isCompleted(String todoText) {
    String classAttr = todoItemByText(todoText).getAttribute("class");
    return classAttr != null && classAttr.contains("completed");
}
```

Notice how we reuse `todoItemByText()` that we created earlier. The page object grows organically as we need more functionality.

## Iteration 6: Testing the Remaining Count

### Add Another Test

```java
@Test
@DisplayName("should decrease remaining count when completing")
void shouldDecreaseRemainingCountWhenCompleting() {
    todo.openApplication();
    todo.addTodos("Task 1", "Task 2", "Task 3");

    assertThat(todo.remainingCount()).isEqualTo(3);

    todo.completeTodo("Task 2");

    assertThat(todo.remainingCount()).isEqualTo(2);
}
```

### Add to Step Library

```java
@Step("Get the remaining items count")
public int remainingCount() {
    return todoMvcPage.getRemainingCount();
}
```

### Add to Page Object

```java
private Locator todoCount() {
    return page.locator(".todo-count");
}

public int getRemainingCount() {
    String text = todoCount().textContent();
    return Integer.parseInt(text.replaceAll("[^0-9]", ""));
}
```

## The Pattern

By now, you can see the pattern:

1. **Write a test** that describes what you want to verify
2. **Add step library methods** that the test needs
3. **Add page object methods** that the steps need
4. **Add locators** only when a method requires them

This approach ensures:
- You never write code you don't need
- Each addition is driven by a concrete requirement
- The page object grows naturally to match your test coverage

## Continue Building

Following this pattern, you can add tests for:
- Editing todos (double-click, type, press Enter)
- Deleting todos (hover, click destroy button)
- Filtering (All, Active, Completed)
- Toggle all
- Clear completed

Each new test may require new step methods, page object methods, and locators—add them as needed.

## Final Project Structure

After several iterations, your project will look like:

```
src/test/java/todomvc/
├── pages/
│   └── TodoMvcPage.java            # Grows with each iteration
├── steps/
│   └── TodoSteps.java              # Grows with each iteration
└── tests/
    ├── SerenityPlaywrightTest.java  # Base class with @UsePlaywright
    ├── WhenAddingTodosTest.java
    ├── WhenCompletingTodosTest.java
    ├── WhenEditingTodosTest.java    # Added later
    ├── WhenDeletingTodosTest.java   # Added later
    └── WhenFilteringTodosTest.java  # Added later
```

## Key Takeaways

| Principle | Why It Matters |
|-----------|----------------|
| **Start with a test** | Tests drive what code you write |
| **Add only what you need** | No speculative code that may never be used |
| **Extract when patterns emerge** | Base class came after we saw duplication |
| **Let `@UsePlaywright` manage the lifecycle** | No manual Playwright/Browser/Page setup or teardown |
| **Steps return data** | Tests make assertions, keeping steps reusable |
| **Private locators** | Encapsulation makes changes easier |

## Complete Source Code

The complete source code for this tutorial is available at:
[github.com/serenity-bdd/serenity-playwright-todomvc-demo](https://github.com/serenity-bdd/serenity-playwright-todomvc-demo)


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_screenplay_tutorial -->

# Tutorial: Building a Screenplay Test Suite

This tutorial walks through building a Serenity Playwright test suite using the Screenplay Pattern for the [TodoMVC application](https://todomvc.com/examples/react/dist/). We'll build it iteratively, starting with the fundamentals and progressively adding more sophisticated patterns.

## What We're Building

By the end of this tutorial, you'll have a complete test suite with:
- **Targets** for all UI elements
- **Tasks** for user actions (add, complete, delete, filter todos)
- **Questions** to query application state
- **Tests** using `Ensure.that()` assertions

## Project Setup

Create a Maven project with these dependencies:

```xml
<properties>
    <serenity.version>5.3.11</serenity.version>
    <playwright.version>1.58.0</playwright.version>
</properties>

<dependencies>
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay-playwright</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-ensure</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-junit5</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>com.microsoft.playwright</groupId>
        <artifactId>playwright</artifactId>
        <version>${playwright.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>6.0.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

## Part 1: Our First Test

Let's start with the simplest possible test - adding a single todo item.

### Step 1: Create the Base Test Class

First, create a base class that sets up our actor with Playwright abilities:

```java
package todomvc.screenplay;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import org.junit.jupiter.api.BeforeEach;

public abstract class ScreenplayPlaywrightTest {

    protected Actor toby;

    @BeforeEach
    void setUpPlaywright() {
        toby = Actor.named("Toby");
        toby.can(BrowseTheWebWithPlaywright.usingTheDefaultConfiguration());
    }

    // No @AfterEach needed - BrowseTheWebWithPlaywright automatically
    // cleans up browser resources when the test finishes
}
```

:::tip Automatic Cleanup
The `BrowseTheWebWithPlaywright` ability subscribes to Serenity's test lifecycle events and automatically closes the browser, context, and page when each test completes. You don't need to write any teardown code!
:::

:::info Alternative: Using `@UsePlaywright`
If you prefer to use Playwright's `@UsePlaywright` annotation for browser lifecycle management, you can wrap the injected `Page` instead:

```java
import com.microsoft.playwright.Page;
import com.microsoft.playwright.junit.UsePlaywright;
import net.serenitybdd.playwright.junit5.SerenityPlaywrightExtension;

@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright
public abstract class ScreenplayPlaywrightTest {

    protected Actor toby;

    @BeforeEach
    void setUpPlaywright(Page page) {
        toby = Actor.named("Toby");
        toby.can(BrowseTheWebWithPlaywright.withPage(page));
    }
}
```

The `SerenityPlaywrightExtension` registers Playwright pages with Serenity for automatic screenshot capture. This shares a single browser instance between `@UsePlaywright` and Screenplay, instead of creating two separate browsers. See [Using @UsePlaywright with Screenplay](#using-useplaywright-with-screenplay) at the end of this tutorial for a full walkthrough.
:::

### Step 2: Define UI Targets

Create a class to hold all UI element locators:

```java
package todomvc.screenplay.ui;

import net.serenitybdd.screenplay.playwright.Target;

public class TodoList {

    public static final Target NEW_TODO_INPUT =
        Target.the("new todo input")
              .locatedBy("[placeholder='What needs to be done?']");

    public static final Target TODO_ITEMS =
        Target.the("todo items")
              .locatedBy(".todo-list li");

    public static final Target TODO_ITEM_LABELS =
        Target.the("todo item labels")
              .locatedBy(".todo-list li label");
}
```

### Step 3: Create the First Task

Create a task to open the TodoMVC application:

```java
package todomvc.screenplay.tasks;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.playwright.interactions.Open;
import net.serenitybdd.annotations.Step;

public class OpenTodoMvcApp implements Task {

    private static final String URL = "https://todomvc.com/examples/react/dist/";

    @Override
    @Step("{0} opens the TodoMVC application")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(Open.url(URL));
    }

    public static OpenTodoMvcApp onTheHomePage() {
        return new OpenTodoMvcApp();
    }
}
```

### Step 4: Create the Add Todo Task

```java
package todomvc.screenplay.tasks;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.playwright.interactions.Enter;
import net.serenitybdd.screenplay.playwright.interactions.Press;
import net.serenitybdd.annotations.Step;
import todomvc.screenplay.ui.TodoList;

public class AddATodoItem implements Task {

    private final String todoItem;

    public AddATodoItem(String todoItem) {
        this.todoItem = todoItem;
    }

    @Override
    @Step("{0} adds a todo item called '#todoItem'")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Enter.theValue(todoItem).into(TodoList.NEW_TODO_INPUT),
            Press.keys("Enter")
        );
    }

    public static AddATodoItem called(String todoItem) {
        return new AddATodoItem(todoItem);
    }
}
```

### Step 5: Create a Question

Create a question to count visible todos:

```java
package todomvc.screenplay.questions;

import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import todomvc.screenplay.ui.TodoList;

public class TheVisibleTodos {

    public static Question<Integer> count() {
        return Question.about("visible todo count").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(TodoList.TODO_ITEMS.asSelector())
                .count()
        );
    }
}
```

### Step 6: Write the Test

```java
package todomvc.screenplay;

import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.ensure.Ensure;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import todomvc.screenplay.questions.TheVisibleTodos;
import todomvc.screenplay.tasks.AddATodoItem;
import todomvc.screenplay.tasks.OpenTodoMvcApp;

@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("When adding todos")
class WhenAddingTodosTest extends ScreenplayPlaywrightTest {

    @Test
    @DisplayName("should add a single todo item")
    void shouldAddSingleTodoItem() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Buy milk"),
            Ensure.that(TheVisibleTodos.count()).isEqualTo(1)
        );
    }
}
```

Run it with `mvn clean verify` - you should see a passing test with a Serenity report.

## Part 2: Expanding Our Test Suite

Now let's add more capabilities.

### Adding More Targets

Expand the `TodoList` class with more locators:

```java
public class TodoList {

    // Input elements
    public static final Target NEW_TODO_INPUT =
        Target.the("new todo input")
              .locatedBy("[placeholder='What needs to be done?']");

    // Todo items
    public static final Target TODO_ITEMS =
        Target.the("todo items")
              .locatedBy(".todo-list li");

    public static final Target TODO_ITEM_LABELS =
        Target.the("todo item labels")
              .locatedBy(".todo-list li label");

    // Dynamic targets for specific items
    public static Target todoItemCalled(String text) {
        return Target.the("todo '" + text + "'")
                     .locatedBy(".todo-list li:has-text('" + text + "')");
    }

    public static Target checkboxFor(String text) {
        return Target.the("checkbox for '" + text + "'")
                     .locatedBy(".todo-list li:has-text('" + text + "') .toggle");
    }

    public static Target deleteButtonFor(String text) {
        return Target.the("delete button for '" + text + "'")
                     .locatedBy(".todo-list li:has-text('" + text + "') .destroy");
    }

    // Footer elements
    public static final Target TODO_COUNT =
        Target.the("todo count")
              .locatedBy(".todo-count");

    public static final Target CLEAR_COMPLETED_BUTTON =
        Target.the("clear completed button")
              .locatedBy(".clear-completed");

    // Filters
    public static final Target ALL_FILTER =
        Target.the("All filter")
              .locatedBy(".filters a:has-text('All')");

    public static final Target ACTIVE_FILTER =
        Target.the("Active filter")
              .locatedBy(".filters a:has-text('Active')");

    public static final Target COMPLETED_FILTER =
        Target.the("Completed filter")
              .locatedBy(".filters a:has-text('Completed')");

    public static final Target SELECTED_FILTER =
        Target.the("selected filter")
              .locatedBy(".filters a.selected");
}
```

### Complete Task

```java
package todomvc.screenplay.tasks;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.playwright.interactions.Click;
import net.serenitybdd.annotations.Step;
import todomvc.screenplay.ui.TodoList;

public class Complete implements Task {

    private final String todoItem;

    public Complete(String todoItem) {
        this.todoItem = todoItem;
    }

    @Override
    @Step("{0} completes the todo item '#todoItem'")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Click.on(TodoList.checkboxFor(todoItem))
        );
    }

    public static Complete todoItem(String todoItem) {
        return new Complete(todoItem);
    }
}
```

### Delete Task

```java
package todomvc.screenplay.tasks;

import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.playwright.interactions.Click;
import net.serenitybdd.screenplay.playwright.interactions.Hover;
import net.serenitybdd.annotations.Step;
import todomvc.screenplay.ui.TodoList;

public class Delete implements Task {

    private final String todoItem;

    public Delete(String todoItem) {
        this.todoItem = todoItem;
    }

    @Override
    @Step("{0} deletes the todo item '#todoItem'")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Hover.over(TodoList.todoItemCalled(todoItem)),
            Click.on(TodoList.deleteButtonFor(todoItem))
        );
    }

    public static Delete theTodoItem(String todoItem) {
        return new Delete(todoItem);
    }
}
```

### Filter Tasks

```java
package todomvc.screenplay.tasks;

import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.playwright.interactions.Click;
import todomvc.screenplay.ui.TodoList;

public class FilterTodos {

    public static Task toShowAll() {
        return Task.where("{0} filters to show all todos",
            Click.on(TodoList.ALL_FILTER)
        );
    }

    public static Task toShowActive() {
        return Task.where("{0} filters to show active todos",
            Click.on(TodoList.ACTIVE_FILTER)
        );
    }

    public static Task toShowCompleted() {
        return Task.where("{0} filters to show completed todos",
            Click.on(TodoList.COMPLETED_FILTER)
        );
    }
}
```

### More Questions

```java
// TheVisibleTodos.java - expanded
package todomvc.screenplay.questions;

import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import todomvc.screenplay.ui.TodoList;

import java.util.Collection;

public class TheVisibleTodos {

    public static Question<Collection<String>> displayed() {
        return Question.about("the visible todos").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(TodoList.TODO_ITEM_LABELS.asSelector())
                .allTextContents()
        );
    }

    public static Question<Integer> count() {
        return Question.about("visible todo count").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(TodoList.TODO_ITEMS.asSelector())
                .count()
        );
    }
}
```

```java
// TheRemainingCount.java
package todomvc.screenplay.questions;

import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import todomvc.screenplay.ui.TodoList;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class TheRemainingCount {

    private static final Pattern COUNT_PATTERN = Pattern.compile("(\\d+)");

    public static Question<Integer> value() {
        return Question.about("the remaining count").answeredBy(actor -> {
            String text = BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(TodoList.TODO_COUNT.asSelector())
                .textContent();

            Matcher matcher = COUNT_PATTERN.matcher(text);
            return matcher.find() ? Integer.parseInt(matcher.group(1)) : 0;
        });
    }
}
```

```java
// TheCurrentFilter.java
package todomvc.screenplay.questions;

import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import todomvc.screenplay.ui.TodoList;

public class TheCurrentFilter {

    public static Question<String> selected() {
        return Question.about("the current filter").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(TodoList.SELECTED_FILTER.asSelector())
                .textContent()
        );
    }
}
```

```java
// TheTodoItem.java - fluent question builder
package todomvc.screenplay.questions;

import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import todomvc.screenplay.ui.TodoList;

public class TheTodoItem {

    private final String todoItem;

    public TheTodoItem(String todoItem) {
        this.todoItem = todoItem;
    }

    public static TheTodoItem called(String todoItem) {
        return new TheTodoItem(todoItem);
    }

    public Question<Boolean> exists() {
        String item = todoItem;
        return Question.about("whether '" + item + "' exists").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(TodoList.todoItemCalled(item).asSelector())
                .count() > 0
        );
    }

    public Question<Boolean> isCompleted() {
        String item = todoItem;
        return Question.about("whether '" + item + "' is completed").answeredBy(
            actor -> BrowseTheWebWithPlaywright.as(actor)
                .getCurrentPage()
                .locator(TodoList.todoItemCalled(item).asSelector())
                .getAttribute("class")
                .contains("completed")
        );
    }
}
```

## Part 3: Complete Test Suite

Now we have everything to write a comprehensive test suite:

### Adding Todos Tests

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("When adding todos (Screenplay)")
class WhenAddingTodosScreenplayTest extends ScreenplayPlaywrightTest {

    @Test
    @DisplayName("should add a single todo item")
    void shouldAddSingleTodoItem() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Buy milk"),
            Ensure.that(TheVisibleTodos.count()).isEqualTo(1),
            Ensure.that(TheTodoItem.called("Buy milk").exists()).isTrue()
        );
    }

    @Test
    @DisplayName("should add multiple todo items")
    void shouldAddMultipleTodoItems() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Buy milk"),
            AddATodoItem.called("Walk the dog"),
            AddATodoItem.called("Do laundry"),
            Ensure.that(TheVisibleTodos.displayed())
                .containsExactly("Buy milk", "Walk the dog", "Do laundry")
        );
    }

    @Test
    @DisplayName("should update remaining count when adding todos")
    void shouldUpdateRemainingCountWhenAddingTodos() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Task 1"),
            Ensure.that(TheRemainingCount.value()).isEqualTo(1),

            AddATodoItem.called("Task 2"),
            Ensure.that(TheRemainingCount.value()).isEqualTo(2),

            AddATodoItem.called("Task 3"),
            Ensure.that(TheRemainingCount.value()).isEqualTo(3)
        );
    }
}
```

### Completing Todos Tests

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("When completing todos (Screenplay)")
class WhenCompletingTodosScreenplayTest extends ScreenplayPlaywrightTest {

    @BeforeEach
    void setupTodos() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Buy milk"),
            AddATodoItem.called("Walk the dog"),
            AddATodoItem.called("Do laundry")
        );
    }

    @Test
    @DisplayName("should mark a todo as completed")
    void shouldMarkTodoAsCompleted() {
        toby.attemptsTo(
            Complete.todoItem("Buy milk"),
            Ensure.that(TheTodoItem.called("Buy milk").isCompleted()).isTrue(),
            Ensure.that(TheRemainingCount.value()).isEqualTo(2)
        );
    }

    @Test
    @DisplayName("should clear completed todos")
    void shouldClearCompletedTodos() {
        toby.attemptsTo(
            Complete.todoItem("Buy milk"),
            Complete.todoItem("Walk the dog"),
            Click.on(TodoList.CLEAR_COMPLETED_BUTTON),
            Ensure.that(TheVisibleTodos.displayed()).containsExactly("Do laundry"),
            Ensure.that(TheVisibleTodos.count()).isEqualTo(1)
        );
    }
}
```

### Filtering Tests

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("When filtering todos (Screenplay)")
class WhenFilteringTodosScreenplayTest extends ScreenplayPlaywrightTest {

    @BeforeEach
    void setupTodos() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Buy milk"),
            AddATodoItem.called("Walk the dog"),
            AddATodoItem.called("Do laundry"),
            Complete.todoItem("Walk the dog")
        );
    }

    @Test
    @DisplayName("should show all todos by default")
    void shouldShowAllTodosByDefault() {
        toby.attemptsTo(
            Ensure.that(TheCurrentFilter.selected()).isEqualTo("All"),
            Ensure.that(TheVisibleTodos.displayed())
                .containsExactly("Buy milk", "Walk the dog", "Do laundry")
        );
    }

    @Test
    @DisplayName("should filter to show only active todos")
    void shouldFilterToShowOnlyActiveTodos() {
        toby.attemptsTo(
            FilterTodos.toShowActive(),
            Ensure.that(TheCurrentFilter.selected()).isEqualTo("Active"),
            Ensure.that(TheVisibleTodos.displayed())
                .containsExactly("Buy milk", "Do laundry")
        );
    }

    @Test
    @DisplayName("should filter to show only completed todos")
    void shouldFilterToShowOnlyCompletedTodos() {
        toby.attemptsTo(
            FilterTodos.toShowCompleted(),
            Ensure.that(TheCurrentFilter.selected()).isEqualTo("Completed"),
            Ensure.that(TheVisibleTodos.displayed()).containsExactly("Walk the dog")
        );
    }

    @Test
    @DisplayName("should switch between filters")
    void shouldSwitchBetweenFilters() {
        toby.attemptsTo(
            FilterTodos.toShowActive(),
            Ensure.that(TheVisibleTodos.count()).isEqualTo(2),

            FilterTodos.toShowCompleted(),
            Ensure.that(TheVisibleTodos.count()).isEqualTo(1),

            FilterTodos.toShowAll(),
            Ensure.that(TheVisibleTodos.count()).isEqualTo(3)
        );
    }
}
```

### Deleting Tests

```java
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("When deleting todos (Screenplay)")
class WhenDeletingTodosScreenplayTest extends ScreenplayPlaywrightTest {

    @BeforeEach
    void setupTodos() {
        toby.attemptsTo(
            OpenTodoMvcApp.onTheHomePage(),
            AddATodoItem.called("Buy milk"),
            AddATodoItem.called("Walk the dog"),
            AddATodoItem.called("Do laundry")
        );
    }

    @Test
    @DisplayName("should delete a todo item")
    void shouldDeleteTodoItem() {
        toby.attemptsTo(
            Delete.theTodoItem("Walk the dog"),
            Ensure.that(TheTodoItem.called("Walk the dog").exists()).isFalse(),
            Ensure.that(TheVisibleTodos.displayed())
                .containsExactly("Buy milk", "Do laundry")
        );
    }

    @Test
    @DisplayName("should update the remaining count after deleting")
    void shouldUpdateRemainingCountAfterDeleting() {
        toby.attemptsTo(
            Ensure.that(TheRemainingCount.value()).isEqualTo(3),
            Delete.theTodoItem("Buy milk"),
            Ensure.that(TheRemainingCount.value()).isEqualTo(2)
        );
    }
}
```

## Using `@UsePlaywright` with Screenplay

Throughout this tutorial, we used `BrowseTheWebWithPlaywright.usingTheDefaultConfiguration()` — which creates and manages its own Playwright browser. But if your project already uses Playwright's `@UsePlaywright` annotation (for example, to share browser configuration or integrate with Playwright's built-in test fixtures), you can adapt the Screenplay tests to reuse that browser session.

### Updating the Base Test Class

Replace `usingTheDefaultConfiguration()` with `withPage(page)`, and add the `@UsePlaywright` and `SerenityPlaywrightExtension` annotations:

```java
package todomvc.screenplay;

import com.microsoft.playwright.Page;
import com.microsoft.playwright.junit.UsePlaywright;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.playwright.junit5.SerenityPlaywrightExtension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright
public abstract class ScreenplayPlaywrightTest {

    protected Actor toby;

    @BeforeEach
    void setUpPlaywright(Page page) {
        toby = Actor.named("Toby");
        toby.can(BrowseTheWebWithPlaywright.withPage(page));
    }
}
```

Three annotations work together:

| Annotation | Purpose |
|-----------|---------|
| `@ExtendWith(SerenityJUnit5Extension.class)` | Serenity BDD reporting and step injection |
| `@ExtendWith(SerenityPlaywrightExtension.class)` | Registers Playwright pages with Serenity for automatic screenshots |
| `@UsePlaywright` | Manages the full Playwright lifecycle (Playwright, Browser, BrowserContext, Page) |

:::tip Using @SerenityPlaywright
You can replace both `@ExtendWith` annotations with the shorthand `@SerenityPlaywright`:
```java
@SerenityPlaywright
@UsePlaywright
public abstract class ScreenplayPlaywrightTest {
    // ...
}
```
:::

That's it. All the tasks, questions, targets, and test classes from this tutorial work unchanged — the only difference is how the actor's ability is created.

### What Changes

| | `usingTheDefaultConfiguration()` | `withPage(page)` |
|---|---|---|
| **Browser lifecycle** | Managed by Screenplay | Managed by `@UsePlaywright` |
| **Browser instance** | New browser per actor | Reuses `@UsePlaywright` browser |
| **Teardown** | Closes browser, context, page | Only unregisters from Serenity |
| **Tasks & Questions** | Work normally | Work normally |
| **Screenshots & reports** | Captured automatically | Captured automatically |

### Custom Playwright Options

With `@UsePlaywright`, you can customize browser options by implementing `OptionsFactory`:

```java
import com.microsoft.playwright.*;
import com.microsoft.playwright.junit.Options;
import com.microsoft.playwright.junit.OptionsFactory;

public class CustomOptions implements OptionsFactory {

    @Override
    public Options getOptions() {
        return new Options()
            .setLaunchOptions(new BrowserType.LaunchOptions().setHeadless(true))
            .setContextOptions(new Browser.NewContextOptions()
                .setViewportSize(1920, 1080)
                .setLocale("en-US"));
    }
}
```

Then reference it in your tests:

```java
@ExtendWith(SerenityJUnit5Extension.class)
@ExtendWith(SerenityPlaywrightExtension.class)
@UsePlaywright(CustomOptions.class)
public abstract class ScreenplayPlaywrightTest {
    // ...same as above
}
```

### When to Use Which Approach

- **`usingTheDefaultConfiguration()`** — simplest setup; ideal when Screenplay is your only test framework and you don't need Playwright's JUnit integration features.
- **`withPage(page)`** — use when you already have `@UsePlaywright` tests and want to add Screenplay actors to them, or when you need Playwright's built-in fixtures (tracing, video recording, custom options) alongside Screenplay.

## Key Takeaways

### The Screenplay Pattern Benefits

1. **Readability**: Tests read like specifications
   ```java
   toby.attemptsTo(
       OpenTodoMvcApp.onTheHomePage(),
       AddATodoItem.called("Buy milk"),
       Complete.todoItem("Buy milk"),
       Ensure.that(TheRemainingCount.value()).isEqualTo(0)
   );
   ```

2. **Reusability**: Tasks and Questions can be composed and reused
3. **Maintainability**: Changes to UI are isolated to Target definitions
4. **Expressiveness**: Business intent is clear in every test

### Project Structure

```
src/test/java/
├── todomvc/screenplay/
│   ├── ScreenplayPlaywrightTest.java    # Base test class
│   ├── WhenAddingTodosTest.java         # Test class
│   ├── WhenCompletingTodosTest.java     # Test class
│   ├── WhenFilteringTodosTest.java      # Test class
│   ├── WhenDeletingTodosTest.java       # Test class
│   ├── ui/
│   │   └── TodoList.java                # UI Targets
│   ├── tasks/
│   │   ├── OpenTodoMvcApp.java
│   │   ├── AddATodoItem.java
│   │   ├── Complete.java
│   │   ├── Delete.java
│   │   └── FilterTodos.java
│   └── questions/
│       ├── TheVisibleTodos.java
│       ├── TheRemainingCount.java
│       ├── TheCurrentFilter.java
│       └── TheTodoItem.java
```

## Next Steps

- Learn about [advanced Screenplay features](playwright_screenplay) including network interception and multiple tabs
- Explore [Playwright-specific assertions](playwright_screenplay#playwright-specific-assertions) with auto-retry
- See [Best Practices](playwright_best_practices) for production-ready tests


---

<!-- https://serenity-bdd.github.io/docs/playwright/playwright_cucumber -->

# Cucumber Integration with Playwright Screenplay

Cucumber provides a natural language syntax for writing behavior-driven tests. When combined with Serenity Playwright's Screenplay implementation, you get expressive BDD scenarios that drive reliable browser automation.

This guide shows you how to integrate Cucumber with Serenity Playwright using the Screenplay pattern.

## Project Setup

### Maven Dependencies

Add the following dependencies to your `pom.xml`:

```xml
<properties>
    <serenity.version>5.3.11</serenity.version>
    <playwright.version>1.58.0</playwright.version>
    <cucumber.version>7.34.2</cucumber.version>
    <junit.version>5.11.4</junit.version>
</properties>

<dependencyManagement>
    <dependencies>
        <!-- Use BOMs for version management -->
        <dependency>
            <groupId>org.junit</groupId>
            <artifactId>junit-bom</artifactId>
            <version>${junit.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-bom</artifactId>
            <version>${cucumber.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Serenity Screenplay with Playwright -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-screenplay-playwright</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Serenity Cucumber Integration -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-cucumber</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- Cucumber (versions managed by cucumber-bom) -->
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-java</artifactId>
        <scope>test</scope>
    </dependency>

    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-junit-platform-engine</artifactId>
        <scope>test</scope>
    </dependency>

    <!-- JUnit Platform Suite -->
    <dependency>
        <groupId>org.junit.platform</groupId>
        <artifactId>junit-platform-suite</artifactId>
        <scope>test</scope>
    </dependency>

    <!-- Serenity Ensure for assertions -->
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-ensure</artifactId>
        <version>${serenity.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

### Install Playwright Browsers

Before running tests, install the Playwright browsers:

```bash
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"
```

## Project Structure

A typical project structure looks like this:

```
src/test/
├── java/
│   └── yourpackage/
│       ├── cucumber/
│       │   ├── CucumberTestSuite.java      # Test runner
│       │   ├── PlaywrightHooks.java        # Cucumber hooks
│       │   └── StepDefinitions.java        # Step definitions
│       └── screenplay/
│           ├── tasks/                       # Reusable tasks
│           │   ├── OpenTheApplication.java
│           │   └── AddATodoItem.java
│           ├── questions/                   # Reusable questions
│           │   └── TheVisibleTodos.java
│           └── ui/                          # Target definitions
│               └── TodoList.java
└── resources/
    ├── features/
    │   └── managing_todos.feature          # Feature files
    └── serenity.properties                  # Configuration
```

## Step 1: Create the Test Runner

The test runner configures Cucumber to work with Serenity:

```java
package yourpackage.cucumber;

import org.junit.platform.suite.api.*;
import static io.cucumber.junit.platform.engine.Constants.*;

@Suite
@IncludeEngines("cucumber")
@SelectPackages("yourpackage.cucumber")
@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME,
    value = "net.serenitybdd.cucumber.core.plugin.SerenityReporterParallel,pretty")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME,
    value = "yourpackage.cucumber,net.serenitybdd.cucumber.actors")
@ConfigurationParameter(key = FEATURES_PROPERTY_NAME,
    value = "src/test/resources/features")
public class CucumberTestSuite {
}
```

:::important Glue Path Configuration
Always include `net.serenitybdd.cucumber.actors` in your glue path. This registers Serenity's `StageDirector` which automatically calls `OnStage.drawTheCurtain()` after each scenario to clean up browser resources.
:::

## Step 2: Create Playwright Hooks

The hooks class sets up the Playwright stage before each scenario:

```java
package yourpackage.cucumber;

import io.cucumber.java.Before;
import io.cucumber.java.ParameterType;
import io.cucumber.java.Scenario;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.playwright.actors.PlaywrightCast;

public class PlaywrightHooks {

    /**
     * Set up the Playwright stage before each scenario.
     * Order 0 ensures this runs first among all @Before hooks.
     */
    @Before(order = 0)
    public void setTheStage(Scenario scenario) {
        OnStage.setTheStage(new PlaywrightCast());
    }

    /**
     * Define the {actor} parameter type for Cucumber steps.
     * This allows steps like "Given Toby is on the application"
     * to automatically resolve "Toby" to an Actor instance.
     */
    @ParameterType(".*")
    public Actor actor(String actorName) {
        return OnStage.theActorCalled(actorName);
    }
}
```

### Understanding the Hooks

**`@Before(order = 0)`**: The `order = 0` ensures the stage is set up before any other hooks run. This is important if you have other `@Before` hooks that depend on actors.

**`@ParameterType(".*")`**: This creates a custom parameter type that converts actor names in feature files to `Actor` instances. The pattern `.*` matches any string.

**Automatic Cleanup**: You don't need an `@After` hook for cleanup. The `StageDirector` (included via the glue path) automatically handles cleanup by calling `OnStage.drawTheCurtain()`.

## Step 3: Write Feature Files

Feature files describe behavior in Gherkin syntax:

```gherkin
# src/test/resources/features/managing_todos.feature
@playwright
Feature: Managing Todo Items
  As a busy person
  I want to manage my todo list
  So that I can keep track of what I need to do

  Background:
    Given Toby is on the TodoMVC application

  Scenario: Adding a single todo item
    When Toby adds a todo item called "Buy milk"
    Then the todo list should contain "Buy milk"
    And the remaining item count should be 1

  Scenario: Adding multiple todo items
    When Toby adds the following todo items:
      | Buy milk     |
      | Walk the dog |
      | Do laundry   |
    Then the todo list should contain:
      | Buy milk     |
      | Walk the dog |
      | Do laundry   |
    And the remaining item count should be 3

  Scenario: Completing a todo item
    Given Toby has added the following todo items:
      | Buy milk     |
      | Walk the dog |
    When Toby completes the todo item "Walk the dog"
    Then the remaining item count should be 1

  Scenario: Filtering to show only active todos
    Given Toby has added the following todo items:
      | Buy milk     |
      | Walk the dog |
    And Toby has completed the todo item "Walk the dog"
    When Toby filters to show "Active" todos
    Then the visible todo list should contain:
      | Buy milk |
```

## Step 4: Create Step Definitions

Step definitions bridge feature files to Screenplay tasks:

```java
package yourpackage.cucumber;

import io.cucumber.java.en.*;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.actors.OnStage;
import net.serenitybdd.screenplay.ensure.Ensure;
import yourpackage.screenplay.tasks.*;
import yourpackage.screenplay.questions.*;

import java.util.List;

public class TodoStepDefinitions {

    @Given("{actor} is on the TodoMVC application")
    public void actorIsOnTheTodoMvcApplication(Actor actor) {
        actor.attemptsTo(
            OpenTheApplication.onTheTodoMvcHomePage()
        );
    }

    @When("{actor} adds a todo item called {string}")
    public void actorAddsTodoItemCalled(Actor actor, String todoItem) {
        actor.attemptsTo(
            AddATodoItem.called(todoItem)
        );
    }

    @When("{actor} adds the following todo items:")
    public void actorAddsTheFollowingTodoItems(Actor actor, List<String> todoItems) {
        for (String item : todoItems) {
            actor.attemptsTo(
                AddATodoItem.called(item)
            );
        }
    }

    @Given("{actor} has added the following todo items:")
    public void actorHasAddedTheFollowingTodoItems(Actor actor, List<String> todoItems) {
        actorIsOnTheTodoMvcApplication(actor);
        actorAddsTheFollowingTodoItems(actor, todoItems);
    }

    @When("{actor} completes the todo item {string}")
    public void actorCompletesTheTodoItem(Actor actor, String todoItem) {
        actor.attemptsTo(
            Complete.todoItem(todoItem)
        );
    }

    @Given("{actor} has completed the todo item {string}")
    public void actorHasCompletedTheTodoItem(Actor actor, String todoItem) {
        actorCompletesTheTodoItem(actor, todoItem);
    }

    @When("{actor} filters to show {string} todos")
    public void actorFiltersToShow(Actor actor, String filterType) {
        actor.attemptsTo(
            FilterTodos.toShow(filterType)
        );
    }

    @Then("the todo list should contain {string}")
    public void theTodoListShouldContain(String expectedItem) {
        Actor actor = OnStage.theActorInTheSpotlight();
        actor.attemptsTo(
            Ensure.that(TheVisibleTodos.displayed()).contains(expectedItem)
        );
    }

    @Then("the todo list should contain:")
    public void theTodoListShouldContainItems(List<String> expectedItems) {
        Actor actor = OnStage.theActorInTheSpotlight();
        actor.attemptsTo(
            Ensure.that(TheVisibleTodos.displayed())
                  .containsExactlyElementsFrom(expectedItems)
        );
    }

    @Then("the visible todo list should contain:")
    public void theVisibleTodoListShouldContain(List<String> expectedItems) {
        Actor actor = OnStage.theActorInTheSpotlight();
        actor.attemptsTo(
            Ensure.that(TheVisibleTodos.displayed())
                  .containsExactlyElementsFrom(expectedItems)
        );
    }

    @Then("the remaining item count should be {int}")
    public void theRemainingItemCountShouldBe(int expectedCount) {
        Actor actor = OnStage.theActorInTheSpotlight();
        actor.attemptsTo(
            Ensure.that(TheRemainingCount.value()).isEqualTo(expectedCount)
        );
    }
}
```

### Key Patterns in Step Definitions

**Actor Parameter**: The `{actor}` parameter automatically resolves to an Actor instance thanks to the `@ParameterType` definition in the hooks.

**Background Steps**: Steps like `actorHasAddedTheFollowingTodoItems` compose multiple actions, allowing `Given` steps to set up complex preconditions.

**The Actor in the Spotlight**: For `Then` steps that don't receive an actor parameter, use `OnStage.theActorInTheSpotlight()` to get the last actor who performed an action.

**Data Tables**: Cucumber data tables map directly to `List<String>` for single-column tables.

## Step 5: Create Screenplay Tasks

Tasks encapsulate business-level actions:

```java
package yourpackage.screenplay.tasks;

import net.serenitybdd.annotations.Step;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import net.serenitybdd.screenplay.playwright.interactions.Open;

public class OpenTheApplication implements Task {

    private static final String TODO_MVC_URL = "https://todomvc.com/examples/react/dist/";

    @Override
    @Step("{0} opens the TodoMVC application")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Open.url(TODO_MVC_URL)
        );

        // Clear localStorage to ensure a clean slate
        // (TodoMVC persists todos in localStorage)
        var page = BrowseTheWebWithPlaywright.as(actor).getCurrentPage();
        page.evaluate("() => localStorage.clear()");
        page.reload();
    }

    public static OpenTheApplication onTheTodoMvcHomePage() {
        return new OpenTheApplication();
    }
}
```

```java
package yourpackage.screenplay.tasks;

import net.serenitybdd.annotations.Step;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.playwright.interactions.*;
import yourpackage.screenplay.ui.TodoList;

public class AddATodoItem implements Task {

    private final String itemName;

    public AddATodoItem(String itemName) {
        this.itemName = itemName;
    }

    @Override
    @Step("{0} adds a todo item called '#itemName'")
    public <T extends Actor> void performAs(T actor) {
        actor.attemptsTo(
            Enter.theValue(itemName).into(TodoList.NEW_TODO_INPUT),
            Press.keys("Enter")
        );
    }

    public static AddATodoItem called(String itemName) {
        return new AddATodoItem(itemName);
    }
}
```

## Step 6: Create Screenplay Questions

Questions query the application state:

```java
package yourpackage.screenplay.questions;

import net.serenitybdd.annotations.Step;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.playwright.abilities.BrowseTheWebWithPlaywright;
import yourpackage.screenplay.ui.TodoList;

import java.util.Collection;

public class TheVisibleTodos implements Question<Collection<String>> {

    @Override
    @Step("{0} checks the visible todo items")
    public Collection<String> answeredBy(Actor actor) {
        var page = BrowseTheWebWithPlaywright.as(actor).getCurrentPage();
        return page.locator(TodoList.TODO_ITEMS.asSelector())
                   .allTextContents();
    }

    public static TheVisibleTodos displayed() {
        return new TheVisibleTodos();
    }
}
```

## Step 7: Define UI Targets

Targets define how to locate elements:

```java
package yourpackage.screenplay.ui;

import net.serenitybdd.screenplay.playwright.Target;

public class TodoList {
    public static final Target NEW_TODO_INPUT =
        Target.the("new todo input").locatedBy(".new-todo");

    public static final Target TODO_ITEMS =
        Target.the("todo items").locatedBy(".todo-list li label");

    public static final Target TODO_COUNT =
        Target.the("todo count").locatedBy(".todo-count");

    public static final Target TOGGLE_ALL =
        Target.the("toggle all checkbox").locatedBy(".toggle-all");
}
```

## Running the Tests

### Run All Cucumber Tests

```bash
mvn clean verify
```

### Run Tests with Specific Tags

```bash
mvn clean verify -Dcucumber.filter.tags="@playwright"
```

### Run a Single Scenario

```bash
mvn clean verify -Dcucumber.filter.name="Adding a single todo item"
```

### View Reports

After running tests, open the Serenity report:

```
target/site/serenity/index.html
```

## Configuration

### serenity.properties

```properties
# Browser settings
playwright.browsertype=chromium
playwright.headless=true
playwright.channel=chrome
playwright.baseurl=https://staging.example.com
playwright.slowmo=200

# Screenshot settings
serenity.take.screenshots=FOR_FAILURES

# Report settings
serenity.project.name=My TodoMVC Tests
```

### cucumber.properties

```properties
# Cucumber settings
cucumber.publish.quiet=true
```

## Advanced Configuration

### Custom Browser Configuration

Configure `PlaywrightCast` with custom options:

```java
@Before(order = 0)
public void setTheStage(Scenario scenario) {
    BrowserType.LaunchOptions options = new BrowserType.LaunchOptions()
        .setHeadless(false)
        .setSlowMo(100);  // Slow down for debugging

    OnStage.setTheStage(
        new PlaywrightCast()
            .withLaunchOptions(options)
            .withBrowserType("firefox")
    );
}
```

### Multiple Actors

Scenarios can involve multiple actors:

```gherkin
Scenario: Collaborative editing
  Given Alice has added a todo item called "Shared task"
  When Bob views the todo list
  Then Bob should see "Shared task" in the list
```

```java
@When("{actor} views the todo list")
public void actorViewsTheTodoList(Actor actor) {
    actor.attemptsTo(
        OpenTheApplication.onTheTodoMvcHomePage()
    );
}
```

Each actor gets their own browser instance automatically through `PlaywrightCast`.

## Troubleshooting

### State Leakage Between Scenarios

If tests interfere with each other:

1. Verify `net.serenitybdd.cucumber.actors` is in your glue path
2. Clear application state (like localStorage) in your navigation task
3. Ensure `@Before(order = 0)` is set on your stage setup hook

### Element Not Found

If elements aren't being found:

1. Use Playwright's built-in auto-waiting (it's enabled by default)
2. Check your selectors using browser DevTools
3. Consider using Playwright's more robust selectors like `text=`, `role=`, etc.

### Screenshots Not Captured

Set screenshot mode in `serenity.properties`:

```properties
serenity.take.screenshots=FOR_EACH_ACTION
```

## Example Repository

A complete working example is available in the [serenity-playwright-todomvc-demo](https://github.com/serenity-bdd/serenity-playwright-todomvc-demo) repository.

## See Also

- [Screenplay Pattern with Playwright](playwright_screenplay) - Core Screenplay concepts
- [Tutorial: Screenplay with TodoMVC](playwright_screenplay_tutorial) - Building a test suite from scratch
- [Cucumber Configuration Reference](/docs/cucumber/configuration-reference) - All Cucumber options
- [Parallel Execution](/docs/cucumber/parallel-execution) - Running tests in parallel


---

<!-- https://serenity-bdd.github.io/docs/spring/integration_testing_spring -->

Spring projects are well suited for running your acceptance tests against different layers of your application.

With Serenity, you can ensure correct behavior using a browser or the REST API or work with the service layer of your application directly.

Occasionally it can also be useful to access the service layers directly in your browser-based end-to-end tests.

For example, you may have a scenario where a user action must, as a side effect, record an audit log in a table in the database.

To keep your test focused and simple, you may want to call the service layer directly to check the audit logs, rather than using the browser to log in as an administrator and navigate to the audit logs screen.

Integration tests must use the `SerenityRunner`.
To be able to inject (e.g. `@Autowired`) dependencies and use the usual annotations (like `@DirtiesContext`), you just need to include the Serenity `SpringIntegrationMethodRule` in your test class.

```java
@RunWith(SerenityRunner.class)
@SpringBootTest
public class WhenInjectingSpringDependencies {

    @Managed
    WebDriver driver;

    @ManagedPages(defaultUrl = "http://www.google.com")
    public Pages pages;

    @Rule
    public SpringIntegrationMethodRule springIntegrationMethodRule =
      new SpringIntegrationMethodRule();

    @Autowired
    public GizmoService gizmoService;

    @Test
    public void shouldInstantiateGizmoService() {
        assertThat(gizmoService, is(not(nullValue())));
    }

    @Test
    public void shouldInstantiateNestedServices() {
        assertThat(gizmoService.getWidgetService(), is(not(nullValue())));
    }
}
```

### In Spring Boot &lt;1.3

use the `@ContextConfiguration` annotation to define the configuration file or files to use. Then you can inject dependencies as you would with an ordinary Spring integration test, using the usual Spring annotations such as `@Autowired` or `@Resource`. For example, suppose we are using the following Spring configuration file, called ‘config.xml’:

```xml
<beans>
    <bean id="widgetService" class="net.serenity.junit.spring.WidgetService">
        <property name="name"><value>Widgets</value></property>
        <property name="quota"><value>1</value></property>
    </bean>
    <bean id="gizmoService" class="net.serenity.junit.spring.GizmoService">
        <property name="name"><value>Gizmos</value></property>
        <property name="widgetService"><ref bean="widgetService" /></property>
    </bean>
</beans>
```

We can use this configuration file to inject dependencies as shown here:

```java
@RunWith(SerenityRunner.class)
@ContextConfiguration(locations = "/config.xml")
public class WhenInjectingSpringDependencies {

    @Managed
    WebDriver driver;

    @ManagedPages(defaultUrl = "http://www.google.com")
    public Pages pages;

    @Rule
    public SpringIntegrationMethodRule springIntegrationMethodRule = new SpringIntegrationMethodRule();

    @Autowired
    public GizmoService gizmoService;

    @Test
    public void shouldInstantiateGizmoService() {
        assertThat(gizmoService, is(not(nullValue())));
    }

    @Test
    public void shouldInstantiateNestedServices() {
        assertThat(gizmoService.getWidgetService(), is(not(nullValue())));
    }
}
```

Other context-related annotations such as `@DirtiesContext` will also work as they would in a traditional Spring Integration test. Spring will create a new ApplicationContext for each test, but it will use a single ApplicationContext for all of the methods in your test. If one of your tests modifies an object in the ApplicationContext, you may want to tell Spring so that it can reset the context for the next test. You do this using the `@DirtiesContext` annotation. In the following test case, for example, the tests will fail without the `@DirtiesContext` annotation:

```java
@RunWith(SerenityRunner.class)
@ContextConfiguration(locations = "/spring/config.xml")
public class WhenWorkingWithDirtyContexts {

    @Managed
    WebDriver driver;

    @ManagedPages(defaultUrl = "http://www.google.com")
    public Pages pages;

    @Rule
    public SpringIntegration springIntegration = new SpringIntegration();

    @Autowired
    public GizmoService gizmoService;

    @Test
    @DirtiesContext
    public void shouldNotBeAffectedByTheOtherTest() {
        assertThat(gizmoService.getName(), is("Gizmos"));
        gizmoService.setName("New Gizmos");
    }

    @Test
    @DirtiesContext
    public void shouldNotBeAffectedByTheOtherTestEither() {
        assertThat(gizmoService.getName(), is("Gizmos"));
        gizmoService.setName("New Gizmos");
    }

}
```

You can also inject Spring dependencies directly into your Step libraries, for JUnit, Cucumber and JBehave, as shown in this example:

```java
@ContextConfiguration(locations = "/spring/config.xml")
public class NestedSpringEnabledSteps {

    @Autowired
    public WidgetService widgetService;

    private String widgetName;

    @Steps
    private NestedSteps nestedSteps;

    @Given("I have a nested autowired Spring bean")
    public void givenIHaveAnAutowiredSpringBean() {
        assertThat(nestedSteps.widgetService, notNullValue());
    }

    @When("I use the nested bean")
    public void whenIUseTheBean() {
        widgetName = nestedSteps.widgetService.getName();
    }

    @Then("the nested bean should be instantiated")
    public void thenItShouldBeInstantiated() {
        assertThat(widgetName, is("Widgets"));
    }

}
```


---

<!-- https://serenity-bdd.github.io/docs/reporting/the_serenity_reports -->

The Serenity reports are a particularly powerful feature of Serenity BDD. They aim not only to _report_ test results, but also to _document_ how features are tested, and what the application does. 

## An overview of the test results

A typical Serenity test report is shown below:

![Functional Coverage Overview](img/reports-overview.png)

This shows a simple pie chart displaying the test result distribution, and bar charts indicating the test outcomes sorted by result and by test duration.

The squiggly lines in the orange bars (indicating broken tests) are for accessiblity. To activate these, you will need the following setting in your `serenity.conf` file:

```hocon
serenity {
    report {
       accessibility = true
    }
}
```

## Functional Test Coverage

Further down the screen you will find the Functional Test Coverage section:
![A typical Serenity Report home page](img/functional-coverage-overview.png)

This section gives a breakdown by capability (or by however you have decided to group your features). You can define the requirements types used in your project using the `serenity.requirement.types` property, e.g.

```hocon
serenity {
  requirement {
    types = "epic, feature"
  }
}
```
Note that for Cucumber, the lowest level will always be defined as _Feature_.

The _Key Statistics_ section shows execution times and the overall number of test scenarios and test cases. You can define the ranges of duration values that appear in the report using the `serenity.report.durations` property: 

```hocon
serenity{
  report {
    durations = "1,2,4,8,15,30,60"
  }
}
```

Serenity distinguishes between more general _Test Scenarios_, and more specific _Test Cases_.

A simple scenario or JUnit test counts as a scenario with a single test case. For example, consider the following scenario:

```gherkin
Scenario: Colin logs in with Colin's valid credentials
    Given Colin is on the login page
    When Colin logs in with valid credentials
    Then he should be presented the product catalog
```

This counts as 1 scenario with 1 test case.

| Scenarios | Test Cases |
|-----------|------------|
| 1         | 1          |

A scenario outline, on the other hand, is a single scenario with many test cases. So if you had the following scenario outline:

```gherkin
    Scenario Outline: Login's with invalid credentials for <username>
      Given Colin is on the login page
      When Colin attempts to login with the following credentials:
        | username   | password   |
        | <username> | <password> |
      Then he should be presented with the error message <message>
      Examples:
        | username        | password       | message                                                     |
        | standard_user   | wrong_password | Username and password do not match any user in this service |
        | unknown_user    | secret_sauce   | Username and password do not match any user in this service |
        | unknown_user    | wrong_password | Username and password do not match any user in this service |
        | locked_out_user | secret_sauce   | Sorry, this user has been locked out                        |
```

Then the test report would include 1 scenario but 4 test cases:

| Scenarios | Test Cases |
|-----------|------------|
| 1         | 4          |

So a test suite that contains both of these scenarios would include 2 scenarios made up of 5 test cases:

| Scenarios | Test Cases |
|-----------|------------|
| 2         | 5          |

## Functional Coverage Details

Further down the functional coverage results are displayed in more detail:

![Functional Coverage Details](img/functional-coverage-details.png)

This lists the requirements by category. By default, Cucumber results organised in folders under `src/test/resources/features` will be organised by Capabilities and Features. As mentioned above, you can customise these categories using the `serenity.requirement.types` property. 


## Test Results

The Test Results tab lists the actual test results:

![Test Results](img/test-results.png)

For data-driven tests and scenario outlines, each row of data is reported as a separate test result, and marked by a table icon to indicate that it is a data-driven test result. 

## Errors and Tags

The last section of the report lists the most frequent causes of test failures:

![Errors and tags](img/tags.png)

This section also mentions which the features containing the most failing tests. You can see which tests fail for a given reason by clicking on the corresponding _error_ tag just below this section.

It also lists the tags appearing in the features. You can exclude tags you don't want to appear in this section (for example, technical tags) using the `serenity.report.exclude.tags` property, e.g.
```
serenity {
    report {
        exclude.tags = "resetappstate,singlebrowser,manual"
    }
}
```


---

<!-- https://serenity-bdd.github.io/docs/reporting/living_documentation -->

## What is Living documentation?

Serenity BDD is more than a library that generates test reports. That is, while you can use Serenity BDD to produce great test reports just fine, the real goal of Serenity BDD is to produce _living documentation_ for your product.

But what do we mean by "living documentation"? Living Documentation is a concept that comes from the world of Behavior Driven Development. It is closely related to the idea of Executable Specifications. Living documentation is, as the name suggests, both _documentation_, and _living_.

* It is _documentation_, because it describes how an application works, and what business rules it applies, in a way that normal users can understand. Well written living documentation can be used by new team members to understand what a product does, and how it works. It can be handed over to a maintenance team when the application goes into production, or it can be used as evidence for auditors to show that the application respects the relevant rules and regulations.
* It is _living_, because it is generated by the automated test suite, and is therefore by definition it is always up-to-date.

In a Serenity BDD report, you can find the Living Documentation in the `Requirements` tab.

#### Requirements Tab {#fig-requirements-tab}

![A test report generated by Serenity](img/requirements-tab.png) 

## Living Documentation and Test Reporting

Living Documentation should not be confused with conventional test reporting. There are a number of important differences, and understanding these differences makes it easier to write good quality living documentation.

### Timing

Conventional test reports are designed and generated fairly late in the development process, typically once features have been delivered and the automated tests written. Testers will often start preparatory work on test cases once the specifications or user stories are finalised, but test reports are still an activity that happens later rather than earlier in the development process.

For a team practicing BDD, on the other hand, the work on Living Documentation starts much earlier. Teams practicing BDD will work together with product owners to define acceptance criteria for the stories to be developed, and these acceptance criteria will form the basis for the automated acceptance tests _and_ for the living documentation that is generated with each build.

### Authors

Test Reports are the responsibility of QA; testers are usually the ones who design the report structure (if any design is done) and generate the test reports.

Living Documentation, on the other hand, is written collaboratively by many different actors: BAs, developers, testers and product owners all play key roles in the BDD requirements discovery process, and help, together, to express the business needs in a form that can be executed as automated acceptance tests.

### Audience and Language

Testers are also the primary consumers of test reports. In many projects, other team members will only ever see test report summaries or overviews.

Living Documentation is for the whole team, including product owners, stakeholders and users involved in the project. It describes what the application should do before a feature is implemented (in the form of pending scenarios), and demonstrates (and gives evidence) that the implemented feature behaves as expected (in the form of passing scenarios). For this reason, living documentation scenarios need to be written in business terms, in a way that is easily understandable by non-testers.

### Purpose and scope
Produced by testers and for testers, a test report naturally has a very strong testing focus. The emphasis is primarily on knowing whether a test passes or fails, and, at a higher level, knowing what proportion of tests pass or fail.

Living Documentation is more like a very detailed illustrated user manual. The focus is about describing what the application does, in business terms.

For example, a scenario in a test report might be interested in checking whether all of the countries appear in a country drop-down list on a user registration page. A scenario appearing in a living documentation report would be more interested in describing the user registration process as a whole, and demonstrating how it works for different types of users, and what business constraints or limitations apply to the choice of countries.

These differences can be summed up in the following table:

**Test Reports** | **Living Documentation**
---|---
Produced after development is done    | Written before development starts
Written by testers                    | Written collaboratively by the whole team
Written mostly for testers            | For the whole team and beyond
Reports on passing and failing tests  | Describes worked examples of functionality

### Living Documentation and other types of tests

Living Documentation is designed to work together with lower-level unit and integration testing to provide a high degree of confidence in the quality of the application. Living documentation will generally focus on key examples of positive and negative paths through the application, and leave the more exhaustive testing to the unit test layers.

In highly regulated environments, on the other hand, living documentation will often be more exhaustive and detailed, as it may be used for audits or regulatory reporting.

In Serenity, living documentation can be "layered", so that the most important details are presented first, and the more exhaustive scenarios presented further down.

At the heart of this reporting is the _Requirements_ tab. Let's see what you will find there.

# The Requirements view

Serenity's requirements view is a core part of the Serenity reporting approach, and understanding how it works is key to producing great living documentation. The Serenity living documentation goes far beyond traditional test reporting: in mature BDD teams working in large organisations, stakeholders regularly use the living documentation produced by Serenity not only to validate and document new releases, but also to explain and document how the system works.

Let's look at the various parts of this report, to better understand you might configure them in your own projects.

## The Requirements Hierarchy

In Serenity, requirements are organised in a hierarchy. You can see this hierarchy in the tree structure in the bottom part of the Requirements tab shown in [A test report generated by Serenity](#fig-requirements-tab).

There are a few ideas of how you can organise this hierarchy at the end of this chapter. You can break your requirements down by high level capabilities down into more granular features, or it might make more sense to organise things in terms of some cross-cutting business functionality.

In all cases, the requirements hierarchy is implemented as a nested directory structure (for Cucumber or JBehave) or as a package structure (for JUnit).

The Requirements hierarchy can be any depth, though it can be confusing if different branches have different depths. At the bottom level are the feature files (for Cucumber), story files (for JBehave) or test classes (for JUnit). The directories that contain these files represent the higher level requirements.

You can get an idea of the full directory structure (in the `src/test/features` directory) for the project shown in [A test report generated by Serenity](#fig-requirements-tab) here:

```
├── customer_due_diligence
│   ├── customer_acceptance_policy
│   │   ├── business_activities.feature
│   │   ├── country_risk_ratings.feature
│   │   ├── customer_risk_profiles.feature
│   │   ├── enhanced_due_diligence.feature
│   │   ├── non-face-to-face-customers.feature
│   │   ├── pep.feature
│   │   ├── readme.md
│   │   └── standard_due_diligence.feature
│   ├── customer_identification
│   │   └── readme.md
│   ├── ongoing_monitoring
│   │   └── readme.md
│   └── readme.md
├── readme.md
└── reporting_controls
    ├── eligibility
    │   ├── cftc_eligibility.feature
    │   ├── mifid2_eligibility.feature
    │   └── readme.md
    ├── readme.md
    └── reportability
        ├── readme.md
        └── reportable_state.feature
```

If you expand the nodes of the requirement tree view, you will get a similar structure in the Requirements tab (see [An expanded requirements tree](#fig-requirements-expanded)).

### An expanded requirements tree{#fig-requirements-expanded}
![An expanded requirements tree](img/requirements-expanded.png)

The tree view also gives you some useful extra information. The little icon on the right hand side of the requirements line tells you the overall result of any executed tests (requirements with no implemented tests are marked as pending). The tree also tells you how many sub-requirements there are underneath each requirement.

## The Requirement description {#fig-requirements-description}

The requirements description is the first thing you see on a typical living documentation report - you can see it below in the white box at the top of the report:

![The Requirements Description](img/reports-overview-summary.png)

This text is a bit like an introduction to a book or to a chapter in a book - it should present the application or high level functionality that is described in detail in the rest of the report.

You can add this introductory text at any level of your requirements hierarchy by adding a `readme.md` file at the appropriate level of your requirements hierarchy. A well-documented set of living documentation will have `readme.md` files at each level of the hierarchy, to explain the purpose and background of each functional area in the application. You can see these files in the directory structure we looked at in the previous section.

Markdown (https://daringfireball.net/projects/markdown/) is a convenient lightweight format that you can use to make your living documentation more readable. The markdown used in the report shown above looks like this:

```markdown
## Regulatory Reporting Controls

This project illustrates Serenity's living documentation capabilities, through a set of requirements for an imaginary investment bank.
 * The _Customer Due Diligence_ requirements, which are partially implemented (a mixture of pending and passing requirements), and
 * The _Reporting controls_, which contain a variety of failing acceptance tests.
```

For any `readme.md` in a nested requirements directory (so any `readme.md` file other than the top level one), the first line should contain the name of the requirement. An example for the _Customer Due Diligence_ capability is shown below:

```markdown
## Customer Due Diligence

Banks are required to "have in place adequate policies, practices and procedures that promote high ethical and professional standards and prevent the bank from being used, intentionally or unintentionally, by criminal elements".

Certain key elements should be included by banks in the design of KYC programmes. Such essential elements should start from the banks’ risk management and control procedures and should include

1) customer acceptance policy,
2) customer identification, and
3) on-going monitoring of high risk accounts
```

### Adding images to the requirement description

You can also include images in the `readme.md` files. By default, Serenity will copy any files in the `src/test/resources/assets` directory into the `target/site/serenity/assets` directory when it generates the reports.

You can place any images you want to include in your living documentation here, and then refer to them using the Markdown image syntax, like this:

```markdown
![Customer Due Diligence](assets/customer-due-diligence.png)
```

This image would then appear in your reports, as illustrated here:

![A rendered application overview including an image](img/requirements-overview-image.png)

If you need to override the location of the `assets` directory, you can do so using the `report.assets.directory` property, as shown here:

```
report.assets.directory=src/test/resources/my-special-resources
```

Note that the target directory in the `target/site/serenity` directory will always be called `assets`.

### Requirements from JUnit 5 test classes

With JUnit 5 you do not need a requirements directory: Serenity builds the hierarchy from the package of each test class (or from the `@Epic`, `@Feature` and `@Story` annotations, described in [Defining Requirements with Annotations](/docs/guide/annotation-requirements)). These points were checked by running them against Serenity 5.4.1:

- A class `shop.ordering.WhenAReaderBuildsABasketTest` appears as `Shop` (capability), then `Ordering` (feature), then the class. The class is named from its class name, `Test` suffix included ("When a reader builds a basket test"), unless it has a `@DisplayName`, which is then used as the feature name. Put a `@DisplayName` with a business phrase on each test class.
- Each scenario is titled by its `@DisplayName`, or by its method name when there is none.
- The introductory text for a package comes from a `readme.md` in `src/test/resources/stories/` followed by the package path (for `shop.ordering`: `src/test/resources/stories/shop/ordering/readme.md`). A `readme.md` in any other folder is not picked up.
- A `@Narrative` on a JUnit 5 test class is not shown in 5.4.1. In releases after 5.4.1 its text is used as the description of the class.
- Package-based and annotation-based classes can coexist. They appear as two separate hierarchies side by side, so choose one way for the whole project if you want a single tree.

## The Test Results tab

The _Test Results_ tab (shown below) tells you about the acceptance tests that were executed for this set of requirements. Both automated and manual tests appear in the summary donut chart and table (the manual results are the same color as the equivalent automated results, but in a lighter tone).

![The test results for a given requirement](img/requirements-results.png)

You can also find the full list of automated and manual test results in the bottom part of the screen.

## Functional Coverage

The Functional Coverage section shows the test results broken down by functional area.

![Functional Coverage](img/requirements-functional-coverage-stats.png)

For example, in the illustration shown above, the _Customer Due Diligence_ high level requirement has three child requirements:

  * Customer Acceptance Policies
  * Customer Identification, and
  * Ongoing Monitoring

The functional coverage view shows the breakdown of test results for each of these child requirements. This is a useful way to get an idea of the stability or release-readiness of different parts of an application.

### Test Results

At the bottom of the `Test Results` tab, you will find the actual test results - the list of all the tests, automated and manual, that were executed for this requirement.

![The test results for a given requirement](img/requirements-test-results.png)

## Feature Overviews

Features are an important part of the Serenity living documentation model. Features correspond to the contents of a feature file in Cucumber, a story file in JBehave, or a test case in JUnit. A feature represents a coherent piece of functionality that customers value; as a rule of thumb, a feature is something we could deploy by itself and the users would still find it useful.

A feature contains a set of acceptance criteria, automated scenarios that demonstrate and verify how the feature works. But often the acceptance criteria are not enough in themselves to fully explain what a feature does. We need some extra information, which we provide at the top of the feature or story file. For example, in the following feature file, we give some additional business context about the _Business Activities_ feature before diving into individual scenarios:

```gherkin
Feature: Business Activities

  Some business activities are considered more risk-prone than others,
  and certain customers and entities may pose specific risks.

  Scenario Outline: The business activity risk factor for an industry

  The industry risk factor is a value from 0 to 10.

    When a customer works in <Business Category>
    Then their base business activity risk factor should be <Risk Factor>

    Examples:
      | Business Category        | Risk Factor |
      | Casino                   | 10          |
      | Precious Metals Exchange | 9           |
      | Currency Exchange        | 9           |
      | Jewellery Store          | 8           |
      | Convenience Store        | 7           |
      | Real Estate Broker       | 6           |
      | Software Development     | 3           |

  Scenario Outline: The business activity risk factor for an established business
      Established businessess have been in activity for 2 years or more

        When a customer with a business risk factor of <Risk Factor>, such as for a <Business Category> business
        And the business been operation for more than two years
        Then their business activity risk rating should be <Risk Rating>

        Examples:
          | Risk Factor | Business Category    | Risk Rating |
          | 7 or above  | Casino               | High        |
          | 5 to 7      | Jewellery Store      | Medium      |
          | Under 5     | Software Development | Low         |
    ...
```

The requirements page for this feature is shown in [The requirements page for a feature](#fig-requirements-feature-overview).

Here we see the introductory text from the top of the feature file,
the list of scenarios (or acceptance criteria) defined for this feature,
and a detailed description of each scenario.
Icons indicate whether a scenario passed or failed, and if you click on the title bar of one of the scenarios, you will go to the test results page for that scenario.

#### The requirements page for a feature {#fig-requirements-feature-overview}
![The requirements page for a feature](img/requirements-feature-overview.png)


### Enhanced Feature Documentation

When you use Serenity with Cucumber, you can turn this feature overview into a rich living document that mixes business rules with examples and scenarios drawn from the acceptance tests. This lets you design a requirements overview that product owners and stakeholders can review quickly and easily, while still keeping the details on hand if they want to know more.

:::caution

Enhanced feature documentation is currently only supported for Cucumber.

:::

For example, we could improve the _Business Activities_ feature overview by embedding the tables (but not the "Given..When..Then" texts which essentially act as text fixtures in this case). To do this, we use the `{Examples}` tag along with the name of the scenario outline that we want to use:

```gherkin
Feature: Business Activities

  Some business activities are considered more risk-prone than others,
  and certain customers and entities may pose specific risks.
  The business activity risk factor for an industry is determined by the potential risk they present to the bank. For example:

  {Examples} The business activity risk factor for an industry
```

When the report is generated, Serenity will include the example table from the _The business activity risk factor for an industry_ scenario in the feature description (see [Feature Overview with Example Tables](#fig-requirements-embedded-table)).

#### Feature Overview with Example Tables {#fig-requirements-embedded-table}
![Example tables from the scenarios can be included in the feature overview](img/requirements-embedded-table.png)

If the tests for this table have been executed, the result for each row will be indicated in the table.

The default form (using the `{Examples}` tag) will take _only_ the examples table from the scenario outline; if you would like the title to be displayed as well, you can use the `{Examples!WithTitle}` tag instead.

Scenarios are generally to granular for the feature summary, and best left for the detailed section further down the page. However sometimes it makes sense to include a scenario or two in the summary. You can do this by using the `{Scenario}` tag. This works for both scenarios and scenario outlines.

## Adding additional evidence

Sometimes the automated test results are not alone enough to satisfy stakeholders or auditors. We need to be able to add some extra proof that our application works as described.

In Serenity, you can add evidence in the form of a String or the contents of a file. For example, you might record the results of a SQL query to demonstrate that a database contains the expected results, or record the full version of a generated XML report when you only make assertions on a few key fields.

You can do this using the `Serenity.recordReportData()` method:

```java
    sqlQueryResult = ...
    Serenity.recordReportData().withTitle("Database evidence").andContents(sqlQueryResult);
```

This method lets you record data from a String or from a file. To get data from a file, use the `fromFile()` method:

```java
    Path report = ...
    Serenity.recordReportData().withTitle("Generated Report").fromFile(report);
```

In both cases, this data is recorded with the test, and appears in the test results:

![Adding evidence to a test result](img/requirements-adding-evidence.png)


## Common Requirements Structures
The exact organisation varies from project to project, but some common structures include:

* Capabilities > Features
* Capabilities > Features > Stories
* Goals > Capabilities > Features
* Epics > Stories
* Themes > Epics > Stories

A two-level requirements hierarchy works well for most projects. A small project (for example, a micro-service) might need only a short list of features. Only very large or complex projects would typically need three or more levels.

### Goals, Capabilities and Features

The aim of any software project is to help our stakeholders achieve their _goals_ by providing them with _capabilities_. In BDD, a _Capability_ is something that allows users to do something that they couldn't do previously, or to do something that they could do previously, but do it more efficiently. A capability is technology-agnostic: it does not commit to a particular solution or implementation. An example of a capability might be the ability to pay online with a credit card.

A _Feature_ is a concrete solution or implementation that delivers a capability. Some possible features that deliver the capability we mentioned earlier might be to pay via PayPal, via Stripe or to pay by integrating with a merchant banking platform.

### Themes and Epics

In Scrum, an _Epic_ is simply a big user story, one that can't be delivered in a sprint. A _Theme_ is just another way to group related User Stories, though many teams use Themes as groups of related epics. (Another way to implement the original idea of themes in Serenity BDD is to use tags).

### User Stories
User Stories are commonly used in Agile as a way to organise work, but they are not always very useful when it comes to Living Documentation. This is because they reflect how a feature was sliced up when it was built. But once a feature is delivered, no one cares how it was broken down during the development phase - all that matters is what was delivered. That's why Cucumber prefers to group scenarios in Feature Files (which describe a feature). For this reason, User Stories are generally considered to be not a great way to structure living documentation. (Note that JBehave still uses the older convention of "Story Files", which were meant to contain the acceptance criteria of a given story).

## Configuring your requirements structure in Serenity BDD

You can configure the way Serenity names the different levels in your own requirements structure using the `serenity.requirements.types` property. For example, if you want to describe your requirements in terms of themes, epics and stories, you would add the following to your Serenity configuration file:

```
serenity.requirements.types=theme,epic,story
```

If you don't configure this parameter, Serenity will decide on a sensible default hierarchy. This hierarchy depends on whether you are using JUnit, Cucumber or JBehave, and on the depth of your requirements hierarchy:


**Test Framework**    | **Default Hierarchy**
--- | --- 
 JUnit             | capability > feature > story
 Cucumber          | theme > capability > feature
 JBehave           | capability > feature > story


:::info

Requirements configuration applies to the container levels, not to the feature or story files themselves. If you are using Cucumber, feature files will **always** be represented as features. If you are using JBehave, story files will **always** be represented as stories.

:::

### Requirements Hierarchies for JUnit Tests

Many teams write automated acceptance tests with Serenity BDD using JUnit. The Screenplay Pattern in particular makes it easy to write highly maintainable tests using a business-readable DSL that produces excellent living documentation.

There are two ways to define the requirements hierarchy for JUnit tests:

#### Package-Based Hierarchy

JUnit acceptance tests can be organised in a package structure that reflects your requirements hierarchy. Note that this means that they may not reflect the package structure in your application, as is usually done for unit and integration tests.

A simple two-level hierarchy is illustrated here:
```
com
└── acme
    └── myapps
        └── specs
            ├── multiple_todo_lists
            ├── sharing_lists
            └── simple_todo_lists
                ├── AddingNewItems.java
                ├── DeletingItems.java
                ├── FilteringItemsByStatus.java
                └── MarkingItemsAsComplete.java
```

You need to tell Serenity where to find the requirements hierarchy in your package structure, using the `serenity.test.root` property. For the example shown above, the root package is `com.acme.myapp.specs`:

```
serenity.test.root=com.acme.myapp.specs
```

In this case, the Serenity living documentation will treat the JUnit test cases ("Adding New Items", "Deleting Items" etc.) as Stories, and the packages directly underneath the `com.acme.myapp.specs` package ("Multiple Todo Lists", "Sharing Lists" etc.) as Features.

#### Annotation-Based Hierarchy

Starting with Serenity 5.3.1, you can also define the requirements hierarchy directly using the `@Epic`, `@Feature`, and `@Story` annotations on your test classes:

```java
@Feature("Managing Todos")
@Story("Complete todo items")
class WhenCompletingTodosTest {
    // ...
}
```

This creates a requirements hierarchy based on the annotation values rather than the package structure. See [Annotation-Based Requirements](/docs/guide/annotation-requirements) for a comprehensive guide with examples.

### Requirements Hierarchies for Cucumber

When you use Cucumber, Serenity expects your feature files to be stored in the `src/test/resources/features` directory. Your requirements hierarchy goes directly underneath this directory:

```
src
└── test
    └── resources
        └── features
            ├── multiple_todo_lists
            ├── sharing_lists
            └── simple_todo_lists
                ├── adding_new_items.feature
                ├── deleting_items.feature
                ├── filtering_items_by_status.feature
                └── marking_items_as_complete.feature
```

When Cucumber is used with the default configuration, the feature files always represent Features, and the directories containing the features represent Capabilities. A Feature is typically bigger than a user story, and can contain the acceptance criteria (scenarios) from several user stories.

### Requirements Hierarchies for JBehave

When you use JBehave, Serenity expects your Story files to be stored in the `src/test/resources/stories` directory. Your requirements hierarchy goes directly underneath this directory:

```
src
└── test
    └── resources
        └── stories
            ├── multiple_todo_lists
            ├── sharing_lists
            └── simple_todo_lists
                ├── adding_new_items.story
                ├── deleting_items.feature
                ├── filtering_items_by_status.story
                └── marking_items_as_complete.story
```

By default the Story files represent stories, and the directories above them are rendered as Features.


---

<!-- https://serenity-bdd.github.io/docs/reporting/filtering_reports -->

Serenity BDD makes it easy to get both a broad overview of your test results and functional coverage.
But when working with large test suites, it is often useful to be able to focus on specific functional areas of the application when reporting results.
For example, you may want to view only the results for the tests related to the current release, or to a specific functional area.

In Serenity BDD, you can use tags to generate this kind of focused report.

This works very naturally with Cucumber test scenarios. For example, in the following feature file, we have used the `@sprint-2` tag to indicate that the scenario is scheduled for Sprint 2.

```gherkin
@sprint-2
Scenario: Buyer orders a coffee
  Given Cathy has a Caffeinate-Me account
  When she orders a large cappuccino
  Then Cathy should receive the order
```

Tagging also works with JUnit 5 tests, as illustrated here:

```java
@ExtendWith(SerenityJUnit5Extension.class)
class WhenAddingNumbers {

    @Steps
    MathWizSteps michael;

    @Test
    @WithTag("release:sprint-2")
    void addingSums() {
        // Given
        michael.startsWith(1);

        // When
        michael.adds(2);

        // Then
        michael.shouldHave(3);
    }

    @Test
    @WithTagsValuesOf({"Reporting", "release:sprint-3"})
    void testWithMultipleTags() {
    }
}
```

:::note JUnit 4 Deprecated
If you're using JUnit 4 with `@RunWith(SerenityRunner.class)`, note that JUnit 4 support is deprecated as of Serenity 5.0.0 and will be removed in Serenity 6.0.0. Please migrate to JUnit 5.
:::

## Running Scenarios by tags

Tags are also a great way to help organize test execution.
For example, you might want to flag all of the web services tests, or mark certain tests to run against Internet Explorer browser only.
With JUnit tests, this can be achieved by providing a single tag or an "or" separated list of tags from command line.
If provided, only classes and/or methods with tags in this list will be executed.

```bash
mvn clean verify -Dtags="feature:Reporting or release:sprint-2"
mvn clean verify -Dtags="feature:Reporting or release:sprint-2"
```

When using Cucumber, we need to use the `cucumber.options` property to indicate which scenarios should be executed. For example, the following command runs all of the Cucumber scenarios with the `@sprint-2` tag":

```bash
mvn clean verify -Dcucumber.options="--tags=@sprint-2"
```

## Excluding Unrelated Requirements

By default, when you use the `tags` option, Serenity will filter your requirements as best it can to report only the requirements that are relevant to the specified tag.

Requirements filtering only happens if you specify the `tags` option. So this will produce a full set of requirements in the *Requirements* page.

```bash
mvn clean verify -Dcucumber.options="--tags @sprint-2"
```

But this will report only the requirements that are related to the executed tests.

```bash
mvn clean verify -Dcucumber.options="--tags @sprint-2" -Dtags=sprint-2
```

If you have already run the full set of tests, you can also produce a filtered aggregate report, in which case you don't need to provide the `cucumber.options` property:

```bash
mvn serenity:aggregate -Dtags=sprint-2
```

## Using tags with Cucumber and JUnit 5

When running Cucumber tests with JUnit 5, you can use the `FILTER_TAGS_PROPERTY_NAME` configuration property to manage the tags for a specific test runner:

```java
@ConfigurationParameter(key = FILTER_TAGS_PROPERTY_NAME, value = "@smoke-test and @filtering")
public class CucumberTestSuite {
}
```

Alternatively, from the command line, you can use the `tags` command line property as shown here (note that with Cucumber 7, you don't need the '@' symbol for the tags when specifying tags on the command line):

```
mvn clean verify -Dtags="smoke-test or filtering"
```


---

<!-- https://serenity-bdd.github.io/docs/reporting/additional_reports -->

In addition to the standard HTML reports, Serenity provides additional reports for more specific usages. These include

  * Emailable HTML reports
  * Html report as single page react application

## Serenity emailable reports

Serenity BDD produces rich reports that act both as test reports and living documentation.
But often it is useful to be able to send a short summary of the test outcomes via email.

Serenity allows you to generate a single-page, self-contained HTML summary report, containing
an overview of the test results, and a configurable breakdown of the status of different areas of the application. You can see a sample of such a report here:

![A summary report generated by Serenity](img/test-summary-report.png)


## Setting up Maven

These reports are configured in the Serenity Maven plugin, where you need to do two things. First, you need to add a dependency for the `serenity-emailer` module in the plugin configuration. Then, you need to tell Serenity to generate the `email` report when it performs the aggregation task.

The full configuration looks something like this:

```xml
<plugin>
    <groupId>net.serenity-bdd.maven.plugins</groupId>
    <artifactId>serenity-maven-plugin</artifactId>
    <version>${serenity.version}</version>
    <dependencies>
        <dependency> 
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-single-page-report</artifactId>
            <version>${serenity.version}</version>
        </dependency>
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-navigator-report</artifactId>
            <version>${serenity.version}</version>
        </dependency>
    </dependencies>
    <configuration>
        <tags>${tags}</tags>
        <reports>single-page-html,navigator</reports>
    </configuration>
    <executions>
        <execution>
            <id>serenity-reports</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```
In the above snippet,
1. The `<dependency>` tags above list the dependencies on different report modules.
2. The `<reports>` tag in the `<configuration>` specifies the list of reports to generate.

If you are using Maven, you can also generate these reports directly using the `reports` goal and by passing the `serenity.reports` system property:

```bash
mvn serenity:reports -Dserenity.reports=single-page-html
```

## Setting up Gradle

If you are using Gradle, you can use the `reports` task to generate any configured extended reports. First of all, you need to add the dependencies to the extended reports you want to run in the `buildscript` section of your `build.gradle` file, e.g.

```gradle
buildscript {
    repositories {
        mavenLocal()
        jcenter()
    }
    dependencies {
        classpath "net.serenity-bdd:serenity-gradle-plugin:2.1.4"
        classpath "net.serenity-bdd:serenity-single-page-report:2.1.4"
    }
}
```

Next, you need to configure the report you want to generate in your `build.gradle` file using the `serenity` section, as shown here:

```gradle
serenity {
    reports = ["single-page-html"]
}
```

Now you can generate these reports by invoking the `reports` task:

```bash
gradle reports

> Task :reports
Generating Serenity Reports for bdd-bank to directory /Users/john/Projects/SerenityDojo/bdd-bank/target/site/serenity
PROCESSING EXTENDED REPORTS: [email]

BUILD SUCCESSFUL in 2s
1 actionable task: 1 executed
```

## Functional Coverage Reporting

The _Functional Coverage_ section lets you highlight key areas of your application.
By default, this section will list test results for each _Feature_. But you can configure the report to group results by other tags as well.

You can specify what categories should appear on this page using the `report.tagtypes` system property. For example, if want to list capabilities as well as features, you would add the following line to your `serenity.properties` file:

```
report.tagtypes=capability,feature
```

Now both capabilities and features would appear in the Functional Coverage section of the report:

![Customising the categories to appear in the Functional Coverage section](img/custom-reports-capabilities-and-features.png)

### Functional coverage by tag
You can also configure functional coverage to report coverage by tags, rather than by requirements hierarchy. Suppose you are using a `@department` tag to define the key stakeholders for each feature. You could flag features to belong to different departments using tags like `@department:Trading`, `department:Sales` or `department:Marketing`.

```gherkin
@department:Trading
Feature: Buying and selling shares

  In order to make my investments grow
  As a trader
  I want to be able to buy and sell shares to make a profit
  ...
```

You could tell Serenity to produce coverage for these tags by including the following line in your `serenity.properties` file:

```
report.tagtypes=department
```

When you generate the summary report, the results will be aggregated by each tag value (Marketing, Sales and Trading), as shown here:

![Functional coverage can be configured by tags](img/custom-reports-alternative-functional-coverage.png)

### Deep links

You can include a link back to your Serenity report, and links to the individual scenario results,
by setting the `serenity.report.url` property. You can do this in the `serenity.properties` file (if it is fixed),
or pass it in from the command line (if you are pointing the the reports for a specific build, for example):

```
serenity.report.url=http://my.jenkins.server:8080/job/my-project/serenity-reports/
```


---

<!-- https://serenity-bdd.github.io/docs/reporting/reports_custom_info -->

## Custom Field Reporting

Custom fields can be included in the reports, using values that are either taken from the environment variables or passed into the build via system properties. This can be useful if you want to include the product or build version, the environment the tests were run on, or the test run date.

You can add custom fields to your report by setting system properties with the special prefix `report.customfields`. These can go in your `serenity.properties` file in the root directory of your project, or you can pass them in as command-line options.

For example, you could add the following properties to your `serenity.properties` file.
```
report.customfields.environment = Integration
report.customfields.ApplicationVersion = 1.2.3
```

This would produce a report containing these values, as shown here:

![Custom fields appearing in the HTML summary report](img/custom-report-fields.png)

### Accessing system variables
We can also access any system variables that Java has access to. For example, we could include the name of the user who ran the test run with the `${USER}` system variable:

```
report.customfields.user = ${USER}
```

This property would result in a report like the following:

![Custom fields can also include system variables](img/custom-reports-including-a-system-variable.png)

Not all system properties are available to Java. For example, on Linux systems, the `$HOST` variable gives the name of the local machine. We could include this in our report by adding the following property:

```
report.customfields.host = ${HOST}
```

However, since this variable is not available to Java, we would need to pass it to Serenity from the command line, like this:

```bash
mvn serenity:aggregate -DHOST=$HOST
```

### Overriding property values

[[custom-report-fields-with-provided-values]]
.You can pass system properties from the command line
image::custom-reports-with-provided-property.png[]

You can of course pass in other properties, to override the ones in your `serenity.properties` file. Here we override the application version:

```bash
mvn serenity:aggregate -DHOST=$HOST -Dreport.customfields.ApplicationVersion=1.2.4
```
But a more elegant solution, if you know you will always be passing in a variable, is to use a shorter variable in your `serenity.properties` file and then pass this one in. For example, here we use the `environment` property to display the current environment in the custom properties:

```
report.customfields.environment = ${environment}
```

We can set this value from the command line as shown here:

```bash
mvn serenity:aggregate -DHOST=$HOST -Denvironment=INT5
```

#### Using default values
If an environment variable doesn't exist, you can have specify a fallback value.

```
report.customfields.user = ${USER:-Unknown}
report.customfields.host = ${HOST:-} # Blank instead of the literal characters "${HOST}"
```
The mechanism behind the substitution: [Apache Commons `StringSubstitutor`](https://commons.apache.org/proper/commons-text/apidocs/org/apache/commons/text/StringSubstitutor.html)

### Ordering the custom properties

By default, the fields will appear in an arbitrary order. You can force the fields to appear in a pre-determined order using the `report.customfields.order` field:

```
report.customfields.order=ApplicationVersion,environment,user,host
```

### A complete example
A complete example of these properties and their various usages is shown here:

```
report.customfields.ApplicationVersion = 1.2.3
report.customfields.environment = ${environment}
report.customfields.user = ${USER}
report.customfields.host = ${HOST}
report.customfields.order=ApplicationVersion,environment,user,host
```

## Custom Build Info

You can also add your own fields the the Build Info screen, using the `sysinfo.*` properties.
The `sysinfo.*` properties let you define fields and values that will appear in the Build Info page. For simple field-value combinations, the field appears alongside the other values on the Build Info screen:

```
sysinfo.lead = Daisy
```

You can use Groovy expressions to access system properties (that you can pass in from the command line). The `env` property gives you access to the current environment variables. For example, to display the current Jenkins build number, you could include the following line:

```
sysinfo.build = "${env.BUILD_NUMBER}"
```

You can also group custom properties into sections with sub-titles. An example of such a configuration in the `serenity.conf` file is shown below:

```
sysinfo {
  lead = Daisy
  build = "${env.BUILD_NUMBER}"
  Test Run {
    Run By = "${env.USER}"
    Java Version = "${java.version}"
  }
}
```

The corresponding Build Info screen is shown below:

![Customised Build Info details](img/build-info.png)

## Defining build info programmatically

You can also use the `BuildInfo` class to add information to the Build Info page programmatically. Simply define the section, and add as many property name/value pairs as you want. You can see an example here:

```java
BuildInfo.section("Toggles").setProperty("toggle-custom-ads-v2", "on");
BuildInfo.section("Toggles").setProperty("toggle-user-feedback", "on");

BuildInfo.section("Versions").setProperty("game-history-service", "1.2.3");
BuildInfo.section("Versions").setProperty("player-service", "3.4.5");
BuildInfo.section("Versions").setProperty("related-products-service", "2.3.4");
```

![Customised Build Info details](img/custom-build-info.png)


---

<!-- https://serenity-bdd.github.io/docs/reporting/integrating_with_jira -->

# Integrating with JIRA

With Selenium BDD it is possible to create tight one and two-way integration with JIRA

### One way integration with JIRA

[JIRA](https://www.atlassian.com/software/jira) is popular issue-tracking system that is also often used for Agile projects and requirements management. Many teams using JIRA store their requirements electronically in the form of story cards and epics in JIRA

Suppose we are implementing a Frequent Flyer application for an airline. The idea is that travelers will earn points when they fly with our airline, based on the distance they fly. Travelers start out with a “Bronze” status, and can earn a better status by flying more frequently. Travelers with a higher frequent flyer status benefit from advantages such as lounge access, prioritized boarding, and so on. One of the story cards for this feature might look like the following:

![](img/frequent-flyer-story-card.png)

This story contains a description following one of the frequently-used formats for user story descriptions (“as a..I want..so that”). It also contains a custom “Acceptance Criteria” field, where we can write down a brief outline of the “definition of done” for this story.

These stories can be grouped into epics, and placed into sprints for project planning, as illustrated in the JIRA Agile board shown here:

![](img/jira-agile-board.png)

As illustrated in the story card, each of these stories has a set of acceptance criteria, which we can build into more detailed scenarios, based on concrete examples. We can then automate these scenarios using a BDD tool like JBehave.

The story in the frequent flyer storycard describes how many points members need to earn to be awarded each status level. A JBehave scenario for the story card illustrated earlier might look like this:

```
Frequent Flyer status is calculated based on points

Meta:
@issue #FH-17

Scenario: New members should start out as Bronze members
Given Jill Smith is not a Frequent Flyer member
When she registers on the Frequent Flyer program
Then she should have a status of Bronze

Scenario: Members should get status updates based on status points earned
Given a member has a status of <initialStatus>
And he has <initialStatusPoints> status points
When he earns <extraPoints> extra status points
Then he should have a status of <finalStatus>

Examples:
| initialStatus | initialStatusPoints | extraPoints | finalStatus | notes                    |
| Bronze        | 0                   | 300         | Silver      | 300 points for Silver    |
| Silver        | 0                   | 700         | Gold        | 700 points for Gold      |
| Gold          | 0                   | 1500        | Platinum    | 1500 points for Platinum |
```

Serenity lets you associate JBehave stories or JUnit tests with a JIRA card using the @issue meta tag (illustrated above), or the equivalent @Issue annotation in JUnit. At the most basic level, this will generate links back to the corresponding JIRA cards in your test reports, as illustrated here:

![jira-serenity-report](img/jira-serenity-report.png)

For this to work, Serenity needs to know where your JIRA server. The simplest way to do this is to define the following properties in a file called serenity.properties in your project root directory:

```
jira.url=https://myserver.atlassian.net
jira.project=FH
jira.username=jirauser
jira.password=t0psecret
```

You can also set these properties up in your Maven pom.xml file or pass them in as system properties.

#### Feature Coverage
But test results only report part of the picture. If you are using JIRA to store your stories and epics, you can use these to keep track of progress. But how do you know what automated acceptance tests have been implemented for your stories and epics, and, equally importantly, how do you know which stories or epics have no automated acceptance tests? In agile terms, a story cannot be declared “done” until the automated acceptance tests pass. Furthermore, we need to be confident not only that the tests exist, but that they test the right requirements, and that they test them sufficiently well.

We call this idea of measuring the number (and quality) of the acceptance tests for each of the features we want to build “feature coverage”. Serenity can provide feature coverage reporting in addition to the more conventional test results. If you are using JIRA, you will need to add serenity-jira-requirements-provider to the dependencies section of your pom.xml file:
```
<dependencies>
    ...
    <dependency>
        <groupId>net.serenity.plugins.jira</groupId>
        <artifactId>serenity-jira-requirements-provider</artifactId>
        <version>xxx</version>
    </dependency>
</dependencies>
```
The actual version number might be different for you – always take a look at [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cthucydides) to know what the latest version is.

You will also need to add this dependency to the Serenity reporting plugin configuration:

```
<build>
    ...
    <plugins>
        ...
        <plugin>
            <groupId>net.serenity.maven.plugins</groupId>
            <artifactId>maven-serenity-plugin</artifactId>
            <version>xxx</version>
            <executions>
                <execution>
                    <id>serenity-reports</id>
                    <phase>post-integration-test</phase>
                    <goals>
                        <goal>aggregate</goal>
                    </goals>
                </execution>
            </executions>
            <dependencies>
                <dependency>
                    <groupId>net.serenity.plugins.jira</groupId>
                    <artifactId>serenity-jira-requirements-provider</artifactId>
                    <version>xxx</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
```

Now, when you run the tests, Serenity will query JIRA to determine the epics and stories that you have defined and list them on the Requirements page. This page gives you an overview of how many requirements (epics and stories) have passing tests (green), how many have failing (red) or broken (orange) tests, and how many have no tests at all (blue):

![serenity-jira-requirements-view](img/serenity-jira-requirements-view.png)

If you click on an epic, you can see the stories defined for the epic, including an indicator (in the “Coverage” column) of how well each story has been tested.

![serenity-jira-report-epic-details]( img/serenity-jira-report-epic-details.png "Epic details in Serenity report")

From here, you may want to drill down into the details about a given story, including what acceptance tests have been defined for this story, and whether they ran successfully:

![serenity-jira-story-report](img/serenity-jira-story-report.png)
Both JIRA and the JIRA-Serenity integration are quite flexible. We saw earlier that we had configured a custom “Acceptance Criteria” field in our JIRA stories. We have displayed this custom field in the report shown above by including it in the serenity.properties file, like this:

```
jira.custom.field.1=Acceptance Criteria
```

Serenity reads the narrative text appearing in this report (“As a frequent flyer…”) from the Description field of the corresponding JIRA card. We can override this behavior and get Serenity to read this value from a different custom field using the `jira.custom.narrative.field` property. For example, some teams use a custom field called “User Story” to store the narrative text, instead of the Description field. We could get Serenity to use this field as follows:

```
jira.custom.narrative.field=User Story
```

### Two way integration with JIRA

#### Links from JIRA to Serenity
The simplest form of two-way integration between Serenity and JIRA is to get Serenity to insert a comment containing links to the Serenity test reports for each related issue card. To get this to work, you need to tell Serenity where the reports live. One way to do this is to add a property called serenity.public.url to your serenity.properties file with the address of the serenity reports.

```
serenity.public.url=http://buildserver.myorg.com/latest/serenity/report
```

This will tell Serenity that you not only want links from the Serenity reports to JIRA, but you also want to include links in the JIRA cards back to the corresponding Serenity reports. When this property is defined, Serenity will add a comment like the following to any issues associated with the executed tests:

![jira-serenity-comment](img/jira-serenity-comment.png)

The `serenity.public.url` will typically point to a local web server where you deploy your reports, or to a path within your CI server. For example, you could publish the Serenity reports on Jenkins using the [Jenkins HTML Publisher Plugin](https://wiki.jenkins-ci.org/display/JENKINS/HTML+Publisher+Plugin), and then add a line like the following to your serenity.properties file:

```
serenity.public.url=http://jenkins.myorg.com/job/myproject-acceptance-tests/Serenity_Report/
```

If you do not want Serenity to update the JIRA issues for a particular run (e.g. when running your tests locally), you can also set `serenity.skip.jira.updates` to true, e.g.

```
serenity.skip.jira.updates=true
```

This will simply write the relevant issue numbers to the log rather than trying to connect to JIRA.

#### Updating JIRA issue states

You can also configure the plugin to update the status of JIRA issues. This is deactivated by default: to use this option, you need to set the `serenity.jira.workflow.active` option to true, e.g.

```
serenity.jira.workflow.active=true
```

The default configuration will work with the default JIRA workflow: open or in progress issues associated with successful tests will be resolved, and closed or resolved issues associated with failing tests will be reopened. If you are using a customized workflow, or want to modify the way the transitions work, you can write your own workflow configuration. Workflow configuration uses a simple Groovy DSL. The following is an example of the configuration file used for the default workflow:

```
when 'Open', {
    'success' should: 'Resolve Issue'
}

when 'Reopened', {
    'success' should: 'Resolve Issue'
}

when 'Resolved', {
    'failure' should: 'Reopen Issue'
}

when 'In Progress', {
    'success' should: ['Stop Progress','Resolve Issue']
}

when 'Closed', {
    'failure' should: 'Reopen Issue'
}
```

You can write your own configuration file and place it on the classpath of your test project (e.g. in serenity's directory). Then you can override the default configuration by using `serenity.jira.workflow` property, e.g.

```
serenity.jira.workflow=my-workflow.groovy
```

Alternatively, you can simply create a file called jira-workflow.groovy and place it somewhere on your classpath (e.g. in the src/test/resources directory). Serenity will then use this workflow. In both these cases, you don’t need to explicitly set the `serenity.jira.workflow.active` property.

#### Release management

In JIRA, you can organize your project releases into versions, as illustrated here:

![jira-versions](img/jira-versions.png)

You can and assign cards to one or more versions using the `Fix Version/s` field:

![jira-fix-versions](img/jira-fix-versions.png)

By default, Serenity will read version details from the Releases in JIRA. Test outcomes will be associated with a particular version using the “Fixed versions” field. The *Releases* tab gives you a run-down of the different planned versions, and how well they have been tested so far:

![releases-tab](img/releases-tab.png)

JIRA uses a flat version structure – you can’t have for example releases that are made up of a number of sprints. Serenity lets you organize these in a hierarchical structure based on a simple naming convention. By default, Serenity uses “release” as the highest level release, and either “iteration” or “sprint” as the second level. For example, suppose you have the following list of versions in JIRA – Release 1 – Iteration 1.1 – Iteration 1.2 – Release 2 – Release 3

This will produce Release reports for Release 1, Release 2, and Release 3, with Iteration 1.2 and Iteration 1.2 appearing underneath Release 1. The reports will contain the list of requirements and test outcomes associated with each release. You can drill down into any of the releases to see details about that particular release.

![serenity-jira-releases](img/serenity-jira-releases.png)

You can also customize the names of the types of releases using the serenity.release.types property, e.g.

```
serenity.release.types=milestone, release, version
```


---

<!-- https://serenity-bdd.github.io/docs/cloud/selenium-grid -->

# Introduction

[Selenium Grid](https://www.selenium.dev/documentation/grid/) allows the execution of WebDriver scripts on remote machines (virtual or real) by routing commands sent by the client to remote browser instances. It aims to provide an easy way to run tests in parallel on multiple machines.

Selenium Grid 4 takes advantage of a number of new technologies in order to facilitate scaling up while allowing local execution.

You can also use Serenity to run your WebDriver tests on a remote machine, such as a Selenium Grid or a remote service such as provided by [BrowserStack](https://www.browserstack.com/automate?utm_source=serenity&utm_medium=partnered) or [LambdaTest](https://www.lambdatest.com?utm_source=serenity_bdd&utm_medium=website). This allows you to run your web tests against a variety of different browsers and operating systems, and also benefit from faster test execution when running the tests in parallel. We will look at how to do this in detail later on in the chapter.

## Running Selenium Grid locally
The simplest way to start with Selenium Grid is to run a standalone instance on your local machine. This allows you to make sure your Serenity configuration has been correctly set up to use the Selenim grid.

To try this own, download the latest `selenium-server` jar file from [the Selenium website](https://www.selenium.dev/downloads/). Then start up the server with the following command:

```
java -jar selenium-server-<version>.jar standalone
```

This will start up the local instance of the Selenium Grid server. You can check out the dashboard on [http://localhost:4444/ui](http://localhost:4444/ui).

You can configure your tests to run against this server by setting three properties:
 - Set the `webdriver.driver` property to `remote`
 - Set the `webdriver.remote.url` property to the address of your Selenium Grid instance (http://localhost:4444 by default)
 - Set the `webdriver.remote.driver` property to the name of the driver you want to run (e.g. "chrome")

```conf
webdriver {
  driver = remote
  remote {
    url="http://localhost:4444"
    driver=chrome
  }
 }
```

You can also provide additional properties about the target browser or environment, including:
- `webdriver.remote.browser.version`: What version of the remote browser to use
- `webdriver.remote.os`: What operating system the tests should be run on.

For example, if you were running a Selenium Hub locally on port 4444 (the default) on a Windows machine, you could run the following command:

```
mvn verify -Dwebdriver.remote.url=http://localhost:4444/wd/hub -Dwebdriver.remote.driver=chrome -Dwebdriver.remote.os=WINDOWS
```

You can also pass the usual driver-specific capabilities to the remote browser, e.g.
```
mvn verify -Dwebdriver.remote.url=http://localhost:4444/wd/hub -Dwebdriver.remote.driver=chrome -Dwebdriver.remote.os=WINDOWS -Dchrome.switches="--no-sandbox,--ignore-certificate-errors,--homepage=about:blank,--no-first-run"
```


---

<!-- https://serenity-bdd.github.io/docs/cloud/selenoid -->

# Introduction

[Selenoid](https://aerokube.com/selenoid/latest/) Selenoid is a powerful Golang implementation of original Selenium hub code. It is using Docker to launch browsers. Please refer to GitHub repository if you need source code.

The simplest way to configure the driver you want to use is in your project's `serenity.conf` file (which you will find in `src/test/resources` folder).
Refer to [Driver Config](https://serenity-bdd.github.io/docs/guide/driver_config)

You can configure your tests to run against this server by setting two properties:

 - Set the `webdriver.driver` property to `remote` 
 - Set the `webdriver.remote.url` property to the address of your selenoid instance (http://localhost:4444/wd/hub by default)

```conf
webdriver {
  driver = remote
  remote.url = "http://localhost:4444/wd/hub"
  }
 }
```

You can also provide additional properties about the target browser or environment, including:
- `browserName`:  property to the name of the driver you want to run (e.g. "chrome")
- `browserVersion`: What version of the remote browser to use (e.g. "93")

``` conf

webdriver {
  driver = remote
  remote.url = "http://localhost:4444/wd/hub"
  capabilities {
    browserName = "chrome"
    browserVersion = "93"
  }
}

```

If you use serenity.properties:
```properties

webdriver.driver = remote
webdriver.remote.url = http://localhost:4444/wd/hub
webdriver.capabilities.browserVersion=93.0
webdriver.capabilities.browserName=chrome

```

Example with multiple environments for Selenoid and Local browser:
``` conf
serenity {
  project.name = "Project with Remote(selenoid) and Local browsers"
  console.colors = true
  logging = VERBOSE
  take.screenshots = AFTER_EACH_STEP
}

environment = selenoid

environments {
  selenoid {
    webdriver {
      driver = remote
      remote.url = "http://localhost:4444/wd/hub"
      capabilities {
        browserName = "chrome"
        browserVersion = "118.0"
        "selenoid:options" {
            enableVNC = true
            enableVideo = false
            sessionTimeout = 10m
            timeZone = America/Los_Angeles
          }
        "goog:chromeOptions" {
            args = ["--remote-allow-origins=*", "disable-gpu", "disable-setuid-sandbox", "disable-dev-shm-usage"]
            prefs {
              profile.profile_default_content_settings.popups = 0
              profile.default_content_setting_values.notifications = 1
             }
          }
        timeouts {
           #script = 30000
           #pageLoad = 300000
           implicit = 5000
         }
      }
    }
  }
  local {
    webdriver {
      driver = chrome
      capabilities {
        "goog:chromeOptions" {
            args = ["--remote-allow-origins=*", "disable-gpu", "disable-setuid-sandbox", "disable-dev-shm-usage"]
            prefs {
              profile.profile_default_content_settings.popups = 0
              profile.default_content_setting_values.notifications = 1
             }
          }
        timeouts {
           #script = 30000
           #pageLoad = 300000
           implicit = 5000
         }
      }
    }
  }
}

```

You can run tests on specific environment via comman line.
`mvn clean verify -Denvironment=selenoid`


---

<!-- https://serenity-bdd.github.io/docs/cloud/lambdatest -->

# Serenity BDD LambdaTest Integration

LambdaTest is a cloud platform for test execution and test orchestration. With LambdaTest, Serenity users can extend their automation test coverage of their web and mobile apps on 3000+ real devices, browsers, and operating systems.

The `serenity-lambdatest` plugin provides seamless integration with the [LambdaTest](https://www.lambdatest.com?utm_source=serenity_bdd&utm_medium=website) online test automation platform. 

## Adding the LambdaTest plugin

To add the integrated support for LambdaTest to your project, you will need to add the `serenity-lambdatest` dependency to your project dependencies. For Maven, you would add the following:
```xml
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-lambdatest</artifactId>
        <version>${serenity.version}</version>
    </dependency>
```

And for Gradle:
```groovy
    testImplementation "net.serenity-bdd:serenity-lambdatest:${serenityVersion}"
```

## Specifying your LambdaTest credentials and grid URL
Next, you will need a [LambdaTest account](https://accounts.lambdatest.com/register?utm_source=serenity_bdd&utm_medium=sponsor&utm_campaign=serenity_bdd&utm_term=sk&utm_content=homepage) (If you don't already have one you can set up a free lifetime account to experiment). 

You can add your [LambdaTest credentials](https://www.lambdatest.com/support/docs/using-environment-variables-for-authentication-credentials?utm_source=serenity_bdd&utm_medium=sponsor&utm_campaign=serenity_bdd&utm_term=sk&utm_content=homepage) in two ways. The simplest is to define the following system properties:
* `LT_USERNAME` - LambdaTest user name
* `LT_ACCESS_KEY`- LambdaTest access key

Alternatively, you can define your username and accesskey using the `lt.user` and `lt.key` properties respectively in your `serenity.conf` file:

```hocon
lt.user=myuser
lt.key=XXXXXXXX
```

By default the standard LambdaTest grid URL ("hub.lambdatest.com") will be used to connect to the LambdaTest servers, but you can override this by setting the `lt.grid` property:

```hocon
lt.grid = "mycustomhub.lambdatest.com"
```

## Configuring the LambdaTest driver

Serenity interacts with LambdaTest via the `RemoteDriver` driver. You can specify the remote URL explicitly, or let the `serenity-lambdatest` library do it for you. For example, to configure the URL explicitly you could use a `serenity.conf` configuration like this:
```hocon
webdriver {
  driver = remote
  remote.url = "https://"${LT_USERNAME}":"${LT_ACCESS_KEY}"@hub.lambdatest.com/wd/hub"
}
```

If the `webdriver.remote.url` property is not defined, Serenity will use these values to build one for you if the LambdaTest plugin is active (see below).

## Activating the LambdaTest plugin

The Serenity LambdaTest plugin will be invoked if Serenity can find a `"LT:Options"` section in your `serenity.conf` file, or if you specify a `remote.webdriver.url` that points to a LambdaTest server. If you have no LambdaTest-specific capabilities, simply set the `lambdatest.active` property to true like this:

```hocon
lambdatest {
  active = true
}
```

## Defining LambdaTest Capabilities

You can specify the operating system and browser you want to run your tests on by customising the [Selenium Capabilities](https://www.lambdatest.com/support/docs/selenium-automation-capabilities?utm_source=serenity_bdd&utm_medium=sponsor&utm_campaign=serenity_bdd&utm_term=sk&utm_content=homepage) in your `serenity.conf` file. You do this in the `"LT:Options"` section of the `serenity.conf` file, e.g.

```hocon
    webdriver {
      driver = "remote"
      capabilities {
        browserName = "chrome"
        version = "104.0"
        platform = "Windows 10"
        #
        # Any LambdaTest-specific options go in the 'LT:Options' section
        #
        "LT:Options" {
          resolution", "1280x800"
          network = true // To enable network logs
          visual = true // To enable step by step screenshot
          video = true // To enable video recording
          console = true // To capture console logs
        }
      }
    }
```

Note that the `w3c` option will be set to `true` by default, as this is the default protocol for the Selenium version integrated with Serenity.

The LambdaTest test name will be assigned automatically. You can also set the _build_ name by assigning the `lambdatest.build` property.
For example the following example shows how to create a build name from the Jenkins job name and build number environment variables:

```hocon
lambdatest {
  build = "${JOB_NAME} - build ${BUILD_NUMBER}"
}
```

These properties will be placed in the `LT:Options` capability.

:::tip

LambdaTest provides a convenient [Capabilities Generator](https://www.lambdatest.com/capabilities-generator?utm_source=serenity_bdd&utm_medium=sponsor&utm_campaign=serenity_bdd&utm_term=sk&utm_content=homepage) that gives an idea of what options are available.

:::


---

<!-- https://serenity-bdd.github.io/docs/cloud/browserstack -->

# Introduction

[Browserstack](https://www.browserstack.com/automate?utm_source=serenity&utm_medium=partnered) is an online platform that allows you to run cross-browser tests in parallel at scale. In this section, we will see how it integrates with Serenity.

## Adding the Browserstack plugin to your project

Serenity comes with a dedicated BrowserStack plugin that makes it much easier to run your tests on this platform. To use it, first add the `serenity-browserstack` dependency to your project. In Maven, that would look like the following:
```xml
        <dependency>
            <groupId>net.serenity-bdd</groupId>
            <artifactId>serenity-browserstack</artifactId>
            <version>${serenity.version}</version>
        </dependency>
```

Or in Gradle:
```groovy
    testImplementation "net.serenity-bdd:serenity-browserstack:${serenityVersion}"
```

## Specifying your BrowserStack credentials and grid URL
Next, you will need a [BrowserStack account](https://www.browserstack.com/pricing).

You can add your [BrowserStack credentials](https://www.browserstack.com/accounts/settings) in two ways. The simplest is to define the following system properties:
* `BROWSERSTACK_USER` - BrowserStack user name
* `BROWSERSTACK_KEY`- BrowserStack access key

Alternatively, you can define your username and accesskey using the `browserstack.user` and `browserstack.key` properties respectively in your `serenity.conf` file:

```hocon
browserstack.user=myuser
browserstack.key=XXXXXXXX
```

## Configuring the BrowserStack driver
Serenity interacts with BrowserStack via the `RemoteDriver` driver. You can specify the remote URL explicitly, or let the `serenity-browserstack` library do it for you. For example, to configure the URL explicitly you could use a `serenity.conf` configuration like this:
```hocon
webdriver {
  driver = remote
  remote.url =
  "https://"${BROWSERSTACK_USER}":"${BROWSERSTACK_KEY}"@hub.browserstack.com/wd/hub"
}
```

If the `webdriver.remote.url` property is not defined, Serenity will use these values to build one for you if the BrowserStack plugin is active (see below).

## Defining BrowserStack Capabilities
You can specify the operating system and browser you want to run your tests on by customising the [Selenium Capabilities](https://www.browserstack.com/automate/capabilities) in your `serenity.conf` file. You do this in the `"bstack:options"` section of the `serenity.conf` file, e.g.

```hocon
webdriver {
  driver = "remote"
  capabilities {
    browserName = "Chrome"
    #
    # Any BrowserStack-specific options go in the 'bstack:options' section
    #
    "bstack:options" {
      os = "Windows"
      osVersion = "11"
      browserVersion = "latest"
      local = false
      resolution = "1920x1200"
      seleniumVersion = "4.6.0"
      video = true
      idleTimeout = 300 // Make sure to set this to a high number if running tests in parallel
    }
  }
}
```

If you're running the tests in parallel, make sure to set the idleTimeout value to a high number (longer than the total duration of your tests). This will prevent the BrowserStack connection from timing out before it's updated with the test results.


---

<!-- https://serenity-bdd.github.io/docs/cloud/saucelabs -->

# Serenity BDD SauceLabs Integration

The `serenity-saucelabs` plugin provides seamless integration with the [SauceLabs](https://saucelabs.com/) online test automation platform. 

## Adding the SauceLabs plugin

To add the integrated support for SauceLabs to your project, you will need to add the `serenity-saucelabs` dependency to your project dependencies. For Maven, you would add the following:
```xml
    <dependency>
        <groupId>net.serenity-bdd</groupId>
        <artifactId>serenity-saucelabs</artifactId>
        <version>${serenity.version}</version>
    </dependency>
```

And for Gradle:
```groovy
    testImplementation "net.serenity-bdd:serenity-saucelabs:${serenityVersion}"
```

## Specifying your SauceLabs credentials and grid URL
Next, you will need a [SauceLabs account](https://saucelabs.com/pricing). 

Next you will need to configure your SauceLabs credentials (if you are logged on to the Saucelabs Dashboard [you can find these on this page]. The simplest way to do this is to define the following system properties:
* `SAUCE_USERNAME`- SauceLabs user name
* `SAUCE_ACCESS_KEY` - SauceLabs access key

Alternatively, you can define your username and accesskey using the `sauce.username` and `sauce.key` properties respectively in your `serenity.conf` file:

```hocon
sauce.username=myuser
sauce.key=XXXXXXXX
```

## Configuring the SauceLabs driver

Serenity interacts with SauceLabs via the `RemoteDriver` driver. You will need to specify the remote URL for the geographical region you want to use in the `webdriver.remote.url` property, like this:
```hocon
webdriver {
  driver = remote
  remote.url = "https://ondemand.us-west-1.saucelabs.com/wd/hub"
}
```

## Activating the SauceLabs plugin

The Serenity SauceLabs plugin will be invoked if Serenity can find a `"sauce:options"` section in your `serenity.conf` file, or if you specify a `remote.webdriver.url` that points to a SauceLabs server. If you have no Saucelabs-specific capabilities, simply set the `sauce.active` property to true like this:

```hocon
sauce {
  active = true
}
```

## Defining Saucelabs Capabilities

You can specify the operating system and browser you want to run your tests on by customising the [Selenium Capabilities](https://docs.saucelabs.com/dev/test-configuration-options/#desktop-and-mobile-capabilities-sauce-specific--optional) in your `serenity.conf` file. You do this in the `"sauce:options"` section of the `serenity.conf` file, e.g.

```hocon
    webdriver {
      driver = "remote"
      capabilities {
        browserName = "chrome"
        version = "104.0"
        platform = "Windows 10"
        "sauce:options" {
          tags = ["smoketest","billing"]
          recordVideo = true
          recordLogs = false
        }
      }
    }
```


---

<!-- https://serenity-bdd.github.io/docs/cloud/bitbar -->

# Serenity BDD BitBar Integration

BitBar is the cloud for all your testing needs. With BitBar, Serenity users have instant access to scale their cross-browser tests to real iOS and Android devices, as well as the latest and most popular browsers on macOS, Windows, and Linux.

The `serenity-bitbar` plugin ensures seamless integration with the [BitBar](https://BitBar.com/) online test automation platform.

## Adding the BitBar plugin

To add the integrated support for BitBar to your project, add the `serenity-bitbar` dependency to your project dependencies as follows:

* for Maven
```xml
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-bitbar</artifactId>
    <version>${serenity.version}</version>
</dependency>
```

* for Gradle:
```groovy
testImplementation "net.serenity-bdd:serenity-bitbar:${serenityVersion}"
```

## Specifying your BitBar credentials and grid URL
Next, you need a [BitBar account](https://smartbear.com/product/bitbar/free-trial/).

You can add your [BitBar credentials](https://cloud.bitbar.com/#user/security-center) in two ways:

* Define the following system property

`BITBAR_API_KEY` - BitBar API Key

* Define your API Key using the `bitbar.apiKey` property in your `serenity.conf` file

```hocon
bitbar.apiKey=XXXXXXXX
```

## Configuring the BitBar driver

Serenity interacts with BitBar via the `RemoteDriver` driver. You need to specify the remote URL for the geographical region you want to use in the `webdriver.remote.url` property as follows:
```hocon
webdriver {
  driver = remote
  remote.url = "https://eu-mobile-hub.bitbar.com/wd/hub"
}
```
Alternatively, you can define a hub and the `remote.url` will be set automatically:

```hocon
bitbar.hub = "eu-desktop-hub"
```

## Activating the BitBar plugin

The Serenity BitBar plugin is invoked if Serenity finds a `bitbar:options` section in your `serenity.conf` file, or if you specify a `remote.webdriver.url` that points to a BitBar server. If you have no BitBar-specific capabilities, simply set the `bitbar.active` property to true as follows:

```hocon
bitbar {
  active = true
}
```

## Defining BitBar Capabilities

You can specify the operating system and browser on which you want to run your tests by customizing the capabilities in your `serenity.conf` file. Do this in the `bitbar:options` section of the `serenity.conf` file, for example:

```hocon
webdriver {
  driver = "remote"
  capabilities {
    browserName = "chrome"
    version = "latest"
    platform = "Windows"
    "bitbar:options" {
      osVersion = "10"
      screenResolution = "1920x1200"
    }
  }
}
```


---

<!-- https://serenity-bdd.github.io/docs/mobile/appium -->

# Running tests on Appium
Serenity supports running tests on mobile devices/emulators out of the box with [Appium](http://appium.io).

First, you will need to install Appium:
```
(sudo) npm install -g appium --chromedriver_version="102.0"
```

Afterwards Appium is available as command and can be started by invoking the following command:

```
appium
```

Then adapt `serenity.properties` to run on an Android device:

```
webdriver.driver= appium
webdriver.base.url = http://www.google.com/
appium.hub = http://127.0.0.1:4723/wd/hub
appium.platformName = Android
appium.platformVersion = 5.1.1
appium.deviceName = e2f5c460
appium.browserName = Chrome
```

Here's an example for iOS:

```
webdriver.driver= appium
webdriver.base.url = http://www.google.com/
appium.hub = http://127.0.0.1:4723/wd/hub
appium.platformName = iOS
appium.platformVersion = 8.1
appium.deviceName = iPhone 5
appium.browserName = Safari
```

Note: All properties which are starting with `appium` in serenity.properties will be forwarded to appium driver. 

For example, setting `appium.automationName = XCUITest` in serenity.properties will have as end effect setting the property `automationName = XCUITest` in appium driver capabilities.

Besides the properties file you can also use commandline switches:

```
mvn test -Dappium.hub=http://127.0.0.1:4723/wd/hub -Dwebdriver.driver=appium -Dappium.platformName=iOS -Dappium.browserName=Safari -Dappium.deviceName="iPhone 5"
```

All properties starting with appium.* will be forwarded to the appium driver as appium desired capabilities.

For example, setting the property `appium.automationName=myAutomationName` will have as effect setting the capability `automationName` in the appium driver to `myAutomationName`.

The following annotations are supported for a PageObject element:

```java
@AndroidFindBy(id="")
private WebElement loginButton;
```

```java
@iOSFindBy(id="")
private WebElement loginButton;
```

```java
@FindBy(accessibilityId="")
private WebElement loginButton;
```

Sometimes it may be necessary in a PageObject to use specific methods of the underlying driver:
```java
AndroidDriver<AndroidElement> androidDriver() {
    return (AndroidDriver<AndroidElement>)
            ((WebDriverFacade) getDriver()).getProxiedDriver();
}
...
androidDriver().hideKeyboard();
```

You can also add Appium to an existing grid. See the [Appium documentation](https://appium.io/docs/en/advanced-concepts/grid/) for more details about the node-config option.


---

<!-- https://serenity-bdd.github.io/docs/reference/serenity-properties -->

## Where Serenity reads configuration from

Serenity reads settings from these places. Each behaviour below was checked by running it against Serenity 5.4.1.

| Source | Where | Read? |
|---|---|---|
| `serenity.conf` (HOCON) | `src/test/resources/` (the classpath) | yes |
| `serenity.conf` | the project root | **no, it is ignored** |
| `serenity.properties` | the project root | yes |
| `serenity.properties` | `src/test/resources/` | yes |
| System properties | `-Dkey=value` on the command line | yes, they override the files |

- A `-D` option on the command line wins over both files.
- A `serenity.properties` in the project root wins over a `serenity.conf` in `src/test/resources`. When both files are in `src/test/resources`, `serenity.conf` wins.
- Operating-system environment variables such as `SERENITY_PROJECT_NAME` do **not** set the matching property. They can be used inside `serenity.conf` as `${NAME}` substitutions.
- After moving or deleting a configuration file, run `mvn clean`: Maven leaves the old copy in `target/test-classes`, so the old file keeps being read.

### Environment-specific values

```hocon
app.url = "https://top-level.example.com"

environments {
  default { app.url = "https://dev.example.com" }
  staging { app.url = "https://staging.example.com" }
}
```

Choose an environment with `-Denvironment=staging`. Values that staging does not define fall back to `default`, and a block called `all` applies in every environment.

#### Reading a value in code

```java
EnvironmentVariables env = SystemEnvironmentVariables.currentEnvironmentVariables();

// Works in every release:
String url = EnvironmentSpecificConfiguration.from(env).getOptionalProperty("app.url").orElse("none");

// Releases after 5.4.1 also resolve environment values here:
String same = env.getProperty("app.url");
```

In 5.4.1 and earlier, `env.getProperty("app.url")` returns `null` for a key that is defined only inside `environments { }`. Reading `env.getProperty("environments.default.app.url")` returns the `default` block's value whatever environment you chose, so it is not a way to read the chosen environment's value.

#### Which value wins

In releases after 5.4.1, `getProperty` and `EnvironmentSpecificConfiguration` resolve a value in the same order:

1. a value given explicitly: `-Dapp.url=...` on the command line, or set in code;
2. the chosen environment (or environments, if you give several separated by commas; the last one wins);
3. the `all` block, then the `default` block;
4. the plain value from `serenity.conf` or `serenity.properties`.

For the configuration above:

| You run | `app.url` is |
|---|---|
| (nothing) | `https://dev.example.com` |
| `-Denvironment=staging` | `https://staging.example.com` |
| `-Denvironment=staging -Dapp.url=https://cli.example.com` | `https://cli.example.com` |
| `-Denvironment=staging -Denvironments.staging.app.url=https://cli-staging.example.com` | `https://cli-staging.example.com` |

Serenity's own keys (such as `webdriver.base.url` or `serenity.project.name`) inside `environments { }` have always overridden the top-level value; this now holds for your own keys too.

:::info Changed in releases after 5.4.1
Three things behave differently from 5.4.1 and earlier. Check any code or build scripts that depend on them.

- **`getProperty` finds environment-only keys.** A key defined only inside `environments { }` used to return `null`; it now returns the value for the chosen environment.
- **`-Dkey=value` overrides an environment value.** In 5.4.1 and earlier, `-Dapp.url=...` did not override `environments { staging { app.url } }`, and you had to write `-Denvironments.staging.app.url=...`. The long form still works.
- **A key defined both at the top level and inside `environments { }`** now returns the environment value from `getProperty`, as `EnvironmentSpecificConfiguration` and Serenity's own keys already did. Before, `getProperty` returned the top-level value. If you relied on that, move the value you want to keep out of `environments { }`, or give it explicitly with `-D`.

Values read from `serenity.conf` and `serenity.properties` still rank last, and operating-system environment variables such as `SERENITY_PROJECT_NAME` still do not set the matching property.
:::

## Running Serenity tests from the command line

You typically run Serenity as part of the build process (either locally or on a CI server). In addition to the `webdriver.driver` option discussed [here](/docs/guide/driver_config), you can also pass a number of parameters in as system properties to customize the way the tests are run. You can also place these files in a Properties file called `serenity.properties`, in your project root directory.

The full list is shown here:

### properties
Absolute path of the property file where Serenity system property defaults are defined. Defaults to `~/serenity.properties`

### webdriver.driver
What browser do you want your tests to run in, for example firefox, chrome, phantomjs or iexplorer. You can also use the *driver* property as a shortcut.

### webdriver.autodownload
Set to `false` if you don't want Serenity to automatically download driver binaries for local runs.

### webdriver.provided_type
If using a provided driver, what type is it. The implementation class needs to be defined in the `webdriver.provided.{type}` system property.

### webdriver.base.url
The default starting URL for the application, and base URL for relative paths.

### webdriver.remote.url
The URL to be used for remote drivers (including a selenium grid hub or SauceLabs URL)

### phantomjs.webdriver.port
What port to run PhantomJS on (used in conjunction with webdriver.remote.url to register with a Selenium hub, e.g. -Dphantomjs.webdriver=5555 -Dwebdriver.remote.url=http://localhost:4444/wd/hub

### webdriver.remote.driver
The driver to be used for remote drivers

### serenity.driver.capabilities
A set of user-defined capabilities to be used to configure the WebDriver driver. Capabilities should be passed in as a space or semi-colon-separated list of key:value pairs, e.g. "build:build-1234; max-duration:300; single-window:true; tags:[tag1,tag2,tag3]"

### webdriver.timeouts.implicitlywait
How long webdriver waits for elements to appear by default, in milliseconds.

### webdriver.wait.for.timeout
How long webdriver waits by default when you use a fluent waiting method, in milliseconds.

### webdriver.chrome.driver
Path to the Chrome driver, if it is not on the system path.

### serenity.home
The home directory for Serenity output and data files - by default, $USER_HOME/.serenity

### serenity.outputDirectory
Where should reports be generated. If project contains only one module (root module), than this path will be relative to root module, if project contains more than one submodule - than this path will be relative to submodule directory, also this path can be different for each submodule or can be inherited from root project property.

### serenity.project.name
What name should appear on the reports

### serenity.ext.packages*
Extension packages. This is a list of packages that will be scanned for custom TagProvider implementations. To add a custom tag provider, just implement the TagProvider interface and specify the root package for this provider in this parameter.

### serenity.verbose.screenshots
Should Serenity take screenshots for every clicked button and every selected link? By default, a screenshot will be stored at the start and end of each step. If this option is set to true, Serenity will record screenshots for any action performed on a WebElementFacade, i.e. any time you use an expression like element(...).click(), findBy(...).click() and so on. This will be overridden if the ONLY_SAVE_FAILING_SCREENSHOTS option is set to true.
@Deprecated This property is still supported, but serenity.take.screenshots provides more fine-grained control.

### serenity.take.screenshots
Set this property to have more finer control on how screenshots are taken, default is `serenity.take.screenshots=BEFORE_AND_AFTER_EACH_STEP` This property can take the following values:

* `FOR_EACH_ACTION`: Saves a screenshot at every web element action (like click(), typeAndEnter(), type(), typeAndTab() etc.).
* `BEFORE_AND_AFTER_EACH_STEP`: Saves a screenshot before and after every step.
* `AFTER_EACH_STEP`: Saves a screenshot after every step
* `FOR_FAILURES`: Saves screenshots only for failing steps.
* `DISABLED`: Doesn't save screenshots for any steps.

### serenity.full.page.screenshot.strategy
Set this property to have full page screenshot support. This property can take the following values:

* `true`: Enables WHOLE_PAGE screenshot mode.
* `false`: Enables VIEWPORT_ONLY screenshot mode. (default)

### serenity.report.encoding
Encoding used to generate the CSV exports

### serenity.verbose.steps
Set this property to provide more detailed logging of WebElementFacade steps when tests are run.

### serenity.reports.show.step.details
Should Serenity BDD display detailed information in the test result tables. If this is set to true, test result tables will display a breakdown of the steps by result. This is false by default.

### serenity.report.show.manual.tests
Show statistics for manual tests in the test reports.

### serenity.report.show.releases
Report on releases (defaults to true).

### serenity.restart.browser.frequency
During data-driven tests, some browsers (Firefox in particular) may slow down over time due to memory leaks. To get around this, you can get Serenity to start a new browser session at regular intervals when it executes data-driven tests.

### serenity.step.delay
Pause (in ms) between each test step.

### untrusted.certificates
Useful if you are running Firefox tests against an HTTPS test server without a valid certificate. This will make Serenity use a profile with the AssumeUntrustedCertificateIssuer property set.

### refuse.untrusted.certificates
Don't accept sites using untrusted certificates. By default, Serenity BDD accepts untrusted certificates - use this to change this behaviour.

### serenity.timeout
How long should the driver wait for elements not immediately visible, in milliseconds.

### serenity.browser.width
### serenity.browser.height
Resize the browser to the specified dimensions, in order to take larger screenshots. This should work with Internet Explorer and Firefox, but not with Chrome.

### serenity.resized.image.width
Value in pixels. If set, screenshots are resized to this size. Useful to save space.

### serenity.keep.unscaled.screenshots
Set to `true` if you wish to save the original unscaled screenshots.
This is set to `false` by default.

### serenity.store.html.source
Set this property to `true` to save the HTML source code of the screenshot web pages.
This is set to `false` by default.

### serenity.issue.tracker.url
The URL used to generate links to the issue tracking system.

### serenity.activate.firebugs
Activate the Firebugs and FireFinder plugins for Firefox when running the WebDriver tests. This is useful for debugging, but is not recommended when running the tests on a build server.

### serenity.batch.strategy
Defines batch strategy. Allowed values - DIVIDE_EQUALLY (default) and DIVIDE_BY_TEST_COUNT. DIVIDE_EQUALLY will simply divide the tests equally across all batches. This could be inefficient if the number of tests vary a lot between test classes. A DIVIDE_BY_TEST_COUNT strategy could be more useful in such cases as this will create batches based on number of tests.

### serenity.batch.count
If batch testing is being used, this is the size of the batches being executed.

### serenity.batch.number
If batch testing is being used, this is the number of the batch being run on this machine.

### serenity.use.unique.browser
Set this to true for running all web tests in a single browser, for one test. Can be used for configuring Junit and Cucumber, default value is 'false'.

### restart.browser.each.scenario
Set this to false for running all web tests in same story file with one browser, can be used when Jbehave is used. default value is 'false'

### serenity.restart.browser.for.each
Indicate when a browser should be restarted during a test run. Can be one of: scenario, story, feature, never

### serenity.native.events
Activate and deactivate native events for Firefox by setting this property to `true` or `false`.

### security.enable_java
Set this to true to enable Java support in Firefox. By default, this is set to false as it slows down the web driver.

### serenity.proxy.http
HTTP Proxy URL configuration for Firefox and PhantomJS

### serenity.proxy.http_port
HTTP Proxy port configuration for Firefox and PhantomJS
### serenity.proxy.type
HTTP Proxy type configuration for Firefox and PhantomJS

### serenity.proxy.user
HTTP Proxy username configuration for Firefox and PhantomJS

### serenity.proxy.password
HTTP Proxy password configuration for Firefox and PhantomJS

### serenity.logging
Property for providing level of serenity actions, results, etc.

* *QUIET* : No Serenity BDD logging at all
* *NORMAL* : Log the start and end of tests
* *VERBOSE* : Log the start and end of tests and test steps, default value

### serenity.test.root
The root package for the tests in a given project. If provided, Serenity will use this as the root package when determining the capabilities associated with a test. If you are using the File System Requirements provider, Serenity BDD will expect this directory structure to exist at the top of the requirements tree. If you want to exclude packages in a requirements definition and start at a lower level in the hierarchy, use the `serenity.requirement.exclusions` property.

This is also used by the `PackageAnnotationBasedTagProvider` to know where to look for annotated requirements.

### serenity.requirements.dir
Use this property if you need to completely override the location of requirements for the File System Provider.

### serenity.use.requirements.directories
By default, Serenity BDD will read requirements from the directory structure that contains the stories. When other tag and requirements plugins are used, such as the JIRA plugin, this can cause conflicting tags. Set this property to false to deactivate this feature (it is true by default).

### serenity.annotated.requirements.dir
Use this property if you need to completely override the location of requirements for the Annotated Provider. This is recommended if you use File System and Annotated provider simultaneously. The default value is stories.

### serenity.requirement.types
The hierarchy of requirement types. This is the list of requirement types to be used when reading requirements from the file system and when organizing the reports. It is a comma-separated list of tags.The default value is: capability, feature.

### serenity.requirement.exclusions
When deriving requirement types from a path, exclude any values from this comma-separated list.

### serenity.test.requirements.basedir
The base directory in which requirements are kept.
It is assumed that this directory contains sub folders src/test/resources.
If this property is set, the requirements are read from src/test/resources under this folder instead of the classpath or working directory.
If you need to set an independent requirements directory that does not follow the src/test/resources convention, use `serenity.requirements.dir` instead

This property is used to support situations where your working directory
is different from the requirements base dir (for example when building a multi-module project from parent pom with requirements stored inside a sub-module.

### serenity.release.types
What tag names identify the release types (e.g. Release, Iteration, Sprint). A comma-separated list. By default, "Release, Iteration"

### serenity.locator.factory
Normally, Serenity uses SmartElementLocatorFactory, an extension of the AjaxElementLocatorFactory when instantiating page objects.
This is to ensure that web elements are available and usable before they are used.
For alternative behaviour, you can set this value to `DisplayedElementLocatorFactory`, `AjaxElementLocatorFactory` or `DefaultElementLocatorFactory`.

### chrome.switches
Arguments to be passed to the Chrome driver, separated by semicolons. Example: `chrome.switches = --incognito;--disable-download-notification`

// FIXME link to Serenity.useFirefoxProfile()
### webdriver.firefox.profile
The path to the directory of the profile to use when starting firefox. This defaults to webdriver creating an anonymous profile. This is useful if you want to run the web tests using your own Firefox profile. If you are not sure about how to find the path to your profile, look here: http://support.mozilla.com/en-US/kb/Profiles. For example, to run the default profile on a Mac OS X system, you would do something like this:

```bash
$ mvn test -Dwebdriver.firefox.profile=/Users/johnsmart/Library/Application\ Support/Firefox/Profiles/2owb5g1d.default
```
On Windows, it would be something like:

```bat
C:\Projects\myproject>mvn test -Dwebdriver.firefox.profile=C:\Users\John Smart\AppData\Roaming\Mozilla\Firefox\Profiles\mvxjy48u.default
```
### firefox.preferences
A semicolon separated list of Firefox configuration settings. For ex.,

```bash
-Dfirefox.preferences="browser.download.folderList=2;browser.download.manager.showWhenStarting=false;browser.download.dir=c:\downloads"
```

Integer and boolean values will be converted to the corresponding types in the Firefox preferences; all other values will be treated as Strings. You can set a boolean value to true by simply specifying the property name, e.g. `-Dfirefox.preferences=app.update.silent`.

A complete reference to Firefox's configuration settings is given [here](https://kb.mozillazine.org/Firefox_:_FAQs_:_About:config_Entries).

### serenity.csv.extra.columns
Add extra columns to the CSV output, obtained from tag values.

### serenity.console.headings
Write the console headings using ascii-art ("ascii", default value) or in normal text ("normal")

### tags
"or" separated list of tags. If provided, only JUnit classes and/or methods with tags in this list will be executed. For example,

```bash
mvn verify -Dtags="iteration:I1"

mvn verify -Dtags="color:red or flavor:strawberry"
```

### output.formats
What format should test results be generated in. By default, this is "json,xml".

### narrative.format
Set this property to 'asciidoc' to activate using http://www.methods.co.nz/asciidoc/[Asciidoc] format in narrative text.

### jira.url
If the base JIRA URL is defined, Serenity will build the issue tracker url using the standard JIRA form.

### jira.project
If defined, the JIRA project id will be prepended to issue numbers.

### jira.username
If defined, the JIRA username required to connect to JIRA.

### jira.password
If defined, the JIRA password required to connect to JIRA.

### show.pie.charts
Display the pie charts on the dashboard by default. If this is set to false, the pie charts will be initially hidden on the dashboard.

### dashboard.tag.list
If set, this will define the list of tag types to appear on the dashboard screens

*dashboard.excluded.tag.list*::If set, this will define the list of tag types to be excluded from the dashboard screens

### json.pretty.printing
Format the JSON test outcomes nicely. "true" or "false", turned off by default.

### simplified.stack.traces
Stack traces are by default decluttered for readability. For example, calls to instrumented code or internal test libraries is removed. This behaviour can be deactivated by setting this property to false.

### serenity.dry.run
Run through the steps without actually executing them.

### feature.file,language
What (human) language are the Cucumber feature files written in? Defaults to "en".

### serenity.maintain.session
Keep the Serenity BDD session data between tests. Normally, the session data is cleared between tests.

### serenity.console.colors
There is feature for colorful console output during executing serenity tests. To enable it you should provide variable `serenity.console.colors = true`, by default it is turned off. This feature can cause errors if it is enabled for builds under Jenkins.

![Console color output is disabled](img/console-colors-off.png)

If this property equal to true you will find colorful output:

![Console color output is enabled](img/console-colors-on.png)

### serenity.include.actor.name.in.consequences
Set to true to show actor names in the "then" steps. Especially useful when you have multiple actors in a test

[FIXME move FF profile to extended driver info pages?]:#
## Providing your own Firefox profile

If you need to configure your own customized Firefox profile, you can do this by using the Serenity.useFirefoxProfile() method before you start your tests. For example:

```java
@Before
public void setupProfile() {
  FirefoxProfile myProfile = new FirefoxProfile();
  myProfile.setPreference("network.proxy.socks_port",9999);
  myProfile.setAlwaysLoadNoFocusLib(true);
  myProfile.setEnableNativeEvents(true);
  Serenity.useFirefoxProfile(myProfile);
}

@Test
public void aTestUsingMyCustomProfile() {...}
```