agentleFS
sayurionishisayurionishi/playwright-scaffold/.claude/skills/test-standards/SKILL.md

test-standards

Skill1 starsChanged 3 months agoMITView on GitHub

Use when writing a new spec file, structuring functional vs e2e tests, choosing tags, or deciding what belongs in a test. Defines spec structure, tagging, and independence.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Import from fixtures/test-options only.

    line 39
  2. Very specific:

    Keep a test under ~50 lines and to one behavior (SRP).

    line 65
  3. Very specific:

    Use the structured tag option (Playwright 1.42+) — test('name', { tag: '@smoke' }, async …) — not a tag baked into the title.

    line 70
  4. Distinctive:

    Create your own data (factory/helper fixture).

    line 86
  5. Distinctive:

    Prefer API/fixture teardown over UI cleanup (faster, runs on failure).

    line 91

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Test Standards (spec structure)

Which project / folder

TypeFolder → projectThe SUT
One screen/feature in isolationtests/functional/ → functionala single page
Full multi-feature journeytests/e2e/ → e2ethe whole flow
Backend endpointtests/api/ → apithe API

Functional = many small tests, one behavior each. E2E = ONE test for the whole journey (not one per step).

Structure

import { test, expect } from '../../fixtures/test-options';

test.describe('Products', () => {
  test.beforeEach(async ({ productsPage }) => {
    await productsPage.goto();
  });

  test('creates a product', { tag: '@smoke' }, async ({ productsPage, page }) => {
    await test.step('When I add a product', async () => {
      await productsPage.addProduct('Widget');
    });
    await test.step('Then it appears in the list', async () => {
      await expect(page.getByText('Widget')).toBeVisible();
    });
  });
});
  • Import from fixtures/test-options only.
  • describe per feature; beforeEach for shared arrange; test.step to label the beats.

AAA or Given/When/Then — both fine

test.step labels are for the human reading the report. Use either vocabulary — they are the same three-beat shape, so pick whichever reads better and stay consistent within a file:

ArrangeActAssert← AAA (the api specs use this)
GivenWhenThen← BDD (the UI specs use this)
// AAA
await test.step('Act: create the user', async () => { … });
await test.step('Assert: 201 and body matches the contract', async () => { … });

// BDD
await test.step('When I submit wrong credentials', async () => { … });
await test.step('Then I see an error and stay on /login', async () => { … });
  • Steps are optional. Use them when a test has distinct beats worth labeling; skip them on single-action tests (a one-line GET + status check reads fine without a wrapper) — don't pad.
  • The Act step can return the call's result so the Assert step uses it (see tests/api/users.spec.ts).
  • Web-first assertions only. No waitForTimeout, no networkidle.
  • Keep a test under ~50 lines and to one behavior (SRP). Descriptive names (creates X when Y, not test1).
  • For several independent checks in one test, use soft assertions (expect.soft(...)) so all failures report at once instead of stopping at the first. (docs)

Tagging — exactly one per test

Use the structured tag option (Playwright 1.42+) — test('name', { tag: '@smoke' }, async …) — not a tag baked into the title. It's the modern form and keeps titles clean. (A @tag in the title still works with --grep, but prefer the option.)

@smoke (critical, fast) · @sanity · @regression (broad) · @api · @e2e · @security · @contract (a shape/metadata snapshot, not behavior) · @persona (who can see/do what) · @destructive (mutates shared state — runs --workers=1, wins over any other tag, requires cleanup). Tag the test, never the describe. npm run test:smoke etc. filter by tag via --grep. (tag docs)

@contract and @persona exist mainly for the salesforce profile, where metadata drift and the permission matrix are distinct test types you want to run on their own cadence — contract checks on every push, the persona matrix before a permissions release. They're profile-agnostic though: any app with a generated contract or a role model can use them. See salesforce-metadata-contract / salesforce-personas.

Independence (parallel-safe)

  • Tests run in any order, in parallel. No test depends on another's side effects.
  • Create your own data (factory/helper fixture); clean it up in teardown (runs on failure).
  • @destructive tests that touch shared state must restore it in afterEach/afterAll.

Cleanup

Prefer API/fixture teardown over UI cleanup (faster, runs on failure). Never leave data behind.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.