Module @clipboard-health/playwright-flake-linter

@clipboard-health/playwright-flake-linter

Shared, configurable TypeScript AST checks for Playwright flake anti-patterns. The rule implementation lives in this package; consuming repositories provide only their paths, helper names, mechanism names, and justified exceptions.

Install

npm install --save-dev @clipboard-health/playwright-flake-linter

TypeScript is a runtime dependency because the checker uses the compiler API; glob provides the repository-standard source discovery used by embedex. Both are actively maintained, commercially compatible (Apache-2.0 and ISC), already standardized in this monorepo, and the CLI is not included in application bundles.

Configure

Create playwright-flake-lint.config.mjs at the repository root:

export default {
  scanRoots: ["playwright"],
  hardenedIdentityHelperNames: ["generateRandomUserEmail"],
  identityHelperMinimumLengths: {
    generateRandomAlphaNumericString: 24,
    generateRandomString: 26,
  },
  retryHelperNames: ["retry"],
  specificRequestMatcherNames: ["isMatchingRequest"],
  transientClassifierNamePatterns: ["^isRetryable", "retryClassification"],
  undiscriminatingRetryHelperNames: ["retryUntilPassOrTimeout", "toPass"],
  sharedReadinessMechanisms: [
    {
      name: "Home Health response readiness",
      filePathPattern: "playwright/e2e/homeHealth/.*\\.spec\\.ts$",
      directCallNames: ["waitForResponse"],
      sharedHelperNames: ["waitForHomeHealthResponse"],
    },
  ],
};

The mobile repository can use its own genuine names without changing a rule:

export default {
  scanRoots: ["playwright"],
  identityHelperMinimumLengths: {
    mobileRandomSuffix: 32,
  },
  retryHelperNames: ["retryMobileAction"],
  specificRequestMatcherNames: ["matchesMobileRequest"],
  transientClassifierNamePatterns: ["^isTransientMobile"],
  sharedReadinessMechanisms: [
    {
      name: "BottomSheet readiness",
      filePathPattern: "playwright/e2e/sheets/.*\\.spec\\.ts$",
      directCallNames: ["waitForResponse"],
      sharedHelperNames: ["waitForBottomSheet"],
    },
  ],
};

All pattern fields are JavaScript regular-expression source strings. Optional configuration:

Field	Purpose
`allowlist`	Reason-required repository exceptions by rule and file pattern
`hardenedIdentityHelperNames`	Identity helpers that are safe without a length argument
`identityHelperMinimumLengths`	Repository random-helper names and their safe minimum lengths
`identityNamePattern`	Names treated as parallel-worker-sensitive identities
`responseWaitCallNames`	Repository response-wait utility names
`retryHelperNames`	Retry utilities whose callbacks must classify transient failures
`sharedReadinessMechanisms`	File/mechanism registry mapping direct gates to shared helpers
`specificRequestMatcherNames`	Delegated helpers that fully discriminate a response request
`specFilePattern`	Files where fixed-sleep checks apply
`transientClassifierNamePatterns`	Classifier names accepted inside retry callbacks
`undiscriminatingRetryHelperNames`	Utilities that inherently retry any failure and are always rejected

sharedReadinessMechanisms[].name is the diagnostic label, so repositories can use their native terminology such as Dialog or BottomSheet.

Wire into CI

Add the executable to the repository's existing verification chain:

{
  "scripts": {
    "architecture:check": "existing-checks && playwright-flake-lint"
  }
}

Use a non-default config location with playwright-flake-lint --config path/to/config.mjs.

Rules

Rule ID	Anti-pattern	Required alternative
`fixed-sleep`	`waitForTimeout` or `setTimeout` delays in specs	Rubric B2: use a deterministic readiness signal
`response-wait`	Status/`.ok()` response predicates without specific request data	Rubric B2: match method, URL, and a discriminating request predicate
`retry-classification`	Retry utilities invoked without transient-only classification	Rubric B1: classify transient failures and fail fast otherwise
`test-data-identity`	Low-entropy identities or bypasses of hardened random helpers	Rubric A2: use configured hardened or UUID-backed identities
`shared-readiness`	Per-spec readiness gates where a shared mechanism helper exists	Rubric A1: use or extend the configured shared helper

Allowlisting

Prefer fixing a violation. A justified inline exception must immediately precede the violating statement and include a reason:

// flake-lint-allow fixed-sleep -- The timer fixture verifies elapsed product time.
await page.waitForTimeout(100);

A repository-level exception also requires a reason:

export default {
  scanRoots: ["playwright"],
  allowlist: [
    {
      ruleId: "fixed-sleep",
      filePathPattern: "playwright/e2e/legacy/timer\\.spec\\.ts$",
      reason: "The timer fixture verifies elapsed product time.",
    },
  ],
};

Comments or config entries without a non-empty reason do not suppress a violation.

Future shared rules

The existing per-repository Dialog/query-list checks are a candidate for this package. Their component-name difference (Dialog in admin and BottomSheet in mobile) belongs in repository config when that rule is migrated; this package does not change those checks yet.