noctcore-code-quality/skipped-tests-need-tracking
noctcore-code-quality/skipped-tests-need-tracking
- Package
- code-quality v1.0.0
- Preset
- recommended
- Severity
- error
- Autofix
- No
- Suggestions
- Yes
- Options
- Optional
- Type info
- Not needed
A skipped test must carry a tracking marker (issue URL or TODO(@owner)) so the debt has an owner.
.skip / .fixme / xit / xdescribe are escape hatches. Left unowned they rot into permanent dark
zones — nobody remembers why the test is off or who is meant to turn it back on. Requiring a tracking
marker (an issue URL or a TODO(@owner)) within a few lines of the skip keeps a human attached to the
debt.
.only is deliberately not covered here — no-focused-tests bans it
outright, so it can never legitimately appear with or without tracking.
What it flags
Section titled “What it flags”Any call of a skip form (it.skip( / test.skip( / describe.skip(, the .fixme( variants,
xit(, xdescribe(, xtest(, and a skip modifier anywhere in the chain such as
it.concurrent.skip( or it.skip.each([...])() with no tracking marker in a comment on that line
or within the lookback lines above it. The report sits on the callee (it.skip, xit), and offers
a suggestion that inserts a // TODO(@owner): link the tracking issue line above the skip for you to
complete.
The marker is read from comments only. A comment counts when it is on the skip’s line or ends within
the lookback window, and so does every comment in the same run of adjacent comment lines, so a
URL at the top of a five-line // explanation still counts. Code never counts: a
const BASE = 'http://localhost:3000' above a skip is not a marker. A node:test skip reason given as
text ({ skip: 'https://...' }, t.skip('TODO(@alice)')) counts too.
// untrackedit.skip('later', () => {});xdescribe('later', () => {});// tracked// TODO(@alice): flaky under CIit.skip('later', () => {});
it.skip('later', () => {}); // https://github.com/org/repo/issues/1node:test skips
Section titled “node:test skips”node:test skips through the test’s options or its context, the same way it spells a platform
guard. Only an unconditional skip is reported, on the option or the call:
- a
skiportodooption ontest/it/describe/suite(and at.testsubtest) whose value is a truthy literal:{ skip: true },{ skip: 1 },{ todo: 'write it' }; t.skip()/t.todo()(orawait t.skip()) as a statement of the test callback’s own body, wheretis the callback’s context parameter.
test('publishes the tarball', { skip: 'broken on the new registry' }, async () => {});
test('signs the release', (t) => { t.todo('needs the new key');});// TODO(@alice): the new registry rejects the tarballtest('publishes the tarball', { skip: 'broken on the new registry' }, async () => {});
test('signs the release', (t) => { t.todo('needs the new key, https://github.com/org/repo/issues/12');});What it does not flag
Section titled “What it does not flag”- A test that is not skipped.
- A skip with a
markersmatch in a comment on its own line or within thelookbacklines above it. - Playwright’s conditional skip,
test.skip(browserName === 'webkit', 'reason'): the first argument is a condition rather than a test name, and no argument is the test body.test.skip()andtest.skip(true, 'reason')are unconditional and still reported. .only:no-focused-testsbans it outright.- A conditional
node:testskip: an option whose value is computed ({ skip: process.platform === 'win32' },{ skip: !ready }, shorthand{ skip }), or at.skip(...)inside anif, a loop or a helper. Those are platform or environment guards. - A
skip/todokey in an object passed to anything that is not a test runner, and askipmethod on a receiver that is not the test’s context (query.skip(10)). - The text of a skip that is not a call: inside a string, a template literal or a comment. A test that lints probe code held as a string can spell a skipped test in its own source.
test('uses POSIX signals', { skip: process.platform === 'win32' }, () => {});
test('kills the process group', (t) => { if (process.platform === 'win32') { t.skip('taskkill ends a Windows tree at once'); return; }});// A probe for the linter, e.g. it.skip('later', () => {}), is not a skipped test.const probe = "it.skip('later', () => {});";
it('reports an untracked skip', async () => { expect(await lint(probe)).toHaveLength(1);});Options
Section titled “Options”| Option | Type | Default | Meaning |
|---|---|---|---|
markers |
string[] (regex sources) |
["https?://\\S+", "TODO\\(@?\\S+\\)"] |
Any pattern that, if found in a comment in the lookback window, satisfies the tracking requirement. Compiled with the u flag. |
lookback |
integer (≥0) |
3 |
How many lines above the skip a comment may end and still count (with the rest of its comment run). |
// Require a Jira-style key instead of a URL / TODO.'noctcore-code-quality/skipped-tests-need-tracking': ['error', { markers: ['[A-Z]+-\\d+'] }]When not to use it
Section titled “When not to use it”If your project already enforces skip-tracking another way, or never skips tests.