Feature Tests

Test your installed guestbook against the expected specifications.

The .feature files on this page are Gherkin specifications. npx y2k-guestbook test runs them with Playwright against your installation of the guestbook:

  • A .feature file says what should happen.
  • A step definition is the TypeScript that applies that behaviour in the browser.

Install Playwright

From your Next.js app root:

npm install --save-dev @playwright/test playwright-bdd
npx playwright install chromium

Confirm the package installations by running:

npm ls @playwright/test playwright-bdd

Setup

Test Reports

A test run writes to a Playwright report folder — open index.html inside to view results:

  • A later run will overwrite the previous report.
  • A failed scenario keeps recording in the report you can use to debug.

The default folder is features/reports/results/ — in this setup, we'll use this default folder for user tests.

Support Files

features/support/ contains files that help Playwright run tests by giving them shared context:

features/support/world.ts holds the page, the guestbook URL, and values a later step needs to read:

export class PlaywrightWorld {
  page!: Page;
  baseUrl: string;
  guestbookPath: string;
  adminPath: string;
  postedName?: string;

  constructor() {
    this.baseUrl = String(process.env.BASE_URL ?? "http://localhost:3000").replace(/\/$/, "");
    this.guestbookPath = process.env.NEXT_PUBLIC_GUESTBOOK_PATH || "/";
    this.adminPath = process.env.NEXT_PUBLIC_GUESTBOOK_ADMIN_PATH || "/admin";
  }
}

Step Definitions

Example features/step_definitions/ map each Given / When / Then to clicks in the browser, covering the basic functionality of the guestbook, aligning with the Gherkin .feature files below.

You will need to write step definitions for any additional functionality you opt into (notifications, analytics) or any other features that you add.

Running Tests

Run .feature Tests

These tests do not require any admin authentication, so they can be run without any additional setup.

  1. Start the guestbook preview server: npm run dev

  2. In a second terminal at the app root, call:

    To run a specific test in a feature file, append the --name flag naming a Scenario. For example:

    # Writes to features/reports/results/index.html
npx y2k-guestbook test features/features/guestbook/guestbook-comments.feature --name "User submits a valid comment"

Optional Prefixes

By default, Playwright hides the browser window. To watch a run:

# Headed runs will run in Chrome by default
HEADED=1 npx y2k-guestbook test

Gherkin .feature Files

The packaged features/features/ directory contains the following .feature files displayed in this section.

Guestbook

Feature: Guestbook page navigation

    Background:
        Given a user is on the guestbook page

    Scenario: Admin login link is on the guestbook page
        When a user clicks the `admin login` link
        Then they are directed to the Google SSO page for the admin dashboard

Admin Dashboard

Feature: Unauthorized admin login

    Background:
        Given the user does not have admin authorization
        And a user is on the guestbook page

    Scenario: Unauthorized user is denied the dashboard
        When a user clicks the `admin login` link
        And they sign in successfully with Google
        Then they are redirected to the guestbook page
        And they are shown a message that they do not have admin authorization

    Scenario: Unauthorized visitor message can be dismissed
        Given the user is shown a message that they do not have admin authorization
        When they click the `Close` button
        Then the message closes

Write Additional Tests

If a Given / When / Then already has a matching function, Playwright runs that function. A line with no match fails with Missing step: and the text of that line. Create features/step_definitions/your-steps.ts for that line, and import the testing functions:

import { Given, When, Then } from "y2k-guestbook/testing";

Given("your scenario here", async function () {
  await this.page.goto(this.guestbookUrl());
});

Fill in the body with the appropriate code to execute the step. Instruction should be written the way a human user would find things on the page — for example, reference the submit button, the display name field, the prev / next links, and not CSS class names or code.

  • It doesn't matter what the file is called, as long as it's in the features/step_definitions/ directory and has the .ts extension.
  • Stash values you will need later on the World object (for example this.postedName).