Environment Variable Support for Watch Mode Control

[technicalpickles]

Clear and concise description of the problem

As a developer using coding agents (like Cursor, GitHub Copilot, VSCode extensions) with Vitest, I want to be able to run tests programmatically without the process hanging in watch mode, so that my agent workflows can complete successfully and provide immediate feedback.

Current Problem:
When coding agents run vitest in interactive terminal environments, the process defaults to watch mode (!isCI && process.stdin.isTTY = true), runs tests, then waits for file changes. This causes the agent to hang indefinitely, preventing it from receiving test results and continuing its workflow.

Current workarounds are suboptimal:

• Use vitest run instead of vitest (requires agents to know about this command)
• Set CI=true environment variable (misleading, not semantically correct)
• Configure watch: false in vitest config (global override, not per-invocation)

This builds on the discussion in #7818 where @rhysburnie identified the same problem with AI agents getting stuck in watch mode. While PR #7673 restored the TTY check, it doesn't solve the core issue since coding agents still run in interactive terminals.

Suggested solution

Add environment variable support for explicit watch mode control:

New Environment Variables:

• VITEST_WATCH=true - Force watch mode regardless of environment
• VITEST_WATCH=false - Force run mode (no watch)
• VITEST_RUN=true - Force run mode (alias for VITEST_WATCH=false)

Implementation:

// In packages/vitest/src/defaults.ts
function getWatchMode(): boolean {
  // Explicit overrides take precedence
  if (process.env.VITEST_WATCH === 'false' || process.env.VITEST_RUN === 'true') {
    return false
  }
  if (process.env.VITEST_WATCH === 'true') {
    return true
  }

  // Default detection (current behavior)
  return !isCI && process.stdin.isTTY
}

export const configDefaults = Object.freeze({
  // ... other defaults
  watch: getWatchMode(),
  // ... other defaults
})

Usage Examples:

# Force run mode for coding agents
VITEST_RUN=true vitest

# Force run mode (alternative)
VITEST_WATCH=false vitest

# Force watch mode (if needed)
VITEST_WATCH=true vitest

# Default behavior (unchanged)
vitest

Benefits:

1. Backward Compatible - Existing developer workflows unchanged
2. Explicit Control - Environmetn variables have clear intent for different scenarios, ie CI vs agents
3. Agent-Friendly - Simple environment variable for agents to use
4. Semantically Correct - VITEST_RUN=true is clearer than CI=true

Alternative

Alternative 1: Change default to vitest run

• Pros: Solves the agent problem immediately
• Cons: Breaking change that would affect all interactive development workflows

Alternative 2: Agent detection

• Pros: Automatic detection of common agent environments
• Cons: More complex, requires agents to set specific variables, may miss some agents

Alternative 3: Use existing CLI arguments

• Pros: Explicit control via CLI flags (--run vs --run)
• Cons: would need to do one of
  • projects update their package.json to have test vs test:watch
  • agents need to be trained (ie AGENTS.md or rules or whatever) to call vitest --run directly instead of using npm test

Alternative 4: Leave as is

• Pros: No changes needed
• Cons: Coding agents continue to have issues, problem identified in vitest seems to be an issue now that we have code agents #7818 remains unsolved

Additional context

Additional context

Migration Guide:

For Users: No changes required - existing behavior is preserved.

For Coding Agents:

# Instead of: vitest
# Use: VITEST_RUN=true vitest

# Or in package.json scripts:
{
  "scripts": {
    "test": "VITEST_RUN=true vitest",
    "test:watch": "vitest"
  }
}

For CI/CD: No changes required - CI detection still works as before.

Testing Strategy:

test('VITEST_WATCH=false forces run mode', async () => {
  // Test that tests run and process exits
})

test('VITEST_RUN=true forces run mode', async () => {
  // Test that tests run and process exits
})

test('VITEST_WATCH=true forces watch mode', async () => {
  // Test that process enters watch mode
})

test('default behavior unchanged', async () => {
  // Test without any new env vars
})

Documentation Updates Needed:

• docs/config/index.md - Document new environment variables
• docs/guide/cli.md - Add examples for agent scenarios
• docs/guide/features.md - Mention agent compatibility

This solution addresses the coding agent problem identified in #7818 while maintaining backward compatibility and providing a clear, explicit way to control watch mode behavior. It's a simple, safe addition that improves Vitest's usability in automated environments without affecting the excellent interactive development experience.

I intend to submit a PR for this issue if the approach is approved.

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[sheremet-va]

I don't understand how adding a new variable that agents need to learn is better than using --no-watch that already exists (or --run), the thing mentioned in Alternative 3.

The benefits section doesn't seem to make any sense.

The only viable solution in this case is detecting the agent and changing the default in that case. We can already detect CI with std-env, is there no package for agents?

[hi-ogawa]

Bun detects some environment variables oven-sh/bun#21135

When an AI agent is detected through environment variables like CLAUDECODE=1, REPL_ID=1, or IS_CODE_AGENT=1

[rhysburnie]

Personally I think the fix should have been as follows:

vitest runs and doesn't watch... Vitest is the only test lib that I can recall that defaults to watch.

This means no need to check env vars and no need to tell the agents not to watch.

Impacts to human users
They will run vitest expecting it to watch... they may say "oh thats annoying", read the updated docs and see you just need to specify --watch

I get that this maybe would be considered a breaking change, but really whats the impact, just mild annoyance.
Once user finds reason they just adjust the package.json script to include the watch flag:

with something like npm run test:watch

"test:watch": "vitest --watch" or even npm run test -- --watch would work fine.

The point being its much easier for human user to adjust the package.json script for "test" and just let AI run "npm test"

You could argue then that user might do "test": "vitest --watch" an then your back to the same issue again but you're already covering CI envs in the code and if user did do this and encounters the AI issue its more explicit and easy to see why its happening.

Also its more the norm now that test is called by agent vs user right?, and users who do run test in watch while doing tdd are usually quite aware of watch options in test libs especially since all the ones I know except vitest requires you to flag watch.

[technicalpickles]

I don't understand how adding a new variable that agents need to learn is better than using --no-watch that already exists (or --run), the thing mentioned in Alternative 3.

My bad, I updated to reflect those exist. The cons for that are either a project:

• updates it's package.json to use vitest --run for test, and add a separate test:watch task
• documents via AGENTS.md, rules, etc to use vitest --run

The benefits section doesn't seem to make any sense.

Updated for (hopeful) clarity.

We can already detect CI with std-env, is there no package for agents?

Not that I am aware of, but I can research. I have some ideas on how to implement it though.

[sheremet-va]

The team has rejected this idea.