Ghost End-To-End Test Suite

This test suite runs automated browser tests against a running Ghost instance to ensure critical user journeys work correctly.

Quick Start

Prerequisites

• Docker and Docker Compose installed
• Node.js installed (pnpm is managed via corepack — run corepack enable pnpm first)

Running Tests

To run the test, within this e2e folder run:

# Install dependencies
pnpm

# All tests
pnpm test

Dev Environment Mode (Recommended for Development)

If GHOST_E2E_MODE is unset, the e2e shell entrypoints auto-select:

• dev when the local admin dev server is reachable on http://127.0.0.1:5174
• build otherwise

To use dev mode, start pnpm dev before running tests:

# Terminal 1: Start dev environment (from repository root)
pnpm dev

# Terminal 2: Run e2e tests (from e2e folder)
pnpm test

If infra is already running, pnpm infra:up is safe to run again. For dev-mode test runs, infra:up also ensures required local Ghost/gateway dev images exist. If you want to force a mode, set GHOST_E2E_MODE=dev or GHOST_E2E_MODE=build explicitly.

Analytics Development Flow

When working on analytics locally, use:

# Terminal 1 (repo root)
pnpm dev:analytics

# Terminal 2
pnpm test:analytics

E2E test scripts automatically sync Tinybird tokens when Tinybird is running.

Build Mode (Prebuilt Image)

Use build mode when you don’t want to run dev servers. It uses a prebuilt Ghost image and serves public assets from /content/files.

# From repository root
pnpm build
pnpm --filter @tryghost/e2e build:apps
GHOST_E2E_BASE_IMAGE=<ghost-image> pnpm --filter @tryghost/e2e build:docker
GHOST_E2E_MODE=build pnpm --filter @tryghost/e2e infra:up

# Run tests
GHOST_E2E_MODE=build GHOST_E2E_IMAGE=ghost-e2e:local pnpm --filter @tryghost/e2e test

Build-mode E2E infra uses tmpfs-backed MySQL storage by default so database snapshot restore cycles stay fast and isolated from local development data. Set GHOST_E2E_MYSQL_TMPFS=false to use the normal Docker volume instead, or GHOST_E2E_MYSQL_TMPFS_SIZE=4g to adjust the tmpfs size.

For a CI-like local preflight (pulls Playwright + gateway images and starts infra), run:

pnpm --filter @tryghost/e2e preflight:build

Running Specific Tests

# Specific test file
pnpm test specific/folder/testfile.spec.ts

# Matching a pattern
pnpm test --grep "homepage"

# With browser visible (for debugging)
pnpm test --debug

Tests Development

The test suite is organized into separate directories for different areas/functions:

Current Test Suites

• tests/public/ - Public-facing site tests (homepage, posts, etc.)
• tests/admin/ - Ghost admin panel tests (login, content creation, settings)

We can decide whether to add additional sub-folders as we add more tests.

Example structure for admin tests:

tests/admin/
├── login.spec.ts
├── posts.spec.ts
└── settings.spec.ts

Project folder structure can be seen below:

e2e/
├── tests/                      # All the tests
│   ├── public/                 # Public site tests
│   │   └── testname.spec.ts    # Test cases
│   ├── admin/                  # Admin site tests
│   │   └── testname.spec.ts    # Test cases
│   ├── global.setup.ts         # Global setup script
│   ├── global.teardown.ts      # Global teardown script
│   └── .eslintrc.js            # Test-specific ESLint config
├── helpers/                    # All helpers that support the tests, utilities, fixtures, page objects etc.
│   ├── playwright/             # Playwright specific helpers
│   │   └── fixture.ts          # Playwright fixtures
│   ├── pages/                  # Page Object Models
│   │   └── HomePage.ts         # Page Object
│   ├── utils/                  # Utils
│   │   └── math.ts             # Math related utils   
│   └── index.ts                # Main exports
├── playwright.config.mjs       # Playwright configuration
├── package.json                # Dependencies and scripts
└── tsconfig.json               # TypeScript configuration

Writing Tests

Tests use Playwright Test. Use Arrange–Act–Assert (AAA) as a readability heuristic: set up the scenario, perform the behavior under test, then verify the outcome. Keep those phases clear through test structure and naming; comments are only useful when the boundaries would otherwise be unclear.

test.describe('Ghost Homepage', () => {
    test('loads correctly', async ({page}) => {
        const homePage = new HomePage(page);

        await homePage.goto();

        await expect(homePage.title).toBeVisible();
    });
});

Using Page Objects

Page Objects are the default home for reusable knowledge about a page or major UI component. They encapsulate locators, readiness guards, and semantic interactions so tests can describe behavior rather than DOM structure. Assertions stay in test files.

Prefer an existing Page Object when a test exercises reusable UI behavior. A direct semantic locator in a test is acceptable for a small, one-off assertion or interaction when creating a Page Object would add indirection without reuse. Structural selectors sometimes remain necessary for iframes, editor internals, generated theme markup, and elements without an accessible role. Keep those inside Page Objects where practical and prefer, in order:

1. Accessible roles, labels, and visible text
2. Stable test IDs
3. Stable structural selectors when no semantic locator exists

Avoid selectors coupled to visual styling, DOM position, or incidental class names. See Playwright's locator guidance and Martin Fowler's Page Object description for background.

// Create a page object for admin login
import type {Locator, Page} from '@playwright/test';

export class AdminLoginPage {
    private readonly pageUrl = '/ghost';
    public readonly emailInput: Locator;
    public readonly passwordInput: Locator;
    public readonly signInButton: Locator;
    
    constructor(private readonly page: Page) {
        this.emailInput = page.getByLabel('Email address');
        this.passwordInput = page.getByLabel('Password');
        this.signInButton = page.getByRole('button', {name: 'Sign in'});
    }

    async goto(urlToVisit = this.pageUrl) {
        await this.page.goto(urlToVisit);
    }
    
    async login(email: string, password: string) {
        await this.emailInput.fill(email);
        await this.passwordInput.fill(password);
        await this.signInButton.click();
    }
}

Global Setup and Teardown

Tests use Project Dependencies to define special tests as global setup and teardown tests:

• Global Setup: tests/global.setup.ts - runs once before all tests
• Global Teardown: tests/global.teardown.ts - runs once after all tests

Playwright Fixtures

Playwright Fixtures are defined in helpers/playwright/fixture.ts and provide reusable test setup/teardown logic. The fixture resolves isolation mode per test file:

• Default: per-file isolation (one Ghost environment cycle per file)
• Opt-in per-test: call usePerTestIsolation() from @/helpers/playwright/isolation at the root of the file
• Forced per-test: any run with fullyParallel: true

Test Isolation

Test isolation is still automatic, but no longer always per-test.

Infrastructure (MySQL, Redis, Mailpit, Tinybird) must already be running before tests start. Use pnpm dev or pnpm --filter @tryghost/e2e infra:up.

Global setup (tests/global.setup.ts) does:

• Cleans up e2e containers and test databases
• Creates a base database, starts Ghost, waits for health, snapshots the DB

Per-file mode (helpers/playwright/fixture.ts) does:

• Clones a new database from snapshot at file boundary
• Restarts Ghost with the new database and waits for readiness
• Reuses that environment for tests in the file

Per-test mode (helpers/playwright/fixture.ts) does:

• Clones a new database from snapshot for each test
• Restarts Ghost with the new database and waits for readiness

Environment identity for per-file reuse:

• config participates in the environment identity.
• labs participates in the environment identity.
• If either changes between tests in the same file, the shared per-file Ghost environment is recycled before reuse.
• stripeEnabled does not participate in per-file reuse. It always forces per-test isolation because Ghost must boot against a per-test fake Stripe server.

Fixture option behavior:

• config: use for boot-time Ghost config that should get a fresh environment when it changes.
• labs: use for labs flags that should get a fresh environment when they change.
• stripeEnabled: use for Stripe-backed tests; this always runs each test with a fully isolated Ghost environment.

Escape hatch:

• resetEnvironment() is supported only in beforeEach hooks for per-file tests.
• Use it only before resolving stateful fixtures such as baseURL, page, pageWithAuthenticatedUser, or ghostAccountOwner.
• Safe hook pattern: test.beforeEach(async ({resetEnvironment}) => { ... })
• Unsupported pattern: calling resetEnvironment() after page or an authenticated session has already been created.
• ESLint catches the obvious misuse cases, but the runtime guard in the fixture remains the hard safety check.

Opting into per-test isolation:

• Use usePerTestIsolation() from @/helpers/playwright/isolation at the root of the file.
• This configures both Playwright parallel mode and the fixture isolation in one call.

Global teardown (tests/global.teardown.ts) does:

• Cleans up e2e containers and test databases (infra services stay running)

Modes:

• Dev mode: Ghost mounts source code and proxies assets to host dev servers
• Build mode: Ghost uses a prebuilt image and serves assets from /content/files

Best Practices

1. Use Page Objects for reusable UI structure and interactions. Direct semantic locators are fine for small, one-off assertions where a Page Object would not improve reuse or readability.
2. Add meaningful assertions beyond just page loads. Keep assertions in tests.
3. Prefer semantic locators, such as getByRole() and getByLabel(). Use stable test IDs when semantic locators are unavailable. Avoid selectors coupled to styling or DOM position.
4. Clean up test data when tests modify Ghost state
5. Group related tests in describe blocks
6. Do not use should to describe test scenarios

CI Integration

Tests run automatically in GitHub Actions on every PR and commit to main.

CI Process

1. Setup: Ubuntu runner with Node.js and Docker
2. Build Assets: Build server/admin assets and public app UMD bundles
3. Build E2E Image: pnpm --filter @tryghost/e2e build:docker (layers public apps into /content/files)
4. Prepare E2E Runtime: Pull Playwright/gateway images in parallel, start infra, and sync Tinybird state (pnpm --filter @tryghost/e2e preflight:build)
5. Test Execution: Run Playwright E2E tests inside the official Playwright container
6. Artifacts: Upload Playwright traces and reports on failure

Available Scripts

Within the e2e directory:

# Run all tests
pnpm test

# Start/stop test infra (MySQL/Redis/Mailpit/Tinybird)
pnpm infra:up
pnpm infra:down

# CI-like preflight for build mode (pulls images + starts infra)
pnpm preflight:build

# Debug failed tests (keeps containers)
PRESERVE_ENV=true pnpm test

# Run TypeScript type checking
pnpm test:types

# Lint code and tests
pnpm lint

# Build (for utilities)
pnpm build
pnpm dev           # Watch mode for TypeScript compilation

Resolving issues

Test Failures

1. Screenshots: Playwright captures screenshots on failure
2. Traces: Available in test-results/ directory
3. Debug Mode: Run with pnpm test --debug or pnpm test --ui to see browser
4. Verbose Logging: Check CI logs for detailed error information