Speed‑Up Your Vitest Feedback Loop with test.only and test.skip

Why Slow Vitest Runs Hurt Your Workflow

When a test suite takes minutes, the developer’s feedback loop stalls. In many projects the culprit is a handful of flaky or long‑running async tests that cause Vitest to retry or block the entire run. The result? A long wait before you can see whether a change broke anything.

Enter test.only and test.skip

Vitest ships with two simple APIs that let you narrow the scope of a run:

• test.only – runs only the marked test(s) or file(s).
• test.skip – excludes the marked test(s) or file(s) from the run.

Both keep the full semantics of test (assertions, hooks, retries) so you still get accurate results, just for a smaller subset.

Using test.only to Isolate Flaky Tests

Suppose you have a test that intermittently fails because of a race condition:

import { test, expect } from 'vitest'

// A flaky async test
export const flakyTest = () => {
  test('async race', async () => {
    const result = await getDataFromApi();
    expect(result).toBe('ok')
  })
}

Running the full suite repeatedly will waste time; instead, add test.only to focus on the problem:

import { test, expect } from 'vitest'

// Mark this test exclusively
export const flakyTest = () => {
  test.only('async race', async () => {
    const result = await getDataFromApi();
    expect(result).toBe('ok')
  })
}

Execute:

npx vitest --watch

Vitest will report only the async race test, showing its status instantly. If the test passes, you can iterate on the fix; if it fails, you know the issue is isolated.

How to Verify the Filtered Run

• Check the console header: it lists 1 test instead of the full count.
• Look for the ✓ or ✗ marker next to the test name.
• In CI, run npx vitest --run without --watch to confirm the same isolated output.

Skipping Known‑Slow Tests During Development

Sometimes a test is reliable but takes 30 s to run because it hits a real database. You can temporarily skip it while you work on unrelated features:

test.skip('heavy db query', async () => {
  const data = await db.query('SELECT * FROM large_table')
  expect(data.length).toBe(1000)
})

Running npx vitest will now skip that test, speeding up the cycle. Remember to remove skip before committing.

Trade‑Off: Masking Systemic Failures

Relying on test.only or test.skip can hide problems that only surface when the full suite runs. A common pitfall is committing a file that still contains test.only, causing the CI pipeline to pass while the rest of the tests are ignored.

Mitigation strategy:

• Use a pre‑commit hook that greps for test.only or test.skip and fails if found.
• Make your CI run the full suite (no flags) on every push.
• Keep a separate --watch workflow for rapid iteration.

Practical Checklist Before a Release

1. Run npx vitest --watch locally to iterate on flaky or slow tests.
2. Remove any test.only or test.skip markers.
3. Execute npx vitest --run to confirm the entire suite passes.
4. Add a CI step that runs vitest --run and fails the build on any failure.

Following this workflow keeps the fast feedback loop for developers while guaranteeing that regressions never slip through to production.

Conclusion

Vitest’s test.only and test.skip are lightweight, powerful tools for isolating problematic tests. Use them to accelerate local debugging, but guard against accidental commits and hidden failures with pre‑commit checks and mandatory full‑suite runs in CI.