Gate Framework Patterns

Gate 4: framework-patterns

Is this still part of this framework?

Code that works but ignores the repo's conventions is a slow leak: every such file makes the next one easier to write the wrong way. These rules are specific to AdvancePlaywrightFramework2x. Verify each against the current source before citing it.

Specs

1. Import from @fixtures/test-base, never @playwright/test. API and AI specs may use @fixtures/booker.fixture. A spec importing @playwright/test directly has opted out of every page-object and state fixture.
2. Never new SomePage(page) in a spec. Take it from a fixture parameter.
3. No locators in specs. They live in src/pages/*.ts as private readonly fields.
4. Spec filenames need a dot: *.spec.ts. 05_crud_spec.ts with an underscore is silently never collected. It does not fail; it does not exist. A numeric prefix is fine because it sits before the dot.

Page objects

5. Extend BasePage with super(page, 'ClassName'), expose a static readonly PATH, and act through this.el.* (UtilElementLocator), never locator.click() directly. That wrapper is what logs every action.

Project scoping (the trap that recurs)

6. A new test directory needs its project decided at the same moment it is created. Three projects exist:

chromium sets testIgnore: ['**/apisTests/**', '**/aiTest/**']. Add a fourth directory without touching this and it either runs twice, runs against the wrong host, or is invisible. All three have happened.

Config and environment

7. Read env through @config/env (requireEnv / envOr / assertEnv). Never dotenv.config() in a spec: Babel hoists imports above it, so modules reading process.env at load time see nothing.
8. Credentials come from @config/credentials or @testdata/logintestdata.json. Never hard-coded.
9. Never commit a key. .env is gitignored; new variables get a blank placeholder in .env.example, which CI copies to .env.

Libraries

10. ajv + ajv-formats for schemas, jsonpath-plus for JSON queries. Zod is not a dependency and adding it needs an argument. Schemas live in src/testdata/schemas/, draft-07, because Ajv 8's default export only knows draft-07.
11. Log with createLogger('<scope>') from @utils/logger, one scope per file.
12. Errors carry a [ClassName] prefix, as in [BookingApi] GET /booking failed: 404.

Path aliases

13. @api/* @config/* @fixtures/* @pages/* @testdata/* @utils/* map to src/*. Relative imports across directories are the exception.

The AI layer

14. No test may pass or fail on model output. Assert on schema validity, HTTP status, or a verified locator. A test whose result rides on a sampled token is not a test.
15. The suite must stay green with no API key. That is CI's normal state. Agents return an unavailable result; nothing throws.
16. A new agent is a prompt plus a schema through createAgent. New transport code means the factory was bypassed.
17. Self-healing suggests and verifies; it never rewrites a spec.
18. Demo specs that fail on purpose are gated behind AI_DEMO.

Docs

19. No em dashes, anywhere. Use a comma, colon, parentheses or ->.
20. Update all four sync points when adding a module: the section, the level table, the project tree, and the env-keys table. Partial updates rot.

CI and tooling

21. In CI, call the local binary, never npx. On a checkout where a tool is not a declared dependency, npx <tool> silently downloads an unrelated package of the same name from the registry and runs it. This gate's own first CI run did exactly that: npx tsc fetched tsc@2.0.4 and failed with "This is not the tsc command you are looking for". Use ./node_modules/.bin/tsc or an npm script.
22. Every tool the build needs is a declared dependency. typescript was absent from package.json for most of this repo's life, arriving transitively, which is what made the above possible.

Evidence required

npm run verify                              # typecheck, lint, suite
npx playwright test --project=<p> --list    # proves a new spec is actually collected

--list is the cheapest check that a new file exists as far as the runner is concerned. If it is absent from the listing, nothing in the file body can be at fault yet.

Verdict

FAIL on any spec importing @playwright/test directly, any locator in a spec, any new test directory without a project decision, any hard-coded credential, any test asserting on model output, or a suite that needs a key to pass.