@qaguardian/playwright-score 0.1.2 → 0.1.10

package/README.md

@@ -1,5 +1,9 @@
 # @qaguardian/playwright-score
 
+[![CI](https://github.com/qa-guardian/playwright-score/actions/workflows/ci.yml/badge.svg)](https://github.com/qa-guardian/playwright-score/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@qaguardian/playwright-score.svg)](https://www.npmjs.com/package/@qaguardian/playwright-score)
+[![license](https://img.shields.io/npm/l/@qaguardian/playwright-score.svg)](./LICENSE)
+
 **Deterministic, AI-free quality score for Playwright specs** (`sqs-v1`).
 
 **Website:** [qaguardian.com/open-source/playwright-score](https://qaguardian.com/open-source/playwright-score)  
@@ -56,7 +60,35 @@ const result = await scorePaths({
 console.log(result.score, result.grade, result.pass, result.findings);
 ```
 
-## CI example
+## GitHub Action
+
+Drop this into a workflow to gate PRs on the score, post a job summary, and
+keep a sticky PR comment with the full findings up to date:
+
+```yaml
+- uses: qa-guardian/playwright-score@v1
+  with:
+    paths: tests e2e
+    profile: standard      # or guardian
+    # threshold: 80        # defaults to the profile's default
+    mode: gate              # gate: fail CI below threshold · warn: report only
+```
+
+| Input | Description | Default |
+|---|---|---|
+| `paths` | Space-separated paths/globs to score | `tests` |
+| `profile` | `standard` \| `guardian` | `standard` |
+| `threshold` | Pass bar 0–100 | profile default (80 / 75) |
+| `mode` | `gate` (fail CI below threshold) \| `warn` (report only) | `gate` |
+| `comment` | Post/update a sticky PR comment | `true` |
+| `version` | `@qaguardian/playwright-score` version to run | `latest` |
+| `github-token` | Token for the PR comment | `${{ github.token }}` |
+
+Outputs: `score`, `grade`, `pass` — usable by downstream steps (e.g. a
+custom badge, a Slack notification on regression, etc).
+
+Prefer a raw CLI call, or a non-GitHub CI system? See the [CLI](#cli)
+section above — same score, same exit codes:
 
 ```yaml
 - name: Playwright Spec Score

package/dist/cli.js

@@ -44,7 +44,7 @@ async function main() {
             console.log(pkg.version ?? '0.0.0');
         }
         catch {
-            console.log('0.1.1');
+            console.log('0.1.8');
         }
         process.exit(0);
     }

package/dist/eslint-runner.d.ts

@@ -7,4 +7,6 @@ export declare function runEslint(options: {
     files: string[];
     profile: ProfileName;
     cwd?: string;
+    /** See findLocalAssertionHelperNames in metrics.ts. */
+    assertFunctionNames?: string[];
 }): Promise<Finding[]>;

package/dist/eslint-runner.js

@@ -3,8 +3,9 @@ import { ESLint } from 'eslint';
 import { commonAncestorDir } from './fs-util.js';
 import playwright from 'eslint-plugin-playwright';
 import { guardianPlugin, guardianRuleConfigs, } from './rules/guardian-plugin.js';
+import { basePlugin } from './rules/base-plugin.js';
 import { mapRule } from './profiles.js';
-function buildConfig(profile) {
+function buildConfig(profile, assertFunctionNames) {
     const playwrightRecommended = playwright.configs?.['flat/recommended'] ??
         playwright.configs?.recommended;
     const base = [
@@ -17,21 +18,79 @@ function buildConfig(profile) {
             },
             plugins: {
                 playwright,
+                pwscore: basePlugin,
                 ...(profile === 'guardian' ? { guardian: guardianPlugin } : {}),
             },
             rules: {
-                // Ensure key hygiene rules even if recommended set differs by version
+                // Ensure key hygiene rules even if recommended set differs by
+                // version. A few (no-wait-for-timeout, no-force-option,
+                // no-wait-for-selector, expect-expect) are intentionally stricter
+                // than eslint-plugin-playwright's own "recommended" severity —
+                // these are patterns Playwright's own docs call out as anti-
+                // patterns (see playwright.dev/docs/best-practices), so sqs-v1
+                // treats them as errors rather than warnings. no-networkidle and
+                // no-raw-locators aren't part of upstream "recommended" at all but
+                // are enabled here for the same reason.
                 'playwright/no-wait-for-timeout': 'error',
                 'playwright/no-networkidle': 'error',
                 'playwright/no-force-option': 'error',
                 'playwright/no-wait-for-selector': 'error',
                 'playwright/no-wait-for-navigation': 'error',
                 'playwright/missing-playwright-await': 'error',
-                'playwright/expect-expect': 'error',
+                // expect-expect can only see expect(...) calls written directly in
+                // the test body — it has no way to trace an assertion made inside
+                // a helper function the test calls. assertFunctionNames is
+                // populated per-run (see index.ts's findLocalAssertionHelperNames)
+                // with every same-file helper whose own body actually contains an
+                // expect(...)-shaped call, so this is name-agnostic for the common
+                // case regardless of what the helper is called. assertFunctionPatterns
+                // is a secondary, name-based fallback for helpers imported from
+                // another file (which we can't inspect the body of) — patterns are
+                // camelCase/exact-anchored so e.g. "checkoutFlow" doesn't collide
+                // with "check*"; the suffix pattern catches any name embedding a
+                // real Playwright matcher name (toBeVisible, toHaveText, ...).
+                // Verified against several real production files using several
+                // different naming conventions for the exact same delegation shape
+                // (audit, expectRealButtonToBeVisible, alertToBeVisible,
+                // checkFlashMessageVisibility) — all previously false-positived as
+                // "no assertions" at error severity.
+                'playwright/expect-expect': [
+                    'error',
+                    {
+                        assertFunctionNames,
+                        assertFunctionPatterns: [
+                            '^(assert|verify|validate|audit|expect)([A-Z]|$)',
+                            '^checkA11y$',
+                            '^checkAccessibility$',
+                            '(ToBe|ToHave|ToContain|ToMatch|ToEqual)[A-Z]',
+                        ],
+                    },
+                ],
                 'playwright/no-focused-test': 'error',
-                'playwright/no-skipped-test': 'warn',
+                // Upstream flags every test.skip(...) form identically, including
+                // Playwright's own documented conditional runtime skip
+                // (test.skip(condition, reason)) — a false positive on entirely
+                // idiomatic cross-browser test code, verified against real-world
+                // suites. pwscore/no-skipped-test-declaration (below) replaces it
+                // with the same severity for the actual anti-pattern (an
+                // always-skipped test declaration) only.
+                'playwright/no-skipped-test': 'off',
+                'pwscore/no-skipped-test-declaration': 'warn',
                 'playwright/no-raw-locators': 'warn',
-                'playwright/prefer-web-first-assertions': 'warn',
+                // Both were mapped in profiles.ts (report-only, so they don't
+                // double-penalize the ratio-based locators dimension) but never
+                // actually enabled anywhere — completely inert. prefer-locator
+                // specifically catches Playwright's older direct-action API
+                // (page.click('#foo') instead of a locator or native locator),
+                // arguably the single most common raw-selector anti-pattern in
+                // naive/AI-generated code — verified against a realistic sample
+                // that scored a perfect 100 on the locators dimension despite
+                // using nothing but page.click(selector)/page.type(selector, ...)
+                // throughout, before this fix.
+                'playwright/prefer-locator': 'warn',
+                'playwright/prefer-native-locators': 'warn',
+                // Matches eslint-plugin-playwright's own recommended severity.
+                'playwright/prefer-web-first-assertions': 'error',
                 ...(profile === 'guardian' ? { ...guardianRuleConfigs } : {}),
             },
         },
@@ -79,7 +138,7 @@ export async function runEslint(options) {
     const cwd = options.files.length > 0
         ? commonAncestorDir(options.files)
         : (options.cwd ?? process.cwd());
-    const overrideConfig = buildConfig(options.profile);
+    const overrideConfig = buildConfig(options.profile, options.assertFunctionNames ?? []);
     // Try to attach typescript-eslint parser for .ts files
     try {
         const tsParser = await import('@typescript-eslint/parser');
@@ -110,8 +169,39 @@ export async function runEslint(options) {
     const results = await eslint.lintFiles(options.files);
     const findings = [];
     for (const result of results) {
-        const file = path.resolve(result.filePath);
+        const absFile = path.resolve(result.filePath);
+        const file = path.relative(cwd, absFile) || path.basename(absFile);
         for (const msg of result.messages) {
+            // A `// eslint-disable-next-line some/rule-we-dont-bundle` comment is
+            // extremely common in real-world code (any host project that lints
+            // with plugins we don't embed, e.g. react-hooks, import, sonarjs, or
+            // even @typescript-eslint's own rules — we only bundle its parser,
+            // not its rule set). ESLint reports these with a fixed message
+            // regardless of reportUnusedDisableDirectives config, since it can't
+            // even validate a rule id it has no definition for. This is a
+            // diagnostic about *our* rule coverage, not the spec's quality —
+            // surfacing it as a finding (even report-only) is pure confusion,
+            // not signal.
+            if (/^Definition for rule '.*' was not found\.$/.test(msg.message)) {
+                continue;
+            }
+            if (msg.fatal) {
+                // A file that doesn't parse can't be meaningfully scored at all —
+                // surface it explicitly rather than silently dropping it (it has
+                // no ruleId) and letting an unparseable file default to a clean
+                // 100. scorePaths hard-fails the whole result when this rule id
+                // is present.
+                findings.push({
+                    rule: 'playwright-score/parse-error',
+                    severity: 'error',
+                    message: msg.message,
+                    file,
+                    line: msg.line,
+                    column: msg.column,
+                    dimension: 'structure',
+                });
+                continue;
+            }
             if (!msg.ruleId)
                 continue;
             const mapping = mapRule(msg.ruleId);

package/dist/formatters/markdown.js

@@ -22,5 +22,15 @@ export function formatMarkdown(result) {
             lines.push(`- **${f.severity}** \`${f.rule}\` \`${f.file}${loc}\` — ${f.message}`);
         }
     }
+    if (result.skippedFiles?.length) {
+        lines.push('');
+        lines.push(`<details><summary>Skipped — looks like a non-Playwright test (Jest/Vitest/RTL) (${result.skippedFiles.length})</summary>`);
+        lines.push('');
+        for (const f of result.skippedFiles) {
+            lines.push(`- \`${f}\``);
+        }
+        lines.push('');
+        lines.push('</details>');
+    }
     return lines.join('\n');
 }

package/dist/formatters/sarif.js

@@ -17,7 +17,7 @@ export function formatSarif(result) {
                 tool: {
                     driver: {
                         name: 'playwright-score',
-                        informationUri: 'https://github.com/qaguardian/playwright-score',
+                        informationUri: 'https://github.com/qa-guardian/playwright-score',
                         version: result.scoreVersion,
                         rules: [...rulesMap.values()],
                     },

package/dist/formatters/text.js

@@ -24,6 +24,16 @@ export function formatText(result) {
             lines.push(`  … and ${result.findings.length - 50} more`);
         }
     }
+    if (result.skippedFiles?.length) {
+        lines.push('');
+        lines.push(`Skipped (looks like a non-Playwright test — Jest/Vitest/RTL — ${result.skippedFiles.length}):`);
+        for (const f of result.skippedFiles.slice(0, 20)) {
+            lines.push(`  ${f}`);
+        }
+        if (result.skippedFiles.length > 20) {
+            lines.push(`  … and ${result.skippedFiles.length - 20} more`);
+        }
+    }
     return lines.join('\n');
 }
 function pathBasename(p) {

package/dist/index.js

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { globSync } from 'glob';
 import { runEslint } from './eslint-runner.js';
-import { analyzeSource } from './metrics.js';
+import { commonAncestorDir } from './fs-util.js';
+import { analyzeSource, findLocalAssertionHelperNames, looksLikeNonPlaywrightTest, } from './metrics.js';
 import { DEFAULT_THRESHOLDS } from './profiles.js';
 import { computeScore } from './score-engine.js';
 export { computeScore, SQS_V1, locatorsScore, gradeFromScore } from './score-engine.js';
@@ -13,28 +14,103 @@ export { formatText } from './formatters/text.js';
 export { formatMarkdown } from './formatters/markdown.js';
 export { formatSarif } from './formatters/sarif.js';
 const SPEC_GLOBS = ['**/*.{spec,test}.{ts,tsx,js,jsx}', '**/*.spec.ts', '**/*.test.ts'];
+// Directory/glob expansion must never sweep in vendored or generated code —
+// verified as a real bug: scanning a project root with a plain node_modules
+// dependency that ships its own *.spec.ts files silently included them
+// alongside real specs. Every other JS tool in this space (ESLint,
+// Prettier, Jest) default-excludes these directories for the same reason;
+// an explicit file path always bypasses this (see `explicit` in
+// expandPaths), so this only affects auto-discovery.
+const DEFAULT_IGNORE_GLOBS = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/out/**',
+    '**/coverage/**',
+    '**/.next/**',
+    '**/.nuxt/**',
+    '**/.turbo/**',
+    '**/.cache/**',
+    '**/.svelte-kit/**',
+    '**/playwright-report/**',
+    '**/test-results/**',
+];
+/**
+ * `explicit`: paths the caller named directly (a literal existing file) —
+ * always scored, regardless of whether they look like a Playwright spec.
+ * `expanded`: everything else (matched via a directory scan or a glob
+ * pattern) — subject to the looksLikePlaywrightSpec filter in scorePaths,
+ * since a broad `**\/*.test.ts`-style match can just as easily sweep in
+ * unrelated Jest/Vitest/RTL unit tests sitting in the same repo.
+ */
 function expandPaths(inputs, cwd) {
-    const files = new Set();
+    const explicit = new Set();
+    const expanded = new Set();
     for (const input of inputs) {
         const abs = path.isAbsolute(input) ? input : path.resolve(cwd, input);
         if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
-            files.add(abs);
+            explicit.add(abs);
             continue;
         }
         if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
             for (const g of SPEC_GLOBS) {
-                for (const f of globSync(g, { cwd: abs, absolute: true, nodir: true })) {
-                    files.add(path.resolve(f));
+                for (const f of globSync(g, {
+                    cwd: abs,
+                    absolute: true,
+                    nodir: true,
+                    ignore: DEFAULT_IGNORE_GLOBS,
+                })) {
+                    expanded.add(path.resolve(f));
                 }
             }
             continue;
         }
         // treat as glob
-        for (const f of globSync(input, { cwd, absolute: true, nodir: true })) {
-            files.add(path.resolve(f));
+        for (const f of globSync(input, {
+            cwd,
+            absolute: true,
+            nodir: true,
+            ignore: DEFAULT_IGNORE_GLOBS,
+        })) {
+            expanded.add(path.resolve(f));
         }
     }
-    return [...files].sort();
+    // A file can be reached both explicitly and via expansion (e.g. an
+    // explicit path plus an overlapping glob); explicit intent wins.
+    for (const f of explicit)
+        expanded.delete(f);
+    return { explicit: [...explicit].sort(), expanded: [...expanded].sort() };
+}
+function hardFail(profile, threshold, findings, extra = {}, skippedFiles) {
+    return {
+        scoreVersion: 'sqs-v1',
+        profile,
+        score: 0,
+        grade: 'F',
+        pass: false,
+        threshold,
+        summary: {
+            files: 0,
+            tests: 0,
+            sloc: 0,
+            findings: findings.length,
+            errors: findings.filter((f) => f.severity === 'error').length,
+            warnings: findings.filter((f) => f.severity === 'warning').length,
+            nativeLocators: 0,
+            rawLocators: 0,
+            ...extra,
+        },
+        dimensions: {
+            playwrightHygiene: 0,
+            assertions: 0,
+            locators: 0,
+            structure: 0,
+            ...(profile === 'guardian' ? { guardianConventions: 0 } : {}),
+        },
+        findings,
+        ...(skippedFiles && skippedFiles.length > 0 ? { skippedFiles } : {}),
+    };
 }
 /**
  * Score Playwright spec files. Deterministic and AI-free (sqs-v1).
@@ -43,10 +119,10 @@ export async function scorePaths(options) {
     const cwd = options.cwd ?? process.cwd();
     const profile = options.profile ?? 'standard';
     const threshold = options.threshold ?? DEFAULT_THRESHOLDS[profile] ?? 80;
-    const files = expandPaths(options.paths, cwd);
-    if (files.length === 0) {
+    const { explicit, expanded } = expandPaths(options.paths, cwd);
+    if (explicit.length === 0 && expanded.length === 0) {
         // Hard-fail: empty match must never look like a healthy suite (was ~99 PASS).
-        const findings = [
+        return hardFail(profile, threshold, [
             {
                 rule: 'playwright-score/no-files',
                 severity: 'error',
@@ -54,43 +130,67 @@ export async function scorePaths(options) {
                 file: cwd,
                 dimension: 'structure',
             },
-        ];
-        return {
-            scoreVersion: 'sqs-v1',
-            profile,
-            score: 0,
-            grade: 'F',
-            pass: false,
-            threshold,
-            summary: {
-                files: 0,
-                tests: 0,
-                sloc: 0,
-                findings: 1,
-                errors: 1,
-                warnings: 0,
-                nativeLocators: 0,
-                rawLocators: 0,
-            },
-            dimensions: {
-                playwrightHygiene: 0,
-                assertions: 0,
-                locators: 0,
-                structure: 0,
-                ...(profile === 'guardian' ? { guardianConventions: 0 } : {}),
+        ]);
+    }
+    // Directory/glob matches are excluded only on positive evidence of a
+    // non-Playwright test framework — see looksLikeNonPlaywrightTest. Paths
+    // the caller named explicitly are always scored regardless.
+    const skippedFiles = [];
+    const acceptedExpanded = [];
+    const skipBase = commonAncestorDir([...explicit, ...expanded]);
+    for (const f of expanded) {
+        const source = fs.readFileSync(f, 'utf8');
+        if (looksLikeNonPlaywrightTest(source)) {
+            skippedFiles.push(path.relative(skipBase, f) || path.basename(f));
+        }
+        else {
+            acceptedExpanded.push(f);
+        }
+    }
+    const files = [...explicit, ...acceptedExpanded].sort();
+    if (files.length === 0) {
+        return hardFail(profile, threshold, [
+            {
+                rule: 'playwright-score/no-files',
+                severity: 'error',
+                message: `${expanded.length} file(s) matched but all look like non-Playwright tests (Jest/Vitest/RTL) — nothing to score.`,
+                file: cwd,
+                dimension: 'structure',
             },
-            findings,
-        };
+        ], {}, skippedFiles);
     }
-    const eslintFindings = await runEslint({ files, profile, cwd });
+    // Relative to the files' own common ancestor (not the caller's cwd, which
+    // may be unrelated) so findings stay portable across machines/CI and
+    // formatters/sarif.ts can emit repo-relative artifactLocation URIs.
+    const filesBase = commonAncestorDir(files);
+    // Read every file once, up front, so (a) we can feed ESLint's
+    // expect-expect a per-run list of local assertion-helper names before
+    // linting (see findLocalAssertionHelperNames) and (b) the metrics loop
+    // below doesn't re-read the same files ESLint already read internally.
+    const sources = new Map();
+    const assertFunctionNames = new Set();
+    for (const file of files) {
+        const source = fs.readFileSync(file, 'utf8');
+        sources.set(file, source);
+        for (const name of findLocalAssertionHelperNames(source, file)) {
+            assertFunctionNames.add(name);
+        }
+    }
+    const eslintFindings = await runEslint({
+        files,
+        profile,
+        cwd,
+        assertFunctionNames: [...assertFunctionNames],
+    });
     let totalSloc = 0;
     let totalTests = 0;
     let native = 0;
     let raw = 0;
     const metricFindings = [];
     for (const file of files) {
-        const source = fs.readFileSync(file, 'utf8');
-        const m = analyzeSource(source, file);
+        const source = sources.get(file) ?? '';
+        const relFile = path.relative(filesBase, file) || path.basename(file);
+        const m = analyzeSource(source, relFile);
         totalSloc += m.sloc;
         totalTests += m.tests;
         native += m.locators.native;
@@ -100,7 +200,21 @@ export async function scorePaths(options) {
     }
     // Dedupe empty-test style: if guardian require-expect already fired, still ok
     const findings = [...eslintFindings, ...metricFindings];
-    return computeScore({
+    const parseErrors = findings.filter((f) => f.rule === 'playwright-score/parse-error');
+    if (parseErrors.length > 0) {
+        // A file that isn't valid JS/TS can't be executed, let alone scored on
+        // its merits. Diluting this into the normal per-dimension penalty math
+        // (a handful of exp-decay points on an otherwise large, clean batch)
+        // would let a broken file hide inside a passing score. Hard-fail
+        // instead, same as the no-matching-files case.
+        return hardFail(profile, threshold, findings, {
+            files: files.length,
+            sloc: Math.max(totalSloc, 1),
+            nativeLocators: native,
+            rawLocators: raw,
+        }, skippedFiles);
+    }
+    const result = computeScore({
         profile,
         threshold,
         findings,
@@ -110,4 +224,5 @@ export async function scorePaths(options) {
         nativeLocators: native,
         rawLocators: raw,
     });
+    return skippedFiles.length > 0 ? { ...result, skippedFiles } : result;
 }

package/dist/metrics.d.ts

@@ -1,13 +1,34 @@
 import type { Finding, LocatorCounts } from './types.js';
-/** Count native vs raw locator calls (simple statistical). */
-export declare function countLocators(source: string): LocatorCounts;
-/** Count test( / test.only( / test.skip( style declarations (approx). */
-export declare function countTests(source: string): number;
 /**
- * Detect test callbacks that appear to have zero expect( calls.
- * Heuristic: for each test( ... async (...) => { body }, check body for expect.
+ * Heuristic: does this file show positive evidence of being a *non*-
+ * Playwright test (Jest/Vitest/Mocha/Jasmine/React Testing Library), as
+ * opposed to a Playwright spec that a broad `**\/*.test.ts` glob would
+ * otherwise sweep in alongside real e2e specs? Used only to decide whether
+ * to auto-exclude a file discovered via directory/glob expansion — never
+ * applied to a file path the caller named explicitly.
+ */
+export declare function looksLikeNonPlaywrightTest(source: string): boolean;
+export declare function countLocators(source: string, file?: string): LocatorCounts;
+/**
+ * Names of same-file functions (function declarations, or a const bound to
+ * an arrow/function expression) whose own body contains an expect(...)-
+ * shaped call anywhere. Fed into playwright/expect-expect's own
+ * assertFunctionNames option (see eslint-runner.ts) so a test that
+ * delegates its assertion to a locally-defined helper — `audit(page,
+ * path)`, `checkFlashMessageVisibility(page, msg)`, `assertDashboardLoaded`
+ * — isn't flagged as having no assertions, regardless of what the helper
+ * happens to be named. expect-expect can only see expect() calls written
+ * directly in the test body, so without this, delegating to a helper at
+ * all — an extremely common way to dedupe near-identical specs — reads as
+ * "no assertions"; verified against several real production files using
+ * several different naming conventions for the exact same shape.
+ * Deliberately local-only: a helper imported from another file can't be
+ * resolved without following module specifiers and parsing that file too,
+ * well beyond what a fast, per-file syntactic check should attempt.
  */
-export declare function findEmptyExpectTests(source: string, file: string): Finding[];
+export declare function findLocalAssertionHelperNames(source: string, file?: string): string[];
+/** Count test( / test.only( / test.skip( / test.fixme( style declarations (approx). */
+export declare function countTests(source: string): number;
 export declare function findOversizedFile(source: string, file: string, maxSloc?: number): Finding[];
 export declare function analyzeSource(source: string, file: string): {
     sloc: number;

package/dist/metrics.js

@@ -1,56 +1,237 @@
+import { parseForESLint } from '@typescript-eslint/parser';
 import { countSloc } from './sloc.js';
-const NATIVE_RE = /\.\s*getBy(?:Role|Label|TestId|Text|Placeholder)\s*\(/g;
-const RAW_RE = /(?:page|frame)\s*\.\s*locator\s*\(/g;
-/** Count native vs raw locator calls (simple statistical). */
-export function countLocators(source) {
-    const native = [...source.matchAll(NATIVE_RE)].length;
-    const raw = [...source.matchAll(RAW_RE)].length;
+// A positive "this IS a Playwright spec" check turned out to be unsafe:
+// Playwright's own custom-fixtures pattern (test/expect re-exported from a
+// project-local module built with base.extend()) is extremely common in
+// real suites, and the fixtures a test destructures can be named anything
+// (`bomPage`, `authedUser`, ...) — not necessarily the stock page/context/
+// browser/request names. A file that legitimately imports `test`/`expect`
+// from '../fixtures' and destructures `{ bomPage }` has zero syntactic
+// signal distinguishing it from an unrelated framework, so requiring
+// positive Playwright evidence false-negatives on real production specs
+// (verified against real code: it silently skipped 18 of 19 genuine specs
+// in one real suite). Denylisting known non-Playwright frameworks is much
+// safer — a missed rare/unusual file just scores harmlessly, where a
+// falsely-skipped real spec silently stops being scored at all.
+const NON_PLAYWRIGHT_IMPORT_RE = /from\s+['"](?:vitest|jest|@jest\/[a-z-]+|mocha|jasmine|chai|@testing-library\/[a-z-]+)['"]/;
+const RTL_API_RE = /\bscreen\.(?:getBy|queryBy|findBy|getAllBy|queryAllBy|findAllBy)\w*\(|\btoBeInTheDocument\(/;
+/**
+ * Heuristic: does this file show positive evidence of being a *non*-
+ * Playwright test (Jest/Vitest/Mocha/Jasmine/React Testing Library), as
+ * opposed to a Playwright spec that a broad `**\/*.test.ts` glob would
+ * otherwise sweep in alongside real e2e specs? Used only to decide whether
+ * to auto-exclude a file discovered via directory/glob expansion — never
+ * applied to a file path the caller named explicitly.
+ */
+export function looksLikeNonPlaywrightTest(source) {
+    return NON_PLAYWRIGHT_IMPORT_RE.test(source) || RTL_API_RE.test(source);
+}
+const NATIVE_METHODS = new Set([
+    'getByRole',
+    'getByLabel',
+    'getByTestId',
+    'getByText',
+    'getByPlaceholder',
+]);
+/**
+ * Generic ESTree walk (no visitor-keys dependency). `parent` is excluded so
+ * this stays a walk over a DAG even if a parent back-reference is ever
+ * attached to the tree upstream.
+ */
+function walk(node, visit) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walk(item, visit);
+        return;
+    }
+    const obj = node;
+    if (typeof obj.type === 'string')
+        visit(obj);
+    for (const key in obj) {
+        if (key === 'parent')
+            continue;
+        walk(obj[key], visit);
+    }
+}
+/**
+ * Parses source into an ESTree-compatible AST for our own lightweight
+ * AST-walk checks (locator counting, local assertion-helper discovery).
+ * Returns undefined on any parse failure — callers degrade to "found
+ * nothing" rather than throwing; ESLint's own lint pass over the same
+ * file surfaces the real parse error as a finding.
+ */
+function parseSource(source, file) {
+    try {
+        return parseForESLint(source, {
+            ecmaVersion: 2022,
+            sourceType: 'module',
+            // JSX must be extension-driven, not always-on: a bare .ts file can
+            // legally use the old-style `<Type>value` cast syntax, which is
+            // ambiguous with — and would be misparsed as — a JSX element if JSX
+            // were enabled unconditionally.
+            ecmaFeatures: { jsx: /\.(tsx|jsx)$/.test(file ?? '') },
+        }).ast;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Count native vs raw locator calls via the same AST the ESLint pass
+ * already parses (rather than a regex), so this ratio can't silently
+ * disagree with `no-raw-locators` findings. A regex anchored to literal
+ * `page`/`frame` receivers misses raw locators on any other receiver —
+ * e.g. `this.container.locator(...)` in a Page Object Model, or a second
+ * `.locator()` chained off a prior locator call — both common in
+ * real-world (and AI-generated) specs.
+ */
+// Playwright's older direct-action API takes a raw selector string as the
+// first argument — page.click('#foo') instead of page.locator('#foo').click()
+// or a native locator. This is arguably the single most common raw-selector
+// anti-pattern in naive/AI-generated code (verified against a realistic
+// sample: a file using this exclusively scored a perfect 100 on the
+// locators dimension before this fix). Restricted to methods a Locator
+// itself takes zero required arguments for (click/dblclick/hover/check/
+// uncheck/tap/focus) — real Playwright types never allow a string there on
+// a Locator, so a string first argument unambiguously means the legacy
+// page/frame form regardless of receiver name. fill/type/press/
+// selectOption are deliberately excluded: their first argument is
+// legitimately a string on a Locator too (the value/key, not a selector),
+// so counting them would risk new false positives on correct code.
+const LEGACY_SELECTOR_ACTION_METHODS = new Set([
+    'click',
+    'dblclick',
+    'hover',
+    'check',
+    'uncheck',
+    'tap',
+    'focus',
+]);
+export function countLocators(source, file) {
+    let native = 0;
+    let raw = 0;
+    const ast = parseSource(source, file);
+    if (!ast)
+        return { native, raw };
+    walk(ast, (node) => {
+        if (node.type !== 'CallExpression' ||
+            node.callee?.type !== 'MemberExpression') {
+            return;
+        }
+        const callee = node.callee;
+        if (callee.computed)
+            return;
+        const property = callee.property;
+        if (property?.type !== 'Identifier')
+            return;
+        if (NATIVE_METHODS.has(property.name ?? '')) {
+            native++;
+        }
+        else if (property.name === 'locator') {
+            raw++;
+        }
+        else if (LEGACY_SELECTOR_ACTION_METHODS.has(property.name ?? '')) {
+            const args = node.arguments;
+            const first = args?.[0];
+            if (first?.type === 'Literal' && typeof first.value === 'string')
+                raw++;
+        }
+    });
     return { native, raw };
 }
-/** Count test( / test.only( / test.skip( style declarations (approx). */
+function isExpectCallee(callee) {
+    if (!callee)
+        return false;
+    if (callee.type === 'Identifier')
+        return callee.name === 'expect';
+    if (callee.type === 'MemberExpression') {
+        // Walk down to the root of a member chain, e.g. expect.poll(fn).toBe(x)
+        // — the callee of the outer .toBe() call is `expect.poll(fn).toBe`,
+        // whose object is the `expect.poll(fn)` CallExpression.
+        let obj = callee.object;
+        while (obj?.type === 'MemberExpression')
+            obj = obj.object;
+        if (obj?.type === 'Identifier' && obj.name === 'expect')
+            return true;
+        if (obj?.type === 'CallExpression') {
+            return isExpectCallee(obj.callee);
+        }
+    }
+    return false;
+}
+function containsExpectCall(node) {
+    let found = false;
+    walk(node, (n) => {
+        if (found || n.type !== 'CallExpression')
+            return;
+        if (isExpectCallee(n.callee))
+            found = true;
+    });
+    return found;
+}
+/**
+ * Names of same-file functions (function declarations, or a const bound to
+ * an arrow/function expression) whose own body contains an expect(...)-
+ * shaped call anywhere. Fed into playwright/expect-expect's own
+ * assertFunctionNames option (see eslint-runner.ts) so a test that
+ * delegates its assertion to a locally-defined helper — `audit(page,
+ * path)`, `checkFlashMessageVisibility(page, msg)`, `assertDashboardLoaded`
+ * — isn't flagged as having no assertions, regardless of what the helper
+ * happens to be named. expect-expect can only see expect() calls written
+ * directly in the test body, so without this, delegating to a helper at
+ * all — an extremely common way to dedupe near-identical specs — reads as
+ * "no assertions"; verified against several real production files using
+ * several different naming conventions for the exact same shape.
+ * Deliberately local-only: a helper imported from another file can't be
+ * resolved without following module specifiers and parsing that file too,
+ * well beyond what a fast, per-file syntactic check should attempt.
+ */
+export function findLocalAssertionHelperNames(source, file) {
+    const ast = parseSource(source, file);
+    if (!ast)
+        return [];
+    const names = new Set();
+    walk(ast, (node) => {
+        let name;
+        let body;
+        if (node.type === 'FunctionDeclaration') {
+            const id = node.id;
+            if (id?.type === 'Identifier') {
+                name = id.name;
+                body = node;
+            }
+        }
+        else if (node.type === 'VariableDeclarator') {
+            const id = node.id;
+            const init = node.init;
+            if (id?.type === 'Identifier' &&
+                (init?.type === 'ArrowFunctionExpression' || init?.type === 'FunctionExpression')) {
+                name = id.name;
+                body = init;
+            }
+        }
+        if (name && body && containsExpectCall(body))
+            names.add(name);
+    });
+    return [...names];
+}
+const TEST_NON_DECL_RE = /\btest\.(describe|step|beforeEach|afterEach|beforeAll|afterAll|use|setTimeout|info|expect)\b/;
+/** Count test( / test.only( / test.skip( / test.fixme( style declarations (approx). */
 export function countTests(source) {
-    const re = /\btest(?:\.(?:only|skip|fix|slow))?\s*\(/g;
-    // Exclude test.describe, test.step, test.before*, test.after*, test.use
+    // Playwright's real modifier API is test.fixme() — not test.fix().
+    const re = /\btest(?:\.(?:only|skip|fixme|slow))?\s*\(/g;
     let count = 0;
     let m;
-    const exclude = /\btest\.(?:describe|step|beforeEach|afterEach|beforeAll|afterAll|use|setTimeout|info|expect)\b/;
     while ((m = re.exec(source)) !== null) {
-        const start = Math.max(0, m.index - 0);
-        const snippet = source.slice(start, start + 40);
-        if (exclude.test(snippet.split('(')[0] + '(')) {
-            // more precise: check the matched prefix
-        }
         const before = source.slice(Math.max(0, m.index - 1), m.index + 20);
-        if (/\btest\.(describe|step|beforeEach|afterEach|beforeAll|afterAll|use|setTimeout|info)\b/.test(before)) {
-            continue;
-        }
-        // test.expect is rare as call form
-        if (/\btest\.expect\b/.test(before))
+        if (TEST_NON_DECL_RE.test(before))
             continue;
         count++;
     }
     return count;
 }
-/**
- * Detect test callbacks that appear to have zero expect( calls.
- * Heuristic: for each test( ... async (...) => { body }, check body for expect.
- */
-export function findEmptyExpectTests(source, file) {
-    const findings = [];
-    // Rough scan: if file has test( but no expect( at all
-    const hasTest = /\btest(?:\.(?:only|skip|fix))?\s*\(/.test(source);
-    const hasExpect = /\bexpect\s*\(/.test(source);
-    if (hasTest && !hasExpect) {
-        findings.push({
-            rule: 'metrics/no-empty-test',
-            severity: 'error',
-            message: 'Test file has test() but no expect() assertions',
-            file,
-            dimension: 'assertions',
-        });
-    }
-    return findings;
-}
 export function findOversizedFile(source, file, maxSloc = 400) {
     const sloc = countSloc(source);
     if (sloc > maxSloc) {
@@ -70,10 +251,16 @@ export function analyzeSource(source, file) {
     return {
         sloc: countSloc(source),
         tests: countTests(source),
-        locators: countLocators(source),
-        findings: [
-            ...findEmptyExpectTests(source, file),
-            ...findOversizedFile(source, file),
-        ],
+        locators: countLocators(source, file),
+        // No homegrown "has no assertions" check here: playwright/expect-expect
+        // (a real AST-based community rule, always enabled — see
+        // eslint-runner.ts) already covers this correctly, including
+        // expect.poll(...)/expect.soft(...) chained forms that a source-text
+        // regex would need to special-case. A prior regex-based version of
+        // this check (metrics/no-empty-test) only matched a bare `expect(`
+        // call and so false-positived at error severity on any file whose only
+        // assertions were expect.poll()/expect.soft() — verified against real
+        // production code.
+        findings: [...findOversizedFile(source, file)],
     };
 }

package/dist/profiles.js

@@ -45,10 +45,9 @@ export const ESLINT_RULE_MAP = {
     },
     // Assertions
     'playwright/expect-expect': { dimension: 'assertions' },
-    'playwright/prefer-web-first-assertions': {
-        dimension: 'assertions',
-        severityOverride: 'warning',
-    },
+    // No severityOverride: matches eslint-plugin-playwright's own
+    // recommended severity ('error'), set via eslint-runner.ts's rule config.
+    'playwright/prefer-web-first-assertions': { dimension: 'assertions' },
     'playwright/valid-expect': { dimension: 'assertions' },
     'playwright/no-standalone-expect': { dimension: 'assertions' },
     // Locators — findings for repair, reportOnly so ratio owns locators score
@@ -69,10 +68,10 @@ export const ESLINT_RULE_MAP = {
     },
     // Structure
     'playwright/no-focused-test': { dimension: 'structure' },
-    'playwright/no-skipped-test': {
-        dimension: 'structure',
-        severityOverride: 'warning',
-    },
+    // playwright/no-skipped-test is turned off in eslint-runner.ts in favor
+    // of pwscore/no-skipped-test-declaration, which doesn't false-positive
+    // on Playwright's documented conditional test.skip(condition, reason).
+    'pwscore/no-skipped-test-declaration': { dimension: 'structure' },
     'playwright/max-nested-describe': {
         dimension: 'structure',
         severityOverride: 'warning',
@@ -101,17 +100,7 @@ export const ESLINT_RULE_MAP = {
         dimension: 'guardianConventions',
         severityOverride: 'warning',
     },
-    'guardian/prefer-uuid': {
-        dimension: 'guardianConventions',
-        severityOverride: 'warning',
-    },
-    'guardian/fixtures-import': {
-        dimension: 'guardianConventions',
-        severityOverride: 'info',
-        reportOnly: true,
-    },
     // Metrics injected as synthetic findings
-    'metrics/no-empty-test': { dimension: 'assertions' },
     'metrics/oversized-file': {
         dimension: 'structure',
         severityOverride: 'warning',

package/dist/rules/base-plugin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Rules active for both `standard` and `guardian` profiles — corrections
+ * to upstream eslint-plugin-playwright behavior, not house style.
+ */
+import type { Rule } from 'eslint';
+export declare const basePlugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        'no-skipped-test-declaration': Rule.RuleModule;
+    };
+};

package/dist/rules/base-plugin.js

@@ -0,0 +1,77 @@
+function isSkipCallee(callee) {
+    if (!callee || callee.type !== 'MemberExpression' || callee.computed)
+        return false;
+    const obj = callee.object;
+    const prop = callee.property;
+    if (prop?.type !== 'Identifier' || prop.name !== 'skip')
+        return false;
+    // test.skip(...)
+    if (obj?.type === 'Identifier' && obj.name === 'test')
+        return true;
+    // test.describe.skip(...)
+    if (obj?.type === 'MemberExpression' &&
+        !obj.computed &&
+        obj.object?.type === 'Identifier' &&
+        obj.object.name === 'test' &&
+        obj.property?.type === 'Identifier' &&
+        obj.property.name === 'describe') {
+        return true;
+    }
+    return false;
+}
+const FUNCTION_TYPES = new Set(['FunctionExpression', 'ArrowFunctionExpression']);
+/**
+ * eslint-plugin-playwright's no-skipped-test flags every form of
+ * test.skip(...)/test.describe.skip(...) identically. That conflates two
+ * very different, both-real patterns:
+ *
+ *  - test.skip('name', fn) / test.describe.skip('name', fn) — a
+ *    DECLARATION whose test/suite never runs at all. Worth flagging: this
+ *    is the "test is broken, hide it" anti-pattern.
+ *  - test.skip(condition, reason) / test.skip() called inside a test/hook
+ *    body — Playwright's own documented API for conditionally skipping a
+ *    test at runtime (e.g. per-browser, per-env). This is the correct,
+ *    recommended way to handle exactly that case, not an anti-pattern —
+ *    see playwright.dev/docs/test-annotations#conditionally-skip-a-test.
+ *
+ * Verified against real-world code: eslint-plugin-playwright's rule flags
+ * both forms identically, generating warnings on entirely idiomatic
+ * cross-browser test suites. This rule replaces it (see eslint-runner.ts,
+ * where the upstream rule is turned off) with the same "declaration form"
+ * severity but without the false positive on the conditional form — the
+ * two are told apart by whether the trailing argument is a function (a
+ * declaration always supplies the test body as a function; a conditional
+ * skip's second argument, if any, is the string reason).
+ */
+const noSkippedTestDeclaration = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Disallow test.skip()/test.describe.skip() used to declare an always-skipped test (conditional runtime skips are unaffected)',
+        },
+        messages: {
+            skipped: 'Unexpected use of the .skip() annotation to declare an always-skipped test.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (!isSkipCallee(node.callee))
+                    return;
+                const args = node.arguments ?? [];
+                const lastArg = args[args.length - 1];
+                const isDeclaration = args.length >= 2 && FUNCTION_TYPES.has(lastArg?.type ?? '');
+                if (isDeclaration) {
+                    context.report({ node: node, messageId: 'skipped' });
+                }
+            },
+        };
+    },
+};
+export const basePlugin = {
+    meta: { name: 'pwscore-base', version: '0.1.0' },
+    rules: {
+        'no-skipped-test-declaration': noSkippedTestDeclaration,
+    },
+};

package/dist/rules/guardian-plugin.js

@@ -13,6 +13,76 @@ const DUMMY_SECRETS = new Set([
     'qwerty',
     '',
 ].map((s) => s.toLowerCase()));
+// Playwright's actual modifier API is test.fixme() — not test.fix().
+const TEST_MODIFIERS = new Set(['only', 'skip', 'fixme', 'slow']);
+const DESCRIBE_MODIFIERS = new Set(['serial', 'parallel', 'only', 'fixme']);
+/** Matches a bare test(...) call. */
+function isBareTestCall(node) {
+    return node.callee?.type === 'Identifier' && node.callee.name === 'test';
+}
+/** Matches test.describe(...) and test.describe.serial/parallel/only/fixme(...). */
+function isDescribeCall(node) {
+    const callee = node.callee;
+    if (!callee || callee.type !== 'MemberExpression' || callee.computed)
+        return false;
+    const obj = callee.object;
+    const prop = callee.property;
+    if (!obj || !prop || prop.type !== 'Identifier')
+        return false;
+    // test.describe(...)
+    if (obj.type === 'Identifier' && obj.name === 'test' && prop.name === 'describe') {
+        return true;
+    }
+    // test.describe.serial/parallel/only/fixme(...)
+    if (obj.type === 'MemberExpression' &&
+        !obj.computed &&
+        obj.object?.type === 'Identifier' &&
+        obj.object.name === 'test' &&
+        obj.property?.type === 'Identifier' &&
+        obj.property.name === 'describe' &&
+        DESCRIBE_MODIFIERS.has(prop.name ?? '')) {
+        return true;
+    }
+    return false;
+}
+/** Matches specifically test.describe.serial(...). */
+function isSerialDescribeCall(node) {
+    const callee = node.callee;
+    if (!callee || callee.type !== 'MemberExpression' || callee.computed)
+        return false;
+    const obj = callee.object;
+    const prop = callee.property;
+    return (obj?.type === 'MemberExpression' &&
+        !obj.computed &&
+        obj.object?.type === 'Identifier' &&
+        obj.object.name === 'test' &&
+        obj.property?.type === 'Identifier' &&
+        obj.property.name === 'describe' &&
+        prop?.type === 'Identifier' &&
+        prop.name === 'serial');
+}
+/** Matches test.only/skip/fixme/slow(...) (a modifier form of a real test declaration). */
+function isTestModifierCall(node) {
+    const callee = node.callee;
+    if (!callee || callee.type !== 'MemberExpression' || callee.computed)
+        return false;
+    const obj = callee.object;
+    const prop = callee.property;
+    return (obj?.type === 'Identifier' &&
+        obj.name === 'test' &&
+        prop?.type === 'Identifier' &&
+        TEST_MODIFIERS.has(prop.name ?? ''));
+}
+/** Matches test.step(...). */
+function isTestStepCall(node) {
+    const callee = node.callee;
+    return (callee?.type === 'MemberExpression' &&
+        !callee.computed &&
+        callee.object?.type === 'Identifier' &&
+        callee.object.name === 'test' &&
+        callee.property?.type === 'Identifier' &&
+        callee.property.name === 'step');
+}
 function hasDisableNextLine(sourceCode, line, ruleId) {
     const lines = sourceCode.getText().split(/\r?\n/);
     if (line < 2)
@@ -69,6 +139,42 @@ const noDateNowId = {
         };
     },
 };
+// Whole words only (after splitting camelCase/snake_case/kebab-case), not a
+// bare substring match — a substring match on "auth" flags "authorName",
+// "isAuthenticated", every "Author"/"authenticate"/"authorize" field in a
+// typical app under test, which is a lot of unrelated real-world test data.
+const SENSITIVE_WORDS = new Set([
+    'password',
+    'passwd',
+    'secret',
+    'secrets',
+    'token',
+    'tokens',
+    'auth',
+    'authorization',
+    'credential',
+    'credentials',
+]);
+function splitIdentifierWords(identifier) {
+    return identifier
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((w) => w.toLowerCase());
+}
+function looksLikeSensitiveKey(rawKey) {
+    const words = splitIdentifierWords(rawKey);
+    if (words.some((w) => SENSITIVE_WORDS.has(w)))
+        return true;
+    // apiKey / api_key / API-KEY — "key" alone is too generic (primaryKey,
+    // sortKey, ...) so only flag it directly adjacent to "api".
+    for (let i = 0; i < words.length - 1; i++) {
+        if (words[i] === 'api' && words[i + 1] === 'key')
+            return true;
+    }
+    return false;
+}
 const noHardcodedSecrets = {
     meta: {
         type: 'suggestion',
@@ -80,7 +186,6 @@ const noHardcodedSecrets = {
     },
     create(context) {
         const sourceCode = context.sourceCode ?? context.getSourceCode();
-        const keyRe = /password|passwd|secret|token|api[_-]?key|auth/i;
         function check(node, rawKey) {
             if (node.type !== 'Literal' || typeof node.value !== 'string')
                 return;
@@ -89,7 +194,7 @@ const noHardcodedSecrets = {
                 return;
             if (value.length < 6)
                 return;
-            if (!keyRe.test(rawKey ?? ''))
+            if (!looksLikeSensitiveKey(rawKey ?? ''))
                 return;
             const line = node.loc?.start.line ?? 1;
             if (hasDisableNextLine(sourceCode, line, 'guardian/no-hardcoded-secrets'))
@@ -126,13 +231,26 @@ const noGenericLongTimeout = {
         const allowed = new Set([2000, 20000]);
         return {
             Property(node) {
-                if (node.key.type === 'Identifier' &&
-                    node.key.name === 'timeout' &&
-                    node.value.type === 'Literal' &&
-                    typeof node.value.value === 'number' &&
-                    !allowed.has(node.value.value)) {
-                    context.report({ node, messageId: 'timeout' });
+                if (node.key.type !== 'Identifier' ||
+                    node.key.name !== 'timeout' ||
+                    node.value.type !== 'Literal' ||
+                    typeof node.value.value !== 'number' ||
+                    allowed.has(node.value.value)) {
+                    return;
                 }
+                // Only flag timeout options passed inline to a call, e.g.
+                // locator.click({ timeout }), expect(x).toBeVisible({ timeout }),
+                // test('x', { timeout }, fn) — not unrelated business data that
+                // happens to have a field named "timeout" (session config, a
+                // fixture payload, a mocked API response body, ...).
+                const objectExpr = node.parent;
+                const call = objectExpr?.parent;
+                if (objectExpr?.type !== 'ObjectExpression' ||
+                    call?.type !== 'CallExpression' ||
+                    !call.arguments?.includes(objectExpr)) {
+                    return;
+                }
+                context.report({ node, messageId: 'timeout' });
             },
         };
     },
@@ -150,27 +268,16 @@ const oneDescribeOneTest = {
     create(context) {
         let describes = 0;
         let tests = 0;
+        let usesSerialDescribe = false;
         return {
             CallExpression(node) {
-                if (node.callee.type === 'MemberExpression' && !node.callee.computed) {
-                    if (node.callee.object.type === 'Identifier' &&
-                        node.callee.object.name === 'test' &&
-                        node.callee.property.type === 'Identifier' &&
-                        node.callee.property.name === 'describe') {
-                        describes++;
-                    }
-                }
-                if (node.callee.type === 'Identifier' && node.callee.name === 'test') {
-                    tests++;
+                if (isDescribeCall(node)) {
+                    describes++;
+                    if (isSerialDescribeCall(node))
+                        usesSerialDescribe = true;
                 }
-                if (node.callee.type === 'MemberExpression' &&
-                    !node.callee.computed &&
-                    node.callee.object.type === 'Identifier' &&
-                    node.callee.object.name === 'test' &&
-                    node.callee.property.type === 'Identifier' &&
-                    ['only', 'skip', 'fix', 'slow'].includes(node.callee.property.name)) {
+                if (isBareTestCall(node) || isTestModifierCall(node))
                     tests++;
-                }
             },
             'Program:exit'() {
                 if (describes > 1) {
@@ -180,7 +287,12 @@ const oneDescribeOneTest = {
                         data: { count: String(describes) },
                     });
                 }
-                if (tests > 1) {
+                // test.describe.serial(...) is Playwright's documented mechanism
+                // for one user journey split into multiple ordered, dependent
+                // test() calls — the same "one scenario per file" intent as this
+                // rule, expressed a different way. Don't nag a pattern the
+                // framework itself recommends for exactly this case.
+                if (tests > 1 && !usesSerialDescribe) {
                     context.report({
                         loc: { line: 1, column: 0 },
                         messageId: 'tests',
@@ -205,20 +317,10 @@ const requireTestStep = {
         let hasStep = false;
         return {
             CallExpression(node) {
-                if (node.callee.type === 'Identifier' && node.callee.name === 'test') {
+                if (isBareTestCall(node) || isTestModifierCall(node))
                     hasTest = true;
-                }
-                if (node.callee.type === 'MemberExpression' &&
-                    !node.callee.computed &&
-                    node.callee.object.type === 'Identifier' &&
-                    node.callee.object.name === 'test' &&
-                    node.callee.property.type === 'Identifier') {
-                    if (['only', 'skip', 'fix', 'slow'].includes(node.callee.property.name)) {
-                        hasTest = true;
-                    }
-                    if (node.callee.property.name === 'step')
-                        hasStep = true;
-                }
+                if (isTestStepCall(node))
+                    hasStep = true;
             },
             'Program:exit'() {
                 if (hasTest && !hasStep) {
@@ -242,14 +344,13 @@ const requireExpect = {
         let hasExpect = false;
         return {
             CallExpression(node) {
-                if (node.callee.type === 'Identifier' && node.callee.name === 'test') {
+                if (isBareTestCall(node) || isTestModifierCall(node))
                     hasTest = true;
-                }
-                if (node.callee.type === 'Identifier' && node.callee.name === 'expect') {
+                if (node.callee?.type === 'Identifier' && node.callee.name === 'expect') {
                     hasExpect = true;
                 }
-                if (node.callee.type === 'MemberExpression' &&
-                    node.callee.object.type === 'Identifier' &&
+                if (node.callee?.type === 'MemberExpression' &&
+                    node.callee.object?.type === 'Identifier' &&
                     node.callee.object.name === 'expect') {
                     hasExpect = true;
                 }

package/dist/types.d.ts

@@ -41,6 +41,15 @@ export interface ScoreResult {
     summary: ScoreSummary;
     dimensions: ScoreDimensions;
     findings: Finding[];
+    /**
+     * Files matched by a directory/glob input but skipped because they show
+     * positive evidence of being a non-Playwright test (an import from
+     * vitest/jest/mocha/jasmine/@testing-library, or React Testing Library's
+     * screen.getBy/toBeInTheDocument() APIs). Repo-relative paths. Files passed
+     * explicitly by the caller are always scored and never appear here, even
+     * if they'd otherwise be skipped.
+     */
+    skippedFiles?: string[];
 }
 export interface ScoreOptions {
     paths: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaguardian/playwright-score",
-  "version": "0.1.2",
+  "version": "0.1.10",
   "description": "Deterministic, AI-free Playwright spec quality score (sqs-v1). Lint + score with standard and guardian profiles.",
   "type": "module",
   "main": "./dist/index.js",