@qaguardian/playwright-score 2.1.0 → 2.2.0

package/dist/rules/base-plugin.js

@@ -175,6 +175,64 @@ function callsResolve(fn, resolveName) {
         call.callee?.type === 'Identifier' &&
         call.callee.name === resolveName);
 }
+const LOOP_TYPES = new Set(['ForStatement', 'ForInStatement', 'ForOfStatement', 'WhileStatement', 'DoWhileStatement']);
+/**
+ * A retry/backoff pause inside a plain helper function (an API retry loop,
+ * `for (...) { try { await call() } catch { await sleep(500) } }`) is not a
+ * test waiting on the UI: it paces calls to a service. Only that shape is
+ * exempt: the sleep sits inside a catch clause, or inside a loop whose body
+ * contains a try/catch, and the enclosing function is *defined* (function
+ * declaration, `const f = () => ...`, class method) and is not itself nested
+ * in a callback handed to a call (a test, hook, describe or step body). A
+ * hand-rolled polling wait (`while (await x.isVisible()) sleep()`), a sleep
+ * directly in a test body or hook, a helper declared inside a test callback
+ * and a bare `sleep()` helper are all still flagged. `from` is the ancestor
+ * index to start climbing from (the Promise executor's own parent).
+ */
+function isRetryBackoffInHelper(ancestors, from) {
+    let retryShape = false;
+    let helperFound = false;
+    for (let i = from; i >= 0; i--) {
+        const anc = ancestors[i];
+        if (!helperFound) {
+            if (anc.type === 'CatchClause')
+                retryShape = true;
+            if (LOOP_TYPES.has(anc.type) && containsTryCatch(anc.body))
+                retryShape = true;
+        }
+        if (!FUNCTION_TYPES.has(anc.type) && anc.type !== 'FunctionDeclaration')
+            continue;
+        const parent = ancestors[i - 1];
+        if (parent?.type === 'CallExpression' || parent?.type === 'NewExpression') {
+            // Callback handed to a call (test body, hook, describe, .then, step):
+            // either the sleep is not in a free-standing helper at all, or the
+            // helper lives inside such a callback. Not exempt either way.
+            return false;
+        }
+        if (helperFound)
+            continue; // a function around the helper: keep checking the callback chain
+        if (anc.type === 'FunctionDeclaration' ||
+            parent?.type === 'MethodDefinition' ||
+            parent?.type === 'PropertyDefinition' ||
+            (parent?.type === 'VariableDeclarator' && parent.init === anc)) {
+            if (!retryShape)
+                return false;
+            helperFound = true;
+        }
+    }
+    return helperFound;
+}
+function containsTryCatch(root) {
+    let found = false;
+    walkNode(root, (n) => {
+        if (n.type !== 'TryStatement' || !n.handler)
+            return;
+        // An empty `try {}` is not a retry shape.
+        if ((n.block?.body ?? []).length > 0)
+            found = true;
+    });
+    return found;
+}
 /**
  * `await new Promise((resolve) => setTimeout(resolve, ms))` is the same
  * hard-coded sleep as `page.waitForTimeout(ms)` (already flagged, as an
@@ -289,7 +347,7 @@ const noTimerSleep = {
                             firstArg.name === resolveParam.name;
                         const resolveName = resolveParam?.type === 'Identifier' ? resolveParam.name : undefined;
                         const isWrappedResolve = typeof resolveName === 'string' && callsResolve(firstArg, resolveName);
-                        if (isDirectResolve || isWrappedResolve) {
+                        if ((isDirectResolve || isWrappedResolve) && !isRetryBackoffInHelper(ancestors, i - 1)) {
                             context.report({ node: node, messageId: 'sleep' });
                         }
                     }
@@ -517,8 +575,119 @@ function collectConstBindings(root) {
                 bindings.set(d.id.name, value);
         }
     });
+    // A `const` array is still mutable: `const errors = []; page.on('pageerror',
+    // (e) => errors.push(e)); expect(errors).toEqual([])` is a real assertion
+    // (the listener fills the array), not `expect([]).toEqual([])`. Only keep
+    // an array binding when every reference to it is the plain subject of an
+    // expect(...) call; any other use (method call, passed along, spread,
+    // reassigned element) might mutate it, so it is not a constant.
+    for (const [name, value] of [...bindings]) {
+        if (value.ok && Array.isArray(value.value) && !isOnlyReadAsExpectSubject(root, name)) {
+            bindings.delete(name);
+        }
+    }
     return bindings;
 }
+const MUTATING_METHODS = new Set([
+    'push', 'unshift', 'splice', 'pop', 'shift', 'sort', 'reverse', 'fill', 'copyWithin',
+]);
+/**
+ * True when no reference to `name` under `root` could change the array:
+ * every reference is a declaration, the subject of expect(...), a `.length`
+ * or index read, or the receiver of a non-mutating method. A reference that
+ * is a call argument (it may be handed to code that fills it), the
+ * receiver of a mutating method, an assignment/update target, or any other
+ * use that aliases the array (returned, assigned on, spread, put in an
+ * object) counts as possibly mutating, wherever it sits — including inside
+ * a closure such as a listener. Same-named properties (`obj.name`,
+ * `{ name: 1 }`) are not references. Shadowing is not resolved: a shadowing
+ * binding is read like the outer one, which can only keep a finding quiet.
+ */
+function isOnlyReadAsExpectSubject(root, name) {
+    let ok = true;
+    const visit = (node, stack) => {
+        if (!ok || !node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item, stack);
+            return;
+        }
+        const rec = node;
+        if (typeof rec.type !== 'string')
+            return;
+        const n = node;
+        if (n.type === 'Identifier' && n.name === name) {
+            if (referenceMayMutate(n, stack))
+                ok = false;
+            return;
+        }
+        const next = [...stack, n];
+        for (const key of Object.keys(rec)) {
+            if (key === 'parent')
+                continue;
+            const v = rec[key];
+            if (v && typeof v === 'object')
+                visit(v, next);
+        }
+    };
+    visit(root, []);
+    return ok;
+}
+/** Is the member expression `m` itself written, deleted or the receiver of a mutating method? */
+function memberMutates(m, above) {
+    if (above.type === 'AssignmentExpression' && above.left === m)
+        return true;
+    if (above.type === 'UpdateExpression')
+        return true;
+    if (above.type === 'UnaryExpression' && above.operator === 'delete')
+        return true;
+    const prop = m.property;
+    return (!m.computed &&
+        prop?.type === 'Identifier' &&
+        !!prop.name &&
+        MUTATING_METHODS.has(prop.name) &&
+        above.type === 'CallExpression' &&
+        above.callee === m);
+}
+function referenceMayMutate(id, stack) {
+    const parent = stack[stack.length - 1];
+    const grand = stack[stack.length - 2];
+    if (!parent)
+        return true;
+    switch (parent.type) {
+        case 'VariableDeclarator':
+            return parent.id !== id; // `const b = expected` aliases it
+        case 'CallExpression':
+            if (parent.arguments?.[0] === id && isExpectCallNode(parent))
+                return false;
+            return parent.callee !== id || false; // an argument, or the array called
+        case 'MemberExpression': {
+            if (parent.object !== id)
+                return false; // `obj.expected`: a property name, not this binding
+            // Mutation of the member itself (`a.x = 1`, `a.push(1)`), then, for a
+            // computed access chain (`rows[0].push(9)`, `rows[0][1] = 2`), of
+            // the element it reaches: the inner array is part of the asserted one.
+            let member = parent;
+            for (let up = stack.length - 2; up >= 0; up--) {
+                const above = stack[up];
+                if (memberMutates(member, above))
+                    return true;
+                if (!member.computed || above.type !== 'MemberExpression' || above.object !== member)
+                    break;
+                member = above;
+            }
+            return false; // `.length`, `[0]`, `.map(...)`, ... are reads
+        }
+        case 'Property':
+        case 'PropertyDefinition':
+            // Non-computed key position is a name, not a reference; a value (or
+            // shorthand) puts the array inside an object.
+            return !((parent.key === id || false) && !parent.computed && !parent.shorthand);
+        default:
+            return true;
+    }
+}
 /**
  * Climbs from `node` to the body of the nearest enclosing function (the
  * test/hook callback in the common case) — the scope `noTrivialAssertion`

package/dist/score-engine.js

@@ -188,6 +188,7 @@ export function computeScore(input) {
             nativeLocators: input.nativeLocators,
             rawLocators: input.rawLocators,
             unassertedTests: input.findings.filter((f) => f.rule === 'playwright/expect-expect' && !f.reportOnly).length,
+            unverifiedTests: input.findings.filter((f) => f.rule === 'playwright-score/assertion-unverified').length,
             cleanTests,
         },
         dimensions: dims,

package/dist/types.d.ts

@@ -51,6 +51,10 @@ export interface ScoreSummary {
     /** Tests with no recognized assertion (uncapped playwright/expect-expect
      * census, after delegation resolution). */
     unassertedTests: number;
+    /** Tests with no expect(...) that call something this scan cannot read
+     * (`playwright-score/assertion-unverified`, report-only). They are NOT in
+     * `unassertedTests` and not penalised, but they are not known to assert. */
+    unverifiedTests: number;
     /** Tests with no demerit in any dimension — the headline the score is
      * built from: the weighted share of tests that are clean. */
     cleanTests: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaguardian/playwright-score",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Deterministic, AI-free Playwright spec quality score — the weighted share of your tests that are clean.",
   "type": "module",
   "main": "./dist/index.js",