Cpp Test Authoring

CPP Test Authoring

Guides contributors through the conventions of the two HMCTS Crime Common Platform test repositories so new tests slot into existing patterns instead of forking them.

Repos covered:

• cpp-ui-e2e-serenity — UI end-to-end (Serenity BDD 4.x + Cucumber 6 + Selenium, Java 17, Maven)
• cpp-apitests — API integration tests (JUnit 5 + REST Assured, Java 17, Maven)

When to Use

• User asks to add or extend a UI E2E test, Cucumber feature, step definition, or page object
• User asks to add or extend an API integration test (*IT.java)
• User asks "how do I add a test for X" while inside either repo
• Reviewing whether a proposed test follows the established pattern (defer the actual PR review to review-pr)

When NOT to Use

• Authoring unit tests inside a runtime service (cpp-context-*, cpp-mbd-*) — that's part of the service's own conventions
• Writing or modifying Spring Boot service code — see springboot-service-from-template
• Pipeline failures — defer to pipeline-debug
• WCAG audits — defer to accessibility-check

Prerequisites

Before writing test code:

1. Story has acceptance criteria — apply write-acceptance-criteria if missing
2. For UI scenarios, the Gherkin draft exists — apply generate-bdd-specs if missing
3. Jira ticket is linked (hard rule from claude/CLAUDE.md)
4. No PII, case data, or court reference numbers in any planned fixture, feature, or assertion (hard rule)

Step 1 — Identify the Repo and Test Layer

| Repo | Layer | Marker files | |------|-------|--------------| | cpp-ui-e2e-serenity | UI E2E | serenity.properties, azure-pipelines-dev01_*.yml, src/test/resources/features/ | | cpp-apitests | API integration | apitests-pipeline.yaml, api-integration-test/ module, *IT.java suffixed tests |

If neither marker is present, stop — you're in the wrong repo.

Step 2 — UI E2E: Authoring a Serenity / Cucumber Test

Directory map

cpp-ui-e2e-serenity/
├── src/test/java/com/
│   ├── pageobjects/         # One class per page/section; holds locators + interactions
│   ├── stepdefinitions/     # Cucumber glue; extends the relevant page object
│   └── runner/              # TestRunner.java, RetryTestRunner.java
├── src/test/resources/
│   ├── features//   # *.feature files (Gherkin)
│   ├── locators/custom-locators.json
│   └── testdata//
└── serenity.properties

Authoring checklist

1. Reuse first — grep stepdefinitions/ and pageobjects/ for the journey before creating new classes. Duplicating a step definition is the single most common review reject.
2. Place the feature file under the correct features// folder. Match the naming style of neighbours (CPS, In-Sprint, etc.).
3. Tag scenarios for the pipeline they belong in. The repo has many runner profiles:

• azure-pipelines-dev01_regression.yml — main regression
• azure-pipelines-dev01_BPO_regression.yml — BPO regression
• azure-pipelines-dev01_migration*.yml — migration suites (vanilla / EDT / nows / ts)
• azure-pipeline-cdci-dlrm.yml — DLRM

Choose tags consistent with the existing features in the same folder.

1. Step definitions must extends the page object they exercise. Annotate steps with @Step. Do not hold state in static fields — use the Serenity session.
2. Page objects own all locator strategy. Register new locators in src/test/resources/locators/custom-locators.json; do not hard-code selectors in Java.
3. Wait correctly — use Serenity / WebDriverWait conditions. No Thread.sleep.
4. Test data goes under src/test/resources/testdata//. No real names, NI numbers, URNs, or court refs — use the existing fake data pattern.
5. Wire glue — TestRunner.java declares glue = "com.stepdefinitions". If you add a new package, update the runner.
6. Local run — mvn clean verify -P. Serenity report lands in target/site/serenity/index.html.

Common rejects to avoid

• New page object that duplicates locators from an existing one
• Hard-coded XPath in a step definition
• Thread.sleep(...) instead of an explicit wait
• Feature file in the wrong domain folder so it isn't picked up by the intended pipeline tag
• Real defendant / officer / court data in testdata/

Step 3 — API: Authoring a *IT.java

Directory map

cpp-apitests/api-integration-test/src/test/
├── java/uk/gov/moj/
│   ├── AbstractTest.java                 # Root base
│   ├── ApplicationsAbstractTest.java
│   ├── AuditAbstractTest.java
│   ├── AuthorizationAbstractTest.java
│   └── test/                              # *IT.java live here
└── resources//                    # JSON fixtures, payloads

Authoring checklist

1. File naming is load-bearing — must end IT.java. Failsafe only picks up that suffix; *Test.java will not run in CI.
2. Extend the closest abstract base:

• General API → AbstractTest
• Audit assertions → AuditAbstractTest
• Authorization flows → AuthorizationAbstractTest
• Applications API → ApplicationsAbstractTest

The base wires @ExtendWith(TestHook.class) and shared setup. Do not re-declare hooks.

1. Reuse helpers and builders before creating new ones — grep for the domain you're testing:

• JsonUtil, DbUtil, ApplicationUtil, RestAssuredFileUploadUtil
• Domain helpers, e.g. CpsUnifiedSearchHelper
• Builders, e.g. CpsCaseIngestionData.Builder

1. REST Assured pattern — use given().when().then() with Hamcrest matchers or AssertJ. Avoid raw assertEquals on JSON paths.
2. Fixtures live under src/test/resources//. Load via JsonUtil. No PII / court refs.
3. Contract alignment — when asserting a response shape, cross-check it against the producing service's RAML / OpenAPI. Apply api-contract-check if the response surface is changing.
4. Local run — mvn clean verify (Failsafe phase). Single class: mvn verify -Dit.test=MyEndpointIT -pl api-integration-test.

Common rejects to avoid

• File named *Test.java (Failsafe skips it)
• Extending AbstractTest when a more specific base exists
• Inline JSON payload strings instead of resource fixtures + JsonUtil
• New helper class that duplicates an existing util
• Hard-coded bearer tokens or URLs — use the configured environment

Step 4 — Pre-Commit Checklist (both repos)

• [ ] No PII / case data / court reference numbers anywhere in the diff
• [ ] Existing page objects / step defs / helpers / builders were reused, not duplicated — apply simplify if unsure
• [ ] (UI only) Journey passes a11y check — apply accessibility-check
• [ ] (API only) Assertions match the producing service's contract — apply api-contract-check
• [ ] ADR raised for any deviation from the patterns above — apply adr-template
• [ ] Test runs green locally
• [ ] Test runs green on the targeted pipeline profile

Step 5 — When CI Fails

Defer to pipeline-debug. Identify the failing YAML first:

• UI: one of the azure-pipelines*.yml variants in cpp-ui-e2e-serenity
• API: apitests-pipeline.yaml or azure-pipelines.yaml in cpp-apitests

Step 6 — Raising the PR

When the test is ready:

1. Run review-pr against the diff first — it has a section for these two repos
2. If it surfaces blocking issues, fix before raising
3. Open the PR; reviewer runs review-pr again as part of the merge gate

Related Skills

• write-acceptance-criteria — derive ACs from the story (run first)
• generate-bdd-specs — author the Gherkin feature (UI only)
• accessibility-check — WCAG 2.1 AA on user-facing journeys
• api-contract-check — RAML / OpenAPI alignment for *IT.java
• review-pr — PR review checklist (includes a test-repo section)
• pipeline-debug — CI failure diagnosis
• simplify — reuse and dedupe pass before commit
• adr-template — record any deviation from the patterns above
• security-review — required if touching auth, session, tokens, or PII handling

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hmcts
• Source: hmcts/claude
• License: MIT

Install and usage instructions live in the source repository linked above.