ESLint for Test Quality
This skill makes an AI agent wire ESLint plugins that lint the tests themselves - catching focused tests that silently skip entire suites in CI, assertion-free tests, conditional expects, and flaky waitForTimeout calls before they merge. Trigger it when a project has test files but no test-specific lint rules, when an it.only ever reaches main, or when the user asks to "lint tests", "block .only", or "enforce testing best practices".
Core Principles
- A committed
.only is a silent CI outage. it.only makes every other test in the file stop running while the build stays green. no-focused-tests set to error is the single highest-value test lint rule; it is non-negotiable.
- Tests without assertions must fail the lint. A test that calls code and asserts nothing passes forever.
expect-expect (Jest/Playwright) turns these into lint errors and accepts custom assertion wrappers via configuration.
- Lint rules encode review comments you are tired of writing. "Do not put expects in conditionals", "use userEvent not fireEvent", "no waitForTimeout" - each has a rule; automate the comment.
- Scope test rules to test files only. Apply plugin configs with
files: ['**/*.test.ts'] globs in flat config so production code is not subjected to test rules and vice versa.
- Warnings are noise; errors are gates. CI must run with
--max-warnings 0 or set every rule you care about to error. A warning that scrolls by in CI logs changes nothing.
- Adopt recommended configs first, then tighten. Start from
flat/recommended for each plugin, then promote the high-signal rules (no-conditional-expect, no-standalone-expect, prefer-user-event) to error as the suite cleans up.
Setup
npm install --save-dev eslint eslint-plugin-jest eslint-plugin-testing-library \
eslint-plugin-jest-dom eslint-plugin-playwright
Flat config with per-suite scoping
// eslint.config.js
import jest from 'eslint-plugin-jest';
import testingLibrary from 'eslint-plugin-testing-library';
import jestDom from 'eslint-plugin-jest-dom';
import playwright from 'eslint-plugin-playwright';
export default [
// Unit and component tests (Jest + Testing Library)
{
files: ['src/**/*.test.{ts,tsx}', 'src/**/__tests__/**/*.{ts,tsx}'],
plugins: { jest, 'testing-library': testingLibrary, 'jest-dom': jestDom },
languageOptions: { globals: jest.environments.globals.globals },
rules: {
...jest.configs['flat/recommended'].rules,
...testingLibrary.configs['flat/react'].rules,
...jestDom.configs['flat/recommended'].rules,
'jest/no-focused-tests': 'error',
'jest/no-disabled-tests': 'warn',
'jest/no-conditional-expect': 'error',
'jest/no-standalone-expect': 'error',
'jest/valid-title': 'error',
'jest/prefer-hooks-on-top': 'error',
'jest/expect-expect': [
'error',
{ assertFunctionNames: ['expect', 'expectTypeOf', 'assertOrderShape'] },
],
'testing-library/prefer-user-event': 'error',
'testing-library/no-wait-for-side-effects': 'error',
'testing-library/no-manual-cleanup': 'error',
},
},
// Playwright E2E specs
{
files: ['e2e/**/*.spec.ts'],
plugins: { playwright },
rules: {
...playwright.configs['flat/recommended'].rules,
'playwright/no-focused-test': 'error',
'playwright/no-skipped-test': 'warn',
'playwright/no-wait-for-timeout': 'error',
'playwright/no-conditional-in-test': 'error',
'playwright/no-force-option': 'error',
'playwright/expect-expect': 'error',
'playwright/no-networkidle': 'error',
'playwright/prefer-web-first-assertions': 'error',
},
},
];
Patterns
1. What the rules actually catch
// e2e/checkout.spec.ts - every line below is a lint ERROR with the config above
test.only('applies a coupon', async ({ page }) => {
// playwright/no-focused-test: the other 84 specs in this project
// would silently not run in CI while the build stays green.
});
test('waits for the cart to update', async ({ page }) => {
await page.waitForTimeout(3000); // playwright/no-wait-for-timeout: flaky AND slow
await page.click('#checkout', { force: true }); // playwright/no-force-option: bypasses actionability
});
test('shows totals', async ({ page }) => {
const rows = await page.locator('.row').count();
if (rows > 0) {
expect(rows).toBeGreaterThan(0); // playwright/no-conditional-in-test
}
// playwright/expect-expect also fires if no assertion is reachable
});
// src/components/CouponForm.test.tsx - Jest + Testing Library violations
it('test 1', async () => {
// jest/valid-title: meaningless title
render(<CouponForm />);
fireEvent.change(screen.getByRole('textbox'), { target: { value: 'SAVE10' } });
// testing-library/prefer-user-event: fireEvent skips focus/keyboard semantics
});
it('submits the coupon', async () => {
try {
await submitCoupon('SAVE10');
expect(api.apply).toHaveBeenCalled();
} catch {
expect(true).toBe(false); // jest/no-conditional-expect: may never run
}
});
2. Teaching expect-expect about custom assertion helpers
// tests/helpers/assert-order-shape.ts
import { expect } from 'vitest';
// Custom assertion helper used across suites
export function assertOrderShape(order: unknown): void {
expect(order).toMatchObject({
id: expect.stringMatching(/^ord_/),
total: expect.any(Number),
items: expect.arrayContaining([expect.objectContaining({ sku: expect.any(String) })]),
});
}
// Registered above via expect-expect assertFunctionNames so tests
// that only call assertOrderShape(...) do not trip the rule.
3. CI lint gate that blocks merges
# .github/workflows/lint.yml
name: lint
on: [pull_request]
jobs:
eslint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- name: Lint (zero warnings allowed)
run: npx eslint . --max-warnings 0
4. Pre-commit guard for the fast feedback loop
npm install --save-dev husky lint-staged
npx husky init
{
"lint-staged": {
"*.{ts,tsx,js}": ["eslint --fix --max-warnings 0"]
}
}
# .husky/pre-commit
npx lint-staged
Best Practices
- Run
eslint --fix first when adopting rules on an existing suite; many testing-library rules (such as query preferences) auto-fix.
- Pair
jest/no-disabled-tests as warn with a tracking convention: every it.skip requires a linked ticket in a comment.
- Add
playwright/no-networkidle and prefer-web-first-assertions early; they remove the two most common Playwright flake sources.
- For Vitest projects, use
eslint-plugin-vitest (largely rule-compatible with eslint-plugin-jest) and the same scoping strategy.
- Keep the lint job separate from the test job in CI so a lint failure reports in seconds, not after a 10-minute test run.
- Re-run
npx eslint . --max-warnings 0 locally before pushing; the gate exists to be unreachable, not to be hit.
Anti-Patterns
- Putting test rules in the global config so production files get flagged for "missing expect" and developers disable the plugin entirely.
- Setting
no-focused-tests to warn: the one severity that cannot stop the exact accident the rule exists for.
- Blanket
// eslint-disable-next-line comments without a reason; require --report-unused-disable-directives (or linterOptions.reportUnusedDisableDirectives) to keep disables honest.
- Linting only changed files in CI while the repository still contains
.only from last month - run the full lint, it is cheap.
- Treating the lint gate as optional ("we will fix warnings later"): later never arrives; gate at zero from day one on new projects.
- Writing a custom rule for something
eslint-plugin-jest already ships; check the plugin's rule list first.
When to Trigger This Skill
- A repository has Jest, Vitest, Playwright, or Testing Library tests but
eslint.config.js contains no test-specific plugins.
- An
it.only, test.only, or fdescribe was found on the main branch, or CI passed while most tests silently did not run.
- The user asks to "lint tests", "ban waitForTimeout", "enforce userEvent", "block focused tests", or "add a lint gate to CI".
- Migrating from
.eslintrc to flat config and the test-file overrides need translating into files-scoped config objects.
- Code review keeps repeating the same test-hygiene comments; convert each into the matching rule and let the linter say it.
1---2name: eslint-for-test-quality3description: Enforce test quality with ESLint - eslint-plugin-jest, eslint-plugin-playwright, and eslint-plugin-testing-library rules in flat config, blocking focused tests, missing assertions, and flaky waits via a CI lint gate.4version: 1.0.05author: thetestingacademy6license: MIT7tags: [eslint, lint, test-quality, jest, playwright, testing-library, flat-config, ci, code-quality]8testingTypes: [code-quality]9frameworks: [jest, playwright, vitest]10languages: [javascript, typescript]11domains: [web]12agents: [claude-code, cursor, github-copilot, windsurf, codex, aider, continue, cline, zed, bolt, gemini-cli, amp]13metadata:14 source: https://skillmd.com/skills/pramoddutta/eslint-for-test-quality15---1617# ESLint for Test Quality1819This skill makes an AI agent wire ESLint plugins that lint the tests themselves - catching focused tests that silently skip entire suites in CI, assertion-free tests, conditional expects, and flaky `waitForTimeout` calls before they merge. Trigger it when a project has test files but no test-specific lint rules, when an `it.only` ever reaches main, or when the user asks to "lint tests", "block .only", or "enforce testing best practices".2021## Core Principles22231. **A committed `.only` is a silent CI outage.** `it.only` makes every other test in the file stop running while the build stays green. `no-focused-tests` set to `error` is the single highest-value test lint rule; it is non-negotiable.242. **Tests without assertions must fail the lint.** A test that calls code and asserts nothing passes forever. `expect-expect` (Jest/Playwright) turns these into lint errors and accepts custom assertion wrappers via configuration.253. **Lint rules encode review comments you are tired of writing.** "Do not put expects in conditionals", "use userEvent not fireEvent", "no waitForTimeout" - each has a rule; automate the comment.264. **Scope test rules to test files only.** Apply plugin configs with `files: ['**/*.test.ts']` globs in flat config so production code is not subjected to test rules and vice versa.275. **Warnings are noise; errors are gates.** CI must run with `--max-warnings 0` or set every rule you care about to `error`. A warning that scrolls by in CI logs changes nothing.286. **Adopt recommended configs first, then tighten.** Start from `flat/recommended` for each plugin, then promote the high-signal rules (`no-conditional-expect`, `no-standalone-expect`, `prefer-user-event`) to error as the suite cleans up.2930## Setup3132```bash33npm install --save-dev eslint eslint-plugin-jest eslint-plugin-testing-library \34 eslint-plugin-jest-dom eslint-plugin-playwright35```3637### Flat config with per-suite scoping3839```js40// eslint.config.js41import jest from 'eslint-plugin-jest';42import testingLibrary from 'eslint-plugin-testing-library';43import jestDom from 'eslint-plugin-jest-dom';44import playwright from 'eslint-plugin-playwright';4546export default [47 // Unit and component tests (Jest + Testing Library)48 {49 files: ['src/**/*.test.{ts,tsx}', 'src/**/__tests__/**/*.{ts,tsx}'],50 plugins: { jest, 'testing-library': testingLibrary, 'jest-dom': jestDom },51 languageOptions: { globals: jest.environments.globals.globals },52 rules: {53 ...jest.configs['flat/recommended'].rules,54 ...testingLibrary.configs['flat/react'].rules,55 ...jestDom.configs['flat/recommended'].rules,56 'jest/no-focused-tests': 'error',57 'jest/no-disabled-tests': 'warn',58 'jest/no-conditional-expect': 'error',59 'jest/no-standalone-expect': 'error',60 'jest/valid-title': 'error',61 'jest/prefer-hooks-on-top': 'error',62 'jest/expect-expect': [63 'error',64 { assertFunctionNames: ['expect', 'expectTypeOf', 'assertOrderShape'] },65 ],66 'testing-library/prefer-user-event': 'error',67 'testing-library/no-wait-for-side-effects': 'error',68 'testing-library/no-manual-cleanup': 'error',69 },70 },71 // Playwright E2E specs72 {73 files: ['e2e/**/*.spec.ts'],74 plugins: { playwright },75 rules: {76 ...playwright.configs['flat/recommended'].rules,77 'playwright/no-focused-test': 'error',78 'playwright/no-skipped-test': 'warn',79 'playwright/no-wait-for-timeout': 'error',80 'playwright/no-conditional-in-test': 'error',81 'playwright/no-force-option': 'error',82 'playwright/expect-expect': 'error',83 'playwright/no-networkidle': 'error',84 'playwright/prefer-web-first-assertions': 'error',85 },86 },87];88```8990## Patterns9192### 1. What the rules actually catch9394```ts95// e2e/checkout.spec.ts - every line below is a lint ERROR with the config above9697test.only('applies a coupon', async ({ page }) => {98 // playwright/no-focused-test: the other 84 specs in this project99 // would silently not run in CI while the build stays green.100});101102test('waits for the cart to update', async ({ page }) => {103 await page.waitForTimeout(3000); // playwright/no-wait-for-timeout: flaky AND slow104 await page.click('#checkout', { force: true }); // playwright/no-force-option: bypasses actionability105});106107test('shows totals', async ({ page }) => {108 const rows = await page.locator('.row').count();109 if (rows > 0) {110 expect(rows).toBeGreaterThan(0); // playwright/no-conditional-in-test111 }112 // playwright/expect-expect also fires if no assertion is reachable113});114```115116```tsx117// src/components/CouponForm.test.tsx - Jest + Testing Library violations118119it('test 1', async () => {120 // jest/valid-title: meaningless title121 render(<CouponForm />);122 fireEvent.change(screen.getByRole('textbox'), { target: { value: 'SAVE10' } });123 // testing-library/prefer-user-event: fireEvent skips focus/keyboard semantics124});125126it('submits the coupon', async () => {127 try {128 await submitCoupon('SAVE10');129 expect(api.apply).toHaveBeenCalled();130 } catch {131 expect(true).toBe(false); // jest/no-conditional-expect: may never run132 }133});134```135136### 2. Teaching expect-expect about custom assertion helpers137138```ts139// tests/helpers/assert-order-shape.ts140import { expect } from 'vitest';141142// Custom assertion helper used across suites143export function assertOrderShape(order: unknown): void {144 expect(order).toMatchObject({145 id: expect.stringMatching(/^ord_/),146 total: expect.any(Number),147 items: expect.arrayContaining([expect.objectContaining({ sku: expect.any(String) })]),148 });149}150// Registered above via expect-expect assertFunctionNames so tests151// that only call assertOrderShape(...) do not trip the rule.152```153154### 3. CI lint gate that blocks merges155156```yaml157# .github/workflows/lint.yml158name: lint159on: [pull_request]160161jobs:162 eslint:163 runs-on: ubuntu-latest164 steps:165 - uses: actions/checkout@v4166 - uses: actions/setup-node@v4167 with:168 node-version: 20169 cache: npm170 - run: npm ci171 - name: Lint (zero warnings allowed)172 run: npx eslint . --max-warnings 0173```174175### 4. Pre-commit guard for the fast feedback loop176177```bash178npm install --save-dev husky lint-staged179npx husky init180```181182```json183{184 "lint-staged": {185 "*.{ts,tsx,js}": ["eslint --fix --max-warnings 0"]186 }187}188```189190```bash191# .husky/pre-commit192npx lint-staged193```194195## Best Practices196197- Run `eslint --fix` first when adopting rules on an existing suite; many testing-library rules (such as query preferences) auto-fix.198- Pair `jest/no-disabled-tests` as `warn` with a tracking convention: every `it.skip` requires a linked ticket in a comment.199- Add `playwright/no-networkidle` and `prefer-web-first-assertions` early; they remove the two most common Playwright flake sources.200- For Vitest projects, use `eslint-plugin-vitest` (largely rule-compatible with eslint-plugin-jest) and the same scoping strategy.201- Keep the lint job separate from the test job in CI so a lint failure reports in seconds, not after a 10-minute test run.202- Re-run `npx eslint . --max-warnings 0` locally before pushing; the gate exists to be unreachable, not to be hit.203204## Anti-Patterns205206- Putting test rules in the global config so production files get flagged for "missing expect" and developers disable the plugin entirely.207- Setting `no-focused-tests` to `warn`: the one severity that cannot stop the exact accident the rule exists for.208- Blanket `// eslint-disable-next-line` comments without a reason; require `--report-unused-disable-directives` (or `linterOptions.reportUnusedDisableDirectives`) to keep disables honest.209- Linting only changed files in CI while the repository still contains `.only` from last month - run the full lint, it is cheap.210- Treating the lint gate as optional ("we will fix warnings later"): later never arrives; gate at zero from day one on new projects.211- Writing a custom rule for something `eslint-plugin-jest` already ships; check the plugin's rule list first.212213## When to Trigger This Skill214215- A repository has Jest, Vitest, Playwright, or Testing Library tests but `eslint.config.js` contains no test-specific plugins.216- An `it.only`, `test.only`, or `fdescribe` was found on the main branch, or CI passed while most tests silently did not run.217- The user asks to "lint tests", "ban waitForTimeout", "enforce userEvent", "block focused tests", or "add a lint gate to CI".218- Migrating from `.eslintrc` to flat config and the test-file overrides need translating into `files`-scoped config objects.219- Code review keeps repeating the same test-hygiene comments; convert each into the matching rule and let the linter say it.