Owner / author: Sean Bennett
A working demonstration of black‑box end‑to‑end test automation: business‑readable Gherkin specifications, driven by Cypress through a Page Object Model, executed against a real running stack (Angular UI → .NET 8 API → Postgres) — all of it containerised and run on every push by GitHub Actions.
The block below is written back into this README by the
E2E Tests workflow on every push to main, straight from the
JUnit XML that the containerised Cypress run produces. The same table is published to the
GitHub Actions job summary.
✅ All 2 scenarios passed · run #1 · commit 516641f · 2026-08-04 19:20 UTC
| Passed | Failed | Skipped | Total | Duration |
|---|---|---|---|---|
| 2 | 0 | 0 | 2 | 9.7s |
| Feature | Scenario | Duration | |
|---|---|---|---|
| ✅ | As a user I want to be able to report a problem so that it can be fixed | Create ticket (example #1) | 5.5s |
| ✅ | As a user I want to be able to report a problem so that it can be fixed | Create ticket (example #2) | 4.2s |
Every run also uploads a cypress-artifacts bundle: the JUnit XML, screenshots of any failure,
an MP4 video of each spec, and the full logs of the application containers.
| Capability | Where to look |
|---|---|
| Specifications a non‑engineer can read and review | createTicket.feature |
| Steps that stay thin — no selectors, no waits | step_definitions/ |
| Page Object Model holding all UI knowledge | pageObjectModel/ |
| Design by contract, so failures point at a cause | precondition.ts |
| Trace logging to terminal, browser console and Cypress log | log.ts |
| The whole stack + runner as containers | docker-compose.e2e.yaml, e2e/Dockerfile |
| CI that reports results back into this page | .github/workflows/e2e-tests.yml |
| An API‑level suite in SpecFlow covering the same domain | src/tests/api |
A ticket ("request form") tracker: an Angular 17 + Angular Material front end served by nginx,
talking to an ASP.NET Core 8 Web API over /api, persisted in Postgres.
The screenshots below are not hand‑taken — they are captured by
captureDocScreenshots.ts, a spec
that drives the app through the same Page Object Model the tests use (npm run screenshots).
If the UI changes, regenerating the documentation is one command.
The Tags control is a mat-select multiple that defaults to Bug. The POM opens the overlay,
clears the default and selects each tag from the example row — the kind of component interaction
that gets ugly fast when it lives inside step definitions.
Every value here comes from one row of the Examples: table — title, application area,
description, date offset, video provider + id, contact email and tags.
One Scenario Outline row, from Gherkin text to a database row and back to an assertion.
sequenceDiagram
autonumber
participant Feature as createTicket.feature
participant Steps as Step definitions
participant Journey as ScenarioJourneySingleton
participant POM as Page Object Model
participant Cypress as Cypress runner
participant UI as Angular UI (nginx)
participant API as .NET API
participant DB as Postgres
Note over Journey: Before hook resets the journey<br/>so scenarios never share state
Feature->>Steps: Given I login as role Anonymous
Feature->>Steps: And I start creating a ticket
Steps->>Journey: getPageObjectModel()
Journey-->>Steps: PageObjectModel
Steps->>POM: gotoRoot().createTicket()
POM->>Cypress: cy.visit('/') + cy.contains('Create Ticket').click()
Cypress->>UI: navigate to the create route
loop each field in the Examples row
Feature->>Steps: And I enter the title / area / description / date / video / email / tags
Steps->>POM: fillTitle / fillApplicationArea / fillTags ...
POM->>Cypress: cy.get by formcontrolname, then type or click
Cypress->>UI: drive the Angular Material control
Note over POM: the value is also recorded in<br/>CreateTicketPageValues for later assertion
end
Feature->>Steps: When I submit the ticket
Steps->>POM: submit()
POM->>Cypress: click the raised primary button
Cypress->>UI: submit the reactive form
UI->>API: POST /api/RequestForm
API->>DB: INSERT request form record
DB-->>API: created row
API-->>UI: 200 + created ticket
UI-->>Cypress: redirect to list + "Item created successfully"
Feature->>Steps: Then I should see the ticket created successfully
Steps->>POM: getCreateTicketPageValues()
POM-->>Steps: title, application area, submitted-at
Steps->>POM: verifyLastTicketMatches(...)
POM->>Cypress: assert last .list-item-row matches the entered values
Cypress-->>Feature: scenario passes / fails with a screenshot + video
The important property: the feature file, the step definitions and the page objects each know
exactly one thing. Selectors live only in the POM, so a UI change is a one‑file change; the
Examples: table is the only place test data lives.
No Cypress on the runner, no Node version to match, no wait-on guesswork — the runner only
needs Docker.
sequenceDiagram
autonumber
participant Dev as Developer
participant GH as GitHub Actions runner
participant Compose as docker compose
participant Stack as db + api + fe containers
participant Runner as cypress/included:9.5.4 container
participant Report as renderTestResults.mjs
Dev->>GH: push / pull request
GH->>Compose: build (base + e2e override)
Compose->>Stack: up -d db, API, UI
GH->>Compose: run --rm e2e
Compose->>Runner: start on the simple-form-net network
Runner->>Runner: tsc (TypeScript ➜ cypress/)
Runner->>Stack: poll UI + API until both answer (waitForApp.mjs)
Stack-->>Runner: ready
Runner->>Stack: execute the Gherkin suite against http://simple-form-app-fe
Runner-->>GH: exit code + JUnit XML, video, failure screenshots (bind mounted to ./artifacts)
GH->>Report: node scripts/renderTestResults.mjs
Report-->>GH: markdown ➜ job summary
Report-->>GH: markdown ➜ README results block
GH->>GH: upload cypress-artifacts, capture container logs
GH->>Dev: commit README on main, then fail the job if any scenario failed
flowchart LR
subgraph net["docker network: simple-form-net"]
E2E["e2e<br/><small>cypress/included:9.5.4<br/>Gherkin + POM</small>"]
FE["simple-form-app-fe<br/><small>nginx :80 ➜ host 4200</small>"]
API["simple-form-app-api<br/><small>ASP.NET Core :8080</small>"]
DB[("db<br/><small>postgres:13.13</small>")]
end
ART["./artifacts<br/><small>junit.xml · videos · screenshots</small>"]
E2E -->|"HTTP, browser"| FE
E2E -.->|"readiness probe"| API
FE -->|"/api/* proxy_pass"| API
API -->|"EF Core"| DB
E2E -->|"bind mount"| ART
docker compose -f docker-compose.yaml -f docker-compose.e2e.yaml build
docker compose -f docker-compose.yaml -f docker-compose.e2e.yaml up -d db simple-form-app-api simple-form-app-fe
docker compose -f docker-compose.yaml -f docker-compose.e2e.yaml run --rm e2eResults land in ./artifacts (results/junit.xml, videos/, screenshots/). Render them:
node scripts/renderTestResults.mjsdocker compose up -d --build # UI on :4200, API on :8080, Postgres on :5432
cd src/tests/e2e
npm install
npm test # tsc, then run the Gherkin suite headlessly
npx cypress open # or drive it interactively| Script | Purpose |
|---|---|
npm test |
Compile TypeScript and run the feature files |
npm run test:ci |
Same, plus JUnit XML into results/ |
npm run test:docker |
Wait for the stack, then test:ci (the container's default command) |
npm run screenshots |
Regenerate the README screenshots into docs/images |
The base URL is no longer pinned to localhost:4200 — set CYPRESS_BASE_URL (the compose file
points the runner at http://simple-form-app-fe).
.
├── .github/workflows/e2e-tests.yml CI: build, run dockerised suite, publish results
├── docker-compose.yaml UI + API + Postgres
├── docker-compose.e2e.yaml adds the containerised Cypress runner
├── docs/images/ README screenshots (generated)
├── scripts/renderTestResults.mjs JUnit XML ➜ markdown (job summary + README)
└── src
├── be/SimpleFormApp ASP.NET Core 8 API + EF Core migrations
├── fe/simple-form-app Angular 17 + Angular Material UI
└── tests
├── api SpecFlow / C# API suite (see its README)
└── e2e Cypress + Gherkin UI suite
├── Dockerfile the runner image
├── cypress/integration/features/createTicket.feature
├── scripts/ waitForApp.mjs, collectScreenshots.mjs
└── src/
├── integration/docs/ screenshot capture spec (not part of the suite)
├── plugins/ cucumber preprocessor + log-to-stdout task
└── support/
├── helpers/ log.ts, precondition.ts
├── pageObjectModel/
└── step_definitions/
TypeScript in src/ is compiled by tsc into cypress/ — this Cypress version fails if it finds
.ts files under cypress/, so the sources live outside it and only the emitted JavaScript is
executed.
- Scenario Outline over duplicated scenarios. New coverage is a new row, not new code.
- A journey singleton, reset per scenario.
ScenarioJourneySingletoncarries the page object model between steps; theBeforehook rebuilds it so scenarios cannot leak state into each other. - Page transitions return the next page object.
rootApp.createTicket()returns aCreateTicketPage;createTicketPage.submit()returns aTicketListPage. Illegal transitions fail fast via preconditions ("Not currently on create ticket page") instead of as a selector timeout. - Assertions compare against what was typed.
CreateTicketPageValuesrecords every entered value, so the verification step checks the list against the scenario's own data, including a ±2 second tolerance on the server‑generated timestamp. - Layered logging.
trace()writes to stdout (via a Cypress task), the browser console and the Cypress command log, so a CI failure can be diagnosed from the job log alone.
Recorded as defects rather than papered over — the point of the exercise.
| # | Finding | Evidence |
|---|---|---|
| 1 | Fields optional at the API are required in the UI, so the API accepts payloads the UI cannot produce (bypassable with Postman). | Commented‑out third example row in createTicket.feature |
| 2 | An invalid video URL returns 400, but the UI shows a generic snackbar — the reason is only visible in the network tab. | e2e README |
| 3 | A successful POST returns 200 instead of 201. |
api README, logged as a warning rather than a failed assertion |
| 4 | A missing required field returns 400 with a raw deserialisation message leaking implementation detail. | api README |
| 5 | In the test code: fillTodaysDatePlusDays formats with getMonth() (0‑based), so "today" is entered as the previous month. The scenarios still pass because the assertion checks the server's creation timestamp, not the entered date — a latent gap worth closing. |
createTicketPage.ts |
- Broaden coverage: validation, edit and delete journeys, negative paths, accessibility checks.
- Replace CSS/Material selectors with
data-testattributes. - Reset the database between runs so assertions can rely on an exact list state.
- Add the SpecFlow API suite to the same compose file and the same workflow.
- Publish trend reporting (Cypress Cloud or a JUnit history action) rather than a single run.
Built and maintained by Sean Bennett · https://github.com/8exgh/cypress-e2e-test-automation




