Ui Test

User journeys in scope

Pages — routes, headings, form fields

These are the actual routes and form field names from the source. Always use these exact names.

Home page

Boundary type

Development types

Residential

Email

Upload boundary

No EDP

Upload received

GOV.UK component selectors

Use role-based selectors first. These are the standard GOV.UK Frontend patterns:

// Radio buttons
page.getByRole('radio', { name: 'Draw the boundary on a map' })
page.getByRole('radio', { name: 'Upload a file' })

// Checkboxes
page.getByRole('checkbox', { name: 'Housing' })
page.getByRole('checkbox', { name: 'Other residential' })

// Text/email/number inputs — use label text
page.getByLabel('Email address')
page.getByLabel('Number of residential buildings')

// File upload
page.getByLabel('Upload a boundary file')

// Continue/Submit button
page.getByRole('button', { name: 'Continue' })

// Start button on home page
page.getByRole('link', { name: 'Start now' })

// Error summary (GOV.UK pattern)
page.locator('.govuk-error-summary')
page.locator('.govuk-error-message')

// Page heading
page.locator('h1')

// Back link
page.locator('.govuk-back-link')

Always check the actual Nunjucks template in ../nrf-frontend/src/server/<page>/ for exact label text before writing selectors.

Session and state

• Sessions are server-side (memory in dev, Redis in prod). Do not manipulate cookies.
• CSRF tokens are injected automatically — forms submit via POST with the token; Playwright handles this transparently.
• ENABLE_DEFRA_ID=false disables authentication for tests. Do not test the OIDC flow unless explicitly asked.

What to test

For each page, test in this order:

1. Happy path — valid input, correct next page reached
2. Conditional routing — where next page depends on input value (e.g. development-types → residential)

Do not test:

• Exact UUIDs, session tokens, or server-generated IDs
• Environment-specific values that differ between local/dev/prod
• Implementation details (CSS classes, DOM structure beyond what's semantically meaningful)

Implementation checklist

Before writing any code

1. Check flows/<journey>.md — if it does not exist, stop and ask the user to create it.
2. Read the Nunjucks template and controller in ../nrf-frontend/src/server/<page>/ for exact field names and label text. Always read the current source — never assume from memory.
3. Coverage gap analysis — mandatory, must be presented to the user before writing any test code:
   • Read the latest ../nrf-frontend/src page.test.js files and ../nrf-backend/src *.test.js files for every AC in scope.
   • For each AC produce one of these three recommendations:
     • Write E2E — only verifiable end-to-end (cross-service routing, full journey flow, confirmation content)
     • Descope from E2E — already covered at unit or integration level; note in flow doc "Out of scope" section
     • Enhance integration test instead — name the specific test file in nrf-frontend or nrf-backend to extend; do not write an E2E scenario
   • Present the analysis and revised AC scope to the user. Wait for approval before proceeding.

Implementation

4. Create test/page-objects/<name>.page.js — extend Page, expose locators as getters and actions as async methods, no assertions
5. Register the page object in test/support/world.js under this.pageObjects
6. Create test/features/<journey>.feature — tag every scenario @smoke and/or @regression
7. Create test/step-definitions/<journey>.steps.js — assertions go here, not in page objects
8. Run headed: npm run test:e2e:debug
9. Lint and format: npm run lint && npm run format:check

Page object template

import { Page } from './page.js'

export class BoundaryTypePage extends Page {
  constructor(page, baseUrl) {
    super(page, baseUrl)
  }

  async open() {
    await this.goto('/quote/boundary-type')
  }

  get drawRadio() {
    return this.page.getByRole('radio', { name: 'Draw the boundary on a map' })
  }

  get uploadRadio() {
    return this.page.getByRole('radio', { name: 'Upload a file' })
  }

  get continueButton() {
    return this.page.getByRole('button', { name: 'Continue' })
  }

  get errorSummary() {
    return this.page.locator('.govuk-error-summary')
  }

  async selectBoundaryType(type) {
    if (type === 'draw') await this.drawRadio.click()
    if (type === 'upload') await this.uploadRadio.click()
  }

  async continue() {
    await this.continueButton.click()
  }
}

Feature file template

@smoke @regression
Feature: Boundary type selection

  Scenario: Developer selects upload boundary type and continues
    Given I am on the boundary type page
    When I select "upload"
    And I continue
    Then I should be on the upload boundary page

  Scenario: Developer selects draw boundary type and continues
    Given I am on the boundary type page
    When I select "draw"
    And I continue
    Then I should be on the draw boundary page

Validation errors (empty submission, invalid input, error messages) are tested at the nrf-frontend unit/integration level — do not duplicate them as E2E scenarios.

Step definition template

import assert from 'node:assert/strict'
import { Given, When, Then } from '@cucumber/cucumber'

Given('I am on the boundary type page', async function () {
  await this.pageObjects.boundaryTypePage.open()
})

When('I select {string}', async function (type) {
  await this.pageObjects.boundaryTypePage.selectBoundaryType(type)
})

When('I continue', async function () {
  await this.pageObjects.boundaryTypePage.continue()
})

Then('I should be on the upload boundary page', async function () {
  await this.pageObjects.uploadBoundaryPage.waitFor()
  assert.equal(
    await this.page.title(),
    'Upload boundary - Nature Restoration Fund - Gov.uk'
  )
})