suaveplan/openspec/changes/swap-testing-e2e-cloakbrowser/specs/testing-e2e/spec.md

# testing-e2e — delta (swap-testing-e2e-cloakbrowser)

## ADDED Requirements

### Requirement: Cloakserve CDP connect helper

The package MUST expose `@suaveplan/testing-e2e/cloakserve` (also
re-exported from the package root) providing `connectCloakServe(options, chromium?)`
and `buildCloakServeUrl(options)`. The URL builder MUST map camelCase
option keys to cloakserve's kebab-case query-string keys
(`hardwareConcurrency` → `hardware-concurrency`, etc.), stringify
booleans, skip `undefined`/`null` values, and default the base URL to
`http://localhost:9222`. `connectCloakServe` MUST inject `@playwright/test`'s
`chromium` by default with a lazy dynamic-import cache, and wrap any
`connectOverCDP` rejection in a `CloakLaunchError` whose `context`
carries `{ cloakServeUrl }`.

#### Scenario: buildCloakServeUrl maps keys and base URL

- **WHEN** `buildCloakServeUrl({ fingerprint: 42, hardwareConcurrency: 8, geoip: true })` is called
- **THEN** the result equals `http://localhost:9222/?fingerprint=42&hardware-concurrency=8&geoip=true` (param order is preserved)

**Verified by:** `src/cloakserve/build-cloakserve-url.test.ts::"appends fingerprint seed"` AND `src/cloakserve/build-cloakserve-url.test.ts::"maps camelCase to kebab-case"` AND `src/cloakserve/build-cloakserve-url.test.ts::"stringifies booleans"`

#### Scenario: connectCloakServe forwards options and returns the Browser

- **WHEN** `connectCloakServe({ fingerprint: 11111, timezone: "America/New_York" }, injectedDriver)` is called
- **THEN** `injectedDriver.connectOverCDP` is called with a URL containing `fingerprint=11111` and `timezone=America%2FNew_York`, and the returned `Browser` is the injected fake

**Verified by:** `src/cloakserve/cloakserve-connect.test.ts::"uses injected chromium and builds the cloakserve URL"`

#### Scenario: connectCloakServe wraps errors

- **WHEN** the underlying `connectOverCDP` rejects with `ECONNREFUSED`
- **THEN** `connectCloakServe` rethrows a `CloakLaunchError` with
  `code === TESTING_E2E.CLOAK.PROXY_INVALID` and
  `context.cloakServeUrl` set to the URL that was attempted

**Verified by:** `src/cloakserve/cloakserve-connect.test.ts::"wraps connection errors in CloakLaunchError"` AND `src/cloakserve/cloakserve-connect.test.ts::"classifies generic connect errors as LAUNCH_FAILED"`

### Requirement: Stealth presets

The package MUST expose `@suaveplan/testing-e2e/presets` (also
re-exported from the package root) providing frozen `STEALTH_DEFAULT_CLOAK`
(`{ headless: true }`) and `STEALTH_HEADED_CLOAK`
(`{ headless: false, humanize: true }`) plus `stealthMax(proxy)` and
`stealthMaxHeadless(proxy)` factories that return fresh objects on
every call. `stealthMax(proxy)` MUST return
`{ headless: false, humanize: true, geoip: true, proxy }` — exactly
matching the CloakBrowser README's "Recommended config for anti-bot
sites" block.

#### Scenario: stealthMax matches the upstream recommendation

- **WHEN** `stealthMax("http://proxy:8080")` is called
- **THEN** the result is `{ headless: false, humanize: true, geoip: true, proxy: "http://proxy:8080" }`

**Verified by:** `src/presets/stealth-presets.test.ts::"matches the upstream recommended config"`

#### Scenario: static presets are frozen

- **WHEN** `Object.isFrozen(STEALTH_DEFAULT_CLOAK)` is checked
- **THEN** it is `true` (and same for `STEALTH_HEADED_CLOAK`)

**Verified by:** `src/presets/stealth-presets.test.ts::"is headless and frozen"` AND `src/presets/stealth-presets.test.ts::"is headed + humanized and frozen"`

### Requirement: `waitForTimeout` lint guard

The package's source-guard test MUST flag `waitForTimeout` and
`wait_for_timeout` calls anywhere under `src/` (excluding `.test.ts`
and `.bench.ts`). Both forms emit CDP protocol traffic that
reCAPTCHA v3 / Enterprise behavioural scorers detect — the upstream
CloakBrowser README documents this as a primary cause of low scores.

#### Scenario: guard fires on a synthetic violation

- **WHEN** the `no-disallowed source guard` test runs against the
  current `src/` tree
- **THEN** the test passes (no violations) AND the `PATTERNS` array
  contains entries named `waitForTimeout` and `wait_for_timeout`

**Verified by:** `tests/no-disallowed.test.ts::"src/ contains no disallowed constructs"`

### Requirement: Docker bundle

The package MUST ship a `docker/` directory containing
`Dockerfile.cloakserve` (extending `cloakhq/cloakbrowser`, installing
the Kasada / Akamai font set, running `cloakserve` on `9222`),
`Dockerfile.manager` (extending `cloakhq/cloakbrowser-manager`,
exposing 8080 with a `cloakprofiles` named volume),
`docker-compose.yml` (both services bound to `127.0.0.1`, manager
behind the `manager` compose profile, named volume defined),
`.env.example` (`CLOAKBROWSER_TAG`, `MANAGER_TAG`,
`MANAGER_AUTH_TOKEN`), and a `docker/README.md` operator playbook.
Both Dockerfiles MUST declare a healthcheck.

#### Scenario: cloakserve Dockerfile builds on the upstream image and exposes 9222

- **WHEN** `docker build -f docker/Dockerfile.cloakserve` is run
- **THEN** the resulting image is layered on `cloakhq/cloakbrowser`,
  exposes port `9222`, defaults its CMD to `cloakserve`, and runs the
  documented font-install step

**Verified by:** manual operator verification (`docker compose up cloakserve` + smoke connect via `connectCloakServe`); source-level invariants are enforced by reading the Dockerfile in CI is out of scope for this change

### Requirement: CLOAK_* error codes

The package MUST emit `CloakLaunchError extends TestingE2eError` with
codes `TESTING_E2E.CLOAK.LAUNCH_FAILED`,
`TESTING_E2E.CLOAK.BINARY_MISSING`, and
`TESTING_E2E.CLOAK.PROXY_INVALID`. All three codes MUST appear in the
exported `TESTING_E2E_ERROR_CODES` registry and conform to
`TESTING_E2E_ERROR_CODE_PATTERN`.

#### Scenario: codes registered

- **WHEN** `TESTING_E2E_ERROR_CODES` is iterated
- **THEN** the three CLOAK codes are present and each matches the
  registry pattern

**Verified by:** `src/errors/testing-e2e-error.test.ts::"registers CLOAK_* codes"` AND `src/errors/testing-e2e-error.test.ts::"CloakLaunchError exposes the LAUNCH_FAILED code by default"`

#### Scenario: BINARY_MISSING raised when cloakbrowser binary not present

- **WHEN** the underlying cloakbrowser launcher throws an error whose
  message includes `binary not found`, `ENOENT`, or `Failed to download`
- **THEN** the calling fixture rethrows a `CloakLaunchError` with code
  `TESTING_E2E.CLOAK.BINARY_MISSING`, the original error as `cause`,
  and a remediation hint pointing to `npx cloakbrowser install`

**Verified by:** `src/errors/testing-e2e-error.test.ts::"classifyCloakError maps ENOENT to BINARY_MISSING"`

## MODIFIED Requirements

### Requirement: Layer 0 dep-graph isolation

The `@suaveplan/testing-e2e` `dependencies` and `peerDependencies` MUST
NOT contain any `@suaveplan/*` workspace package. `dependencies` MUST
include `cloakbrowser` (any valid range — direct or `catalog:testing`)
alongside the existing `@playwright/test`, `@opentelemetry/api`,
`tslib`, and `zod` entries. `devDependencies` MAY include
`@suaveplan/testing` for the package's own tests.

#### Scenario: runtime closure clean and contains cloakbrowser

- **WHEN** `bunx turbo ls --filter=@suaveplan/testing-e2e...` is run
- **THEN** no `@suaveplan/*` package appears in the runtime closure
  AND `cloakbrowser` is present as a direct dependency

**Verified by:** `tests/dep-graph.test.ts::"no @suaveplan/* in dependencies or peerDependencies"` AND `tests/dep-graph.test.ts::"cloakbrowser is a direct dependency"`

### Requirement: `extendedTest` default browser is stealth

`extendedTest.browser` MUST be overridden so the default browser used
by every fixture downstream (`freshPage`, consumer-extended fixtures)
launches via `cloakbrowser.launch()` (drop-in for stock chromium).
The override MUST honour `testInfo.project.use.cloak` if defined,
otherwise launch with cloakbrowser defaults (`headless: true`, stealth
args on). The launcher MUST be injectable for unit testing — the
fixture takes an internal default but exposes the launcher symbol on
the `cloak` worker fixture so tests can supply a spy.

#### Scenario: default browser is cloakbrowser

- **WHEN** a test runs under `extendedTest` with no per-project
  override
- **THEN** the `browser` fixture is produced by the cloakbrowser
  `launch` function (identity check via injected spy)

**Verified by:** `src/fixtures/extended-test.test.ts::"browser fixture is launched via cloakbrowser launch"` AND `src/fixtures/extended-test.test.ts::"cloak options from testInfo.project.use.cloak flow into launch"`

#### Scenario: errors map to CloakLaunchError

- **WHEN** the underlying cloakbrowser launcher throws
- **THEN** the fixture rethrows a `CloakLaunchError` with a classified
  code (`LAUNCH_FAILED`, `BINARY_MISSING`, or `PROXY_INVALID`)

**Verified by:** `src/fixtures/extended-test.test.ts::"wraps launch errors in CloakLaunchError"`

### Requirement: Extension fixture uses cloakbrowser launchPersistentContext

`launchWithExtension` MUST accept a `launchPersistentContext` function
parameter (default: cloakbrowser's). The legacy
`chromium: BrowserType` parameter is removed. Extension args
(`--disable-extensions-except`, `--load-extension`) and userDataDir
behaviour are unchanged.

#### Scenario: default launcher is cloakbrowser

- **WHEN** `launchWithExtension({ extensionPath, userDataDir })` is
  called with no explicit launcher
- **THEN** `cloakbrowser.launchPersistentContext` is invoked with the
  expected `userDataDir` and Chromium args

**Verified by:** `src/extension-fixture/launch-with-extension.test.ts::"defaults to cloakbrowser launchPersistentContext"`

#### Scenario: launcher is injectable

- **WHEN** `launchWithExtension({ launchPersistentContext: spy, extensionPath, userDataDir })` is called
- **THEN** the provided `spy` is invoked exactly once with the
  expected `userDataDir` and Chromium args

**Verified by:** `src/extension-fixture/launch-with-extension.test.ts::"uses injected launcher when provided"`

#### Scenario: launchPersistentContext errors map to CloakLaunchError

- **WHEN** the underlying launcher throws an error matching the
  `ENOENT`/binary classifier
- **THEN** `launchWithExtension` rethrows a `CloakLaunchError` with
  `code === TESTING_E2E.CLOAK.BINARY_MISSING`

**Verified by:** `src/extension-fixture/launch-with-extension.test.ts::"wraps launcher errors with CloakLaunchError"`