AGENTS.md

1# AGENTS.md
2 
3E2E testing guidance for AI assistants (Claude, Codex, etc.) working with Ghost tests.
4 
5**IMPORTANT**: When creating or modifying E2E tests, always refer to `./.claude/E2E_TEST_WRITING_GUIDE.md` for comprehensive testing guidelines and patterns.
6 
7## Critical Rules
81. **Always follow ADRs** in `../adr/` folder (ADR-0001: AAA pattern, ADR-0002: Page Objects)
92. **Always use pnpm**, never npm
103. **Always run after changes**: `pnpm lint` and `pnpm test:types`
114. **Never use CSS/XPath selectors** - only semantic locators or data-testid
125. **Prefer less comments and giving things clear names**
13 
14## Running E2E Tests
15 
16**`pnpm dev` must be running before you run E2E tests.** The E2E test runner auto-detects
17whether the admin dev server is reachable at `http://127.0.0.1:5174`. If it is, tests run
18in **dev mode** (fast, no pre-built Docker image required). If not, tests fall back to
19**build mode** which requires a `ghost-e2e:local` Docker image that is only built in CI.
20 
21**If you see the error `Build image not found: ghost-e2e:local`, it means `pnpm dev` is
22not running.** Start it first, wait for the admin dev server to be ready, then re-run tests.
23 
24```bash
25# Terminal 1 (or background): Start dev environment from the repo root
26pnpm dev
27 
28# Wait for the admin dev server to be reachable (http://127.0.0.1:5174)
29 
30# Terminal 2: Run e2e tests from the e2e/ directory
31pnpm test                                       # Run all tests
32pnpm test tests/path/to/test.ts                 # Run specific test
33pnpm lint                                       # Required after writing tests
34pnpm test:types                                 # Check TypeScript errors
35pnpm build                                      # Required after factory changes
36pnpm test --debug                               # See browser during execution, for debugging
37PRESERVE_ENV=true pnpm test                     # Debug failed tests (keeps containers)
38```
39## Test Structure
40 
41### Naming Conventions
42- **Test suites**: `Ghost Admin - Feature` or `Ghost Public - Feature`
43- **Test names**: `what is tested - expected outcome` (lowercase)
44- **One test = one scenario** (never mix multiple scenarios)
45 
46### AAA Pattern
47```typescript
48test('action performed - expected result', async ({page}) => {
49    const analyticsPage = new AnalyticsGrowthPage(page);
50    const postFactory = createPostFactory(page.request);
51    const post = await postFactory.create({status: 'published'});
52 
53    await analyticsPage.goto();
54    await analyticsPage.topContent.postsButton.click();
55 
56    await expect(analyticsPage.topContent.contentCard).toContainText('No conversions');
57});
58```
59 
60## Page Objects
61 
62### Structure
63```typescript
64export class AnalyticsPage extends AdminPage {
65    // Public readonly locators only
66    public readonly saveButton = this.page.getByRole('button', {name: 'Save'});
67    public readonly emailInput = this.page.getByLabel('Email');
68 
69    // Semantic action methods
70    async saveSettings() {
71        await this.saveButton.click();
72    }
73}
74```
75 
76### Rules
77- Page Objects are located in `helpers/pages/`
78- Expose locators as `public readonly` when used with assertions
79- Methods use semantic names (`login()` not `clickLoginButton()`)
80- Use `waitFor()` for guards, never `expect()` in page objects
81- Keep all assertions in test files
82 
83## Locators (Strict Priority)
84 
851. **Semantic** (always prefer):
86   - `getByRole('button', {name: 'Save'})`
87   - `getByLabel('Email')`
88   - `getByText('Success')`
89 
902. **Test IDs** (when semantic unavailable):
91   - `getByTestId('analytics-card')`
92   - Suggest adding `data-testid` to Ghost codebase when needed
93 
943. **Never use**: CSS selectors, XPath, nth-child, class names
95 
96### Playwright MCP Usage
97- Use `mcp__playwright__browser_snapshot` to find elements
98- Use `mcp__playwright__browser_click` with semantic descriptions
99- If no good locator exists, suggest `data-testid` addition to Ghost
100 
101## Test Data
102 
103### Factory Pattern (Required)
104```typescript
105import {PostFactory, UserFactory} from '../data-factory';
106 
107const postFactory = createPostFactory(page.request);
108const post = await postFactory.create({userId: user.id});
109```
110 
111## Best Practices
112 
113### DO ✅
114- Use `usePerTestIsolation()` from `@/helpers/playwright/isolation` if a file needs per-test isolation
115- Treat `config` and `labs` as environment-identity inputs: changing them should be an intentional part of test setup
116- Use `resetEnvironment()` only in `beforeEach` hooks when you need a forced recycle inside per-file mode
117- Keep `stripeEnabled` tests in per-test mode; the fixture forces this automatically
118- Use factories for all test data
119- Use Playwright's auto-waiting
120- Run tests multiple times to ensure stability
121- Use `test.only()` for debugging single tests
122 
123### DON'T ❌
124- Use `test.describe.parallel(...)` or `test.describe.serial(...)` in e2e tests
125- Use nested `test.describe.configure({mode: ...})` (mode toggles are root-level only)
126- Call `resetEnvironment()` after resolving `baseURL`, `page`, `pageWithAuthenticatedUser`, or `ghostAccountOwner`
127- Hard-coded waits (`waitForTimeout`)
128- networkidle in waits (`networkidle`)
129- Test dependencies (Test B needs Test A)
130- Direct database manipulation
131- Multiple scenarios in one test
132- Assertions in page objects
133- Manual login (auto-authenticated via fixture)
134 
135## Project Structure
136- `tests/admin/` - Admin area tests
137- `tests/public/` - Public site tests
138- `helpers/pages/` - Page objects
139- `helpers/environment/` - Container management
140- `data-factory/` - Test data factories
141 
142## Validation Checklist
143After writing tests, verify:
1441. Test passes: `pnpm test path/to/test.ts`
1452. Linting passes: `pnpm lint`
1463. Types check: `pnpm test:types`
1474. Follows AAA pattern with clear sections
1485. Uses page objects appropriately
1496. Uses semantic locators or data-testid only
1507. No hard-coded waits or CSS selectors
151