eslint-plugin-test-flakiness 1.2.0 → 1.3.1

package/lib/rules/await-async-events.js

@@ -31,7 +31,6 @@ module.exports = {
     ],
     messages: {
       missingAwait: '{{method}} must be awaited to prevent race conditions',
-      missingAwaitFireEvent: 'fireEvent.{{method}} should be awaited',
       missingAwaitUserEvent: 'userEvent.{{method}} must be awaited',
       missingAwaitAct: 'act() with async callback must be awaited',
       missingAwaitPage: 'Playwright page.{{method}} must be awaited',
@@ -58,11 +57,6 @@ module.exports = {
       'hover', 'unhover', 'paste', 'keyboard'
     ];
     
-    const asyncFireEventMethods = [
-      'click', 'change', 'input', 'submit', 'focus', 'blur',
-      'keyDown', 'keyUp', 'keyPress', 'mouseDown', 'mouseUp'
-    ];
-    
     const asyncPageMethods = [
       'click', 'fill', 'type', 'press', 'check', 'uncheck',
       'selectOption', 'setInputFiles', 'focus', 'hover', 'tap',
@@ -144,32 +138,6 @@ module.exports = {
       }
     }
 
-    function checkFireEvent(node) {
-      if (node.callee.type === 'MemberExpression' &&
-          node.callee.object.name === 'fireEvent') {
-        
-        const methodName = node.callee.property.name;
-        if (asyncFireEventMethods.includes(methodName) && 
-            !isPromiseHandled(node)) {
-          
-          context.report({
-            node,
-            messageId: 'missingAwaitFireEvent',
-            data: { method: methodName },
-            fix(fixer) {
-              const funcNode = findEnclosingFunction(node);
-              const asyncFixes = ensureAsyncFunction(fixer, funcNode);
-              if (asyncFixes === null) return null;
-              return [
-                fixer.insertTextBefore(node, 'await '),
-                ...asyncFixes
-              ];
-            }
-          });
-        }
-      }
-    }
-
     function checkAct(node) {
       if (node.callee.name === 'act' && node.arguments[0]) {
         const callback = node.arguments[0];
@@ -309,7 +277,6 @@ module.exports = {
       },
       CallExpression(node) {
         checkUserEvent(node);
-        checkFireEvent(node);
         checkAct(node);
         checkPlaywright(node);
         checkElementMethods(node);

package/lib/rules/no-element-removal-check.js

@@ -4,7 +4,7 @@
  */
 'use strict';
 
-const { isTestFile, getFilename } = require('../utils/helpers');
+const { isTestFile, getFilename, findEnclosingFunction, ensureAsyncFunction, addWaitForImport } = require('../utils/helpers');
 
 module.exports = {
   meta: {
@@ -15,11 +15,16 @@ module.exports = {
       recommended: true,
       url: 'https://github.com/tigredonorte/eslint-plugin-test-flakiness/blob/main/docs/rules/no-element-removal-check.md'
     },
+    fixable: 'code',
     schema: [],
     messages: {
       avoidRemovalCheck: 'Checking for element removal can be flaky. Use waitForElementToBeRemoved or wait for a positive condition instead.',
-      useWaitForRemoval: 'Use waitForElementToBeRemoved() instead of checking for null/undefined.',
-      avoidNotInDocument: 'Avoid .not.toBeInTheDocument() without proper waiting.'
+      useWaitForRemoval: 'Avoid checking for null/undefined without proper waiting. Wrap in waitFor() to handle timing.',
+      avoidNotInDocument: 'Avoid .not.toBeInTheDocument() without proper waiting.',
+      avoidNotVisibleWithoutWaitFor: 'Avoid .not.toBeVisible() without proper waiting. Wrap in waitFor() to handle timing.',
+      avoidNotInDocumentNoEvidence: 'Element absence check without prior presence evidence. If the element was removed by an action, wrap in waitFor().',
+      useWaitForRemovalNoEvidence: 'Element null/undefined check without prior presence evidence. If the element was removed by an action, wrap in waitFor().',
+      avoidNotVisibleNoEvidence: 'Element not-visible check without prior presence evidence. If the element was hidden by an action, wrap in waitFor().'
     }
   },
 
@@ -28,34 +33,196 @@ module.exports = {
       return {};
     }
 
+    function isInsideWaitFor(node) {
+      let parent = node.parent;
+      while (parent && parent.type !== 'Program') {
+        if (parent.type === 'CallExpression') {
+          const calleeName = parent.callee.name ||
+            (parent.callee.property && parent.callee.property.name);
+          if (calleeName === 'waitFor' || calleeName === 'waitForElementToBeRemoved') {
+            return true;
+          }
+        }
+        parent = parent.parent;
+      }
+      return false;
+    }
+
+    /**
+     * Find the enclosing it()/test() block body as an array of statements.
+     */
+    function findTestBody(node) {
+      let current = node.parent;
+      while (current) {
+        if (current.type === 'CallExpression' &&
+            current.callee && current.callee.type === 'Identifier' &&
+            (current.callee.name === 'it' || current.callee.name === 'test' || current.callee.name === 'specify')) {
+          // The callback is the second argument (or first if no description)
+          const callback = current.arguments[1] || current.arguments[0];
+          if (callback && callback.body && callback.body.type === 'BlockStatement') {
+            return callback.body.body;
+          }
+        }
+        current = current.parent;
+      }
+      return null;
+    }
+
+    /**
+     * Extract the query target text from an assertion node for matching.
+     * Returns the literal string/regex argument of the query call, or null if unmatchable.
+     */
+    function extractQueryTarget(node) {
+      // Walk up to find the expect() call
+      let expectCall = null;
+      let current = node;
+      while (current) {
+        if (current.type === 'CallExpression' && current.callee && current.callee.name === 'expect') {
+          expectCall = current;
+          break;
+        }
+        if (current.type === 'MemberExpression') {
+          current = current.object;
+          continue;
+        }
+        if (current.type === 'CallExpression' && current.callee) {
+          current = current.callee;
+          continue;
+        }
+        break;
+      }
+
+      if (!expectCall || !expectCall.arguments[0]) return null;
+      const arg = expectCall.arguments[0];
+
+      // arg should be a query call: queryByText('X'), screen.queryByRole('X')
+      let queryCall = arg;
+      if (queryCall.type !== 'CallExpression') return null;
+      if (!queryCall.arguments[0]) return null;
+
+      const firstArg = queryCall.arguments[0];
+      if (firstArg.type === 'Literal' && typeof firstArg.value === 'string') {
+        return { type: 'string', value: firstArg.value };
+      }
+      if (firstArg.regex) {
+        return { type: 'regex', pattern: firstArg.regex.pattern, flags: firstArg.regex.flags };
+      }
+      return null; // unmatchable (variable, template, function call)
+    }
+
+    /**
+     * Check if a statement node contains a positive assertion or usage matching the given target.
+     */
+    function statementMatchesTarget(stmt, target) {
+      const sourceCode = context.getSourceCode();
+      const stmtText = sourceCode.getText(stmt);
+
+      // Check for positive assertions: getByText('X'), getByRole('X'), etc.
+      // or expect(getByText('X')).toBeInTheDocument()
+      if (target.type === 'string') {
+        // Look for getBy/findBy calls with the same string argument
+        const escapedValue = target.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const pattern = new RegExp(`(?:getBy|findBy)\\w+\\s*\\(\\s*['"]${escapedValue}['"]`);
+        return pattern.test(stmtText);
+      }
+      if (target.type === 'regex') {
+        const pattern = new RegExp(`(?:getBy|findBy)\\w+\\s*\\(\\s*/${target.pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/${target.flags}`);
+        return pattern.test(stmtText);
+      }
+      return false;
+    }
+
+    /**
+     * Check if there is evidence that an element was present and then removed.
+     * Evidence = prior userEvent interaction + (optional) prior positive assertion on the same target.
+     * fireEvent is sync so it's NOT evidence (element removed synchronously).
+     */
+    function hasRemovalEvidence(node) {
+      const testBody = findTestBody(node);
+      if (!testBody) return false;
+
+      const target = extractQueryTarget(node);
+
+      // Find the index of the current statement in the test body
+      let currentStmt = node;
+      while (currentStmt && currentStmt.parent && currentStmt.parent.type !== 'BlockStatement') {
+        currentStmt = currentStmt.parent;
+      }
+      const currentIndex = testBody.indexOf(currentStmt);
+      if (currentIndex === -1) return false; // Node not found in this block
+      if (currentIndex === 0) return false;  // First statement — no prior evidence possible
+
+      const sourceCode = context.getSourceCode();
+      let hasUserEvent = false;
+      let hasPositiveAssertion = false;
+
+      for (let i = 0; i < currentIndex; i++) {
+        const stmtText = sourceCode.getText(testBody[i]);
+        if (/userEvent\.\w+\s*\(/.test(stmtText)) {
+          hasUserEvent = true;
+        }
+        if (target && statementMatchesTarget(testBody[i], target)) {
+          hasPositiveAssertion = true;
+        }
+      }
+
+      // Evidence: userEvent interaction + either matchable target with positive assertion, or unmatchable target
+      if (hasUserEvent && (!target || hasPositiveAssertion)) return true;
+      return false;
+    }
+
+    function createWaitForFix(node) {
+      return function(fixer) {
+        const sourceCode = context.getSourceCode();
+        // Find the containing expression statement
+        let statement = node.parent;
+        while (statement && statement.type !== 'ExpressionStatement') {
+          statement = statement.parent;
+        }
+        if (!statement || !statement.expression) return null;
+
+        const importFixes = addWaitForImport(fixer, context);
+        if (importFixes === null) return null; // Skip fix for incompatible frameworks
+
+        const funcNode = findEnclosingFunction(node);
+        const asyncFixes = ensureAsyncFunction(fixer, funcNode);
+        if (asyncFixes === null) return null; // Skip fix for getters/setters/constructors
+
+        const statementText = sourceCode.getText(statement.expression);
+
+        return [
+          fixer.replaceText(
+            statement,
+            `await waitFor(() => { ${statementText}; });`
+          ),
+          ...asyncFixes,
+          ...importFixes
+        ];
+      };
+    }
+
     function checkNotToBeInTheDocument(node) {
       // Check for expect().not.toBeInTheDocument() patterns
       if (node.callee.type === 'MemberExpression' &&
           node.callee.property.name === 'toBeInTheDocument') {
-        
+
         const expectCall = node.callee.object;
         if (expectCall.type === 'MemberExpression' &&
             expectCall.property.name === 'not') {
-          
-          // Check if it's wrapped in waitFor
-          let parent = node.parent;
-          let insideWaitFor = false;
-          
-          while (parent && parent.type !== 'Program') {
-            if (parent.type === 'CallExpression' &&
-                (parent.callee.name === 'waitFor' ||
-                 parent.callee.name === 'waitForElementToBeRemoved')) {
-              insideWaitFor = true;
-              break;
+
+          if (!isInsideWaitFor(node)) {
+            if (hasRemovalEvidence(node)) {
+              context.report({
+                node,
+                messageId: 'avoidNotInDocument',
+                fix: createWaitForFix(node)
+              });
+            } else {
+              context.report({
+                node,
+                messageId: 'avoidNotInDocumentNoEvidence'
+              });
             }
-            parent = parent.parent;
-          }
-          
-          if (!insideWaitFor) {
-            context.report({
-              node,
-              messageId: 'avoidNotInDocument'
-            });
           }
         }
       }
@@ -88,11 +255,19 @@ module.exports = {
                                    arg.callee.property &&
                                    (/^query/.test(arg.callee.property.name) || arg.callee.property.name === 'querySelector');
 
-            if (isQueryMethod || isScreenQuery || isContainerQuery) {
-              context.report({
-                node,
-                messageId: 'useWaitForRemoval'
-              });
+            if ((isQueryMethod || isScreenQuery || isContainerQuery) && !isInsideWaitFor(node)) {
+              if (hasRemovalEvidence(node)) {
+                context.report({
+                  node,
+                  messageId: 'useWaitForRemoval',
+                  fix: createWaitForFix(node)
+                });
+              } else {
+                context.report({
+                  node,
+                  messageId: 'useWaitForRemovalNoEvidence'
+                });
+              }
             }
           }
         }
@@ -125,11 +300,19 @@ module.exports = {
                                   arg.callee.property &&
                                   /^query/.test(arg.callee.property.name);
 
-              if (isQueryMethod || isScreenQuery) {
-                context.report({
-                  node,
-                  messageId: 'useWaitForRemoval'
-                });
+              if ((isQueryMethod || isScreenQuery) && !isInsideWaitFor(node)) {
+                if (hasRemovalEvidence(node)) {
+                  context.report({
+                    node,
+                    messageId: 'useWaitForRemoval',
+                    fix: createWaitForFix(node)
+                  });
+                } else {
+                  context.report({
+                    node,
+                    messageId: 'useWaitForRemovalNoEvidence'
+                  });
+                }
               }
             }
           }
@@ -151,10 +334,17 @@ module.exports = {
                           (nonNullSide.callee.property && nonNullSide.callee.property.name);
 
           if (queryName && /^query/.test(queryName)) {
-            context.report({
-              node,
-              messageId: 'useWaitForRemoval'
-            });
+            if (hasRemovalEvidence(node)) {
+              context.report({
+                node,
+                messageId: 'useWaitForRemoval'
+              });
+            } else {
+              context.report({
+                node,
+                messageId: 'useWaitForRemovalNoEvidence'
+              });
+            }
           }
         }
       }
@@ -169,25 +359,19 @@ module.exports = {
         if (expectCall.type === 'MemberExpression' &&
             expectCall.property.name === 'not') {
 
-          // Check if it's wrapped in waitFor
-          let parent = node.parent;
-          let insideWaitFor = false;
-
-          while (parent && parent.type !== 'Program') {
-            if (parent.type === 'CallExpression' &&
-                (parent.callee.name === 'waitFor' ||
-                 parent.callee.name === 'waitForElementToBeRemoved')) {
-              insideWaitFor = true;
-              break;
+          if (!isInsideWaitFor(node)) {
+            if (hasRemovalEvidence(node)) {
+              context.report({
+                node,
+                messageId: 'avoidNotVisibleWithoutWaitFor',
+                fix: createWaitForFix(node)
+              });
+            } else {
+              context.report({
+                node,
+                messageId: 'avoidNotVisibleNoEvidence'
+              });
             }
-            parent = parent.parent;
-          }
-
-          if (!insideWaitFor) {
-            context.report({
-              node,
-              messageId: 'avoidNotInDocument'
-            });
           }
         }
       }

package/lib/rules/no-immediate-assertions.js

@@ -4,7 +4,7 @@
  */
 'use strict';
 
-const { isTestFile, findEnclosingFunction, ensureAsyncFunction, addWaitForImport, getTestFramework } = require('../utils/helpers');
+const { isTestFile, getFilename, findEnclosingFunction, ensureAsyncFunction, addWaitForImport, getTestFramework } = require('../utils/helpers');
 
 module.exports = {
   meta: {
@@ -49,7 +49,7 @@ module.exports = {
   },
 
   create(context) {
-    if (!isTestFile(context.getFilename())) {
+    if (!isTestFile(getFilename(context))) {
       return {};
     }
 
@@ -61,10 +61,31 @@ module.exports = {
 
     const stateChangingPatterns = [
       'setState', 'setProps', 'dispatch', 'commit',
-      'click', 'type', 'change', 'submit', 'fireEvent',
+      'click', 'type', 'change', 'submit',
       'userEvent', 'simulate', 'trigger'
     ];
 
+    /**
+     * Returns true when the node is a fireEvent.* call (synchronous action).
+     * fireEvent is sync — React Testing Library flushes synchronously within act(),
+     * so assertions immediately after fireEvent are correct as-is.
+     */
+    function isSyncFireEvent(node) {
+      // Unwrap `await fireEvent.click()` — still a sync fireEvent even if mistakenly awaited
+      const target = node.type === 'AwaitExpression' ? node.argument : node;
+      if (!target || target.type !== 'CallExpression') return false;
+      const callee = target.callee;
+      // fireEvent.click(...), fireEvent.change(...), etc.
+      if (callee.type === 'MemberExpression' && callee.object && callee.object.name === 'fireEvent') {
+        return true;
+      }
+      // Direct fireEvent(...) call
+      if (callee.type === 'Identifier' && callee.name === 'fireEvent') {
+        return true;
+      }
+      return false;
+    }
+
     function isStateChangingAction(node) {
       if (node.type !== 'CallExpression') return false;
 
@@ -174,6 +195,11 @@ module.exports = {
       if (node.type === 'ExpressionStatement' &&
           isStateChangingAction(node.expression)) {
 
+        // Skip fireEvent — it's synchronous, assertions after it are fine
+        if (isSyncFireEvent(node.expression)) {
+          return;
+        }
+
         // Check the next statement
         const nextStatement = statements[currentIndex + 1];
         if (nextStatement &&
@@ -283,6 +309,11 @@ module.exports = {
           if (isStateChangingAction(expressions[i]) &&
               isExpectCall(expressions[i + 1])) {
 
+            // Skip fireEvent — synchronous action
+            if (isSyncFireEvent(expressions[i])) {
+              continue;
+            }
+
             // Skip if requireWaitFor is false
             if (!requireWaitFor) {
               continue;

package/lib/rules/no-long-text-match.js

@@ -16,6 +16,7 @@ module.exports = {
       url: 'https://github.com/tigredonorte/eslint-plugin-test-flakiness/blob/main/docs/rules/no-long-text-match.md'
     },
     fixable: null,
+    hasSuggestions: true,
     schema: [
       {
         type: 'object',
@@ -44,7 +45,9 @@ module.exports = {
       textTooLong: 'Text match of {{length}} characters is too long and brittle. Use partial matches or data-testid.',
       usePartialMatch: 'Use partial text matching or regex for long content.',
       useTestId: 'Consider using data-testid for element selection instead of text content.',
-      avoidExactMatch: 'Exact matching of long dynamic content is fragile.'
+      avoidExactMatch: 'Exact matching of long dynamic content is fragile.',
+      suggestExactFalse: 'Add { exact: false } option for partial matching.',
+      suggestUseRegex: 'Convert to regex pattern for partial matching.'
     }
   },
 
@@ -72,7 +75,43 @@ module.exports = {
       DECIMAL_NUMBERS: /\d+[.,]\d+[.,]\d+/ // Multiple decimal/comma separated numbers
     };
 
-    function checkTextContent(node, text) {
+    function createTextSuggestions(callNode, textNode, text) {
+      const suggestions = [];
+
+      // Suggestion 1: Add { exact: false }
+      if (callNode && callNode.arguments) {
+        const hasSecondArg = callNode.arguments.length > 1;
+        if (!hasSecondArg) {
+          suggestions.push({
+            messageId: 'suggestExactFalse',
+            fix(fixer) {
+              return fixer.insertTextAfter(textNode, ', { exact: false }');
+            }
+          });
+        }
+      }
+
+      // Suggestion 2: Convert to regex (use up to 3 significant words for a more targeted pattern)
+      if (textNode && textNode.type === 'Literal' && typeof textNode.value === 'string') {
+        const words = text.split(/\s+/).filter(w => w.length > 3);
+        if (words.length > 0) {
+          const keywordWords = words.slice(0, 3).map(w =>
+            w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\//g, '\\/')
+          );
+          const keyword = keywordWords.join('\\s+');
+          suggestions.push({
+            messageId: 'suggestUseRegex',
+            fix(fixer) {
+              return fixer.replaceText(textNode, `/${keyword}/`);
+            }
+          });
+        }
+      }
+
+      return suggestions.length > 0 ? suggestions : undefined;
+    }
+
+    function checkTextContent(node, text, suggestions) {
       if (typeof text !== 'string') return;
 
       // Ignore if it's in a comment
@@ -94,14 +133,20 @@ module.exports = {
                          DYNAMIC_PATTERNS.TEMPLATE_VAR.test(text) ||
                          DYNAMIC_PATTERNS.DECIMAL_NUMBERS.test(text);
 
-        context.report({
+        const report = {
           node,
           messageId: isDynamic ? 'avoidExactMatch' : 'textTooLong',
           data: {
             length: text.length,
             maxLength: maxLength
           }
-        });
+        };
+
+        if (suggestions) {
+          report.suggest = suggestions;
+        }
+
+        context.report(report);
       }
     }
 
@@ -143,7 +188,7 @@ module.exports = {
 
           if (arg && arg.type === 'Literal') {
             if (typeof arg.value === 'string') {
-              checkTextContent(arg, arg.value);
+              checkTextContent(arg, arg.value, createTextSuggestions(node, arg, arg.value));
             } else if (arg.regex) {
               // For regex literals, check the pattern length
               const patternLength = arg.regex.pattern.length;
@@ -202,7 +247,7 @@ module.exports = {
 
           if (arg && arg.type === 'Literal') {
             if (typeof arg.value === 'string') {
-              checkTextContent(arg, arg.value);
+              checkTextContent(arg, arg.value, createTextSuggestions(node, arg, arg.value));
             } else if (arg.regex) {
               // For regex literals, check the pattern length
               const patternLength = arg.regex.pattern.length;
@@ -258,7 +303,7 @@ module.exports = {
 
           if (arg && arg.type === 'Literal') {
             if (typeof arg.value === 'string') {
-              checkTextContent(arg, arg.value);
+              checkTextContent(arg, arg.value, createTextSuggestions(node, arg, arg.value));
             } else if (arg.regex) {
               // For regex literals, check the pattern length
               const patternLength = arg.regex.pattern.length;

package/lib/utils/helpers.js

@@ -540,9 +540,39 @@ function addWaitForImport(fixer, context) {
     }
   }
 
-  // No suitable import found — add a new one at the top of the file
+  // Try to augment an existing @testing-library require that actually exports waitFor
+  if (ast && ast.body) {
+    for (const node of ast.body) {
+      if (node.type === 'VariableDeclaration') {
+        for (const decl of node.declarations) {
+          if (!decl.init) continue;
+          const init = decl.init;
+          const isRequire = init.type === 'CallExpression' && init.callee && init.callee.name === 'require';
+          if (!isRequire) continue;
+          const requireArg = init.arguments && init.arguments[0];
+          if (!requireArg || !WAITFOR_MODULES.has(requireArg.value)) continue;
+          if (decl.id.type === 'ObjectPattern' && decl.id.properties.length > 0) {
+            const lastProp = decl.id.properties[decl.id.properties.length - 1];
+            return [fixer.insertTextAfter(lastProp, ', waitFor')];
+          }
+        }
+      }
+    }
+  }
+
+  // No suitable import/require found — add a new one at the top of the file.
+  // Default to @testing-library/react since it's the most common testing-library package.
+  // Detect CJS by looking for top-level require() calls; default to ESM otherwise.
   const firstNode = ast && ast.body && ast.body[0];
   if (firstNode) {
+    const isCJS = ast.body.some(n =>
+      n.type === 'VariableDeclaration' && n.declarations.some(d =>
+        d.init && d.init.type === 'CallExpression' && d.init.callee && d.init.callee.name === 'require'
+      )
+    );
+    if (isCJS) {
+      return [fixer.insertTextBefore(firstNode, 'const { waitFor } = require(\'@testing-library/react\');\n')];
+    }
     return [fixer.insertTextBefore(firstNode, 'import { waitFor } from \'@testing-library/react\';\n')];
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-test-flakiness",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "ESLint plugin to detect flaky test patterns and suggest fixes",
   "keywords": [
     "eslint",
@@ -27,6 +27,9 @@
     "test:coverage": "jest --coverage",
     "test:ci": "jest --ci --coverage --maxWorkers=2",
     "lint": "eslint .",
+    "dev:check": "bash scripts/dev-lint.sh --main && bash scripts/dev-test.sh --main",
+    "dev:lint": "bash scripts/dev-lint.sh",
+    "dev:test": "bash scripts/dev-test.sh",
     "lint:fix": "eslint . --fix",
     "lint:markdown": "npx markdownlint-cli '**/*.md' '.github/**/*.md' --ignore node_modules --config .markdownlintrc.json",
     "lint:markdown:fix": "npx markdownlint-cli '**/*.md' '.github/**/*.md' --ignore node_modules --config .markdownlintrc.json --fix",