@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.