Mocha Test Lens

Run individual Mocha tests directly from your code editor with CodeLens buttons, similar to IntelliJ IDEA's test interface.

Features

CodeLens Integration: Shows "Run Test" and "Debug Test" buttons above each describe and it block
Precise Test Execution: Runs specific tests using Mocha's --grep pattern matching
Mocha Config Integration: Automatically uses your Mocha configuration files (.mocharc.json, .mocharc.js, etc.) for transpiler setup, require modules, and other options
Nix Environment Support: Automatically detects and uses nix-managed Node.js installations
TypeScript Support: Works seamlessly with TypeScript projects via Mocha's require configuration
Test File Detection: Automatically activates for:
- All TypeScript/JavaScript files in test/, spec/, or tests/ directories
- Files with .test.ts, .spec.ts, .test.js, or .spec.js extensions anywhere in the project

Installation

From VSIX File

code --install-extension mocha-test-lens-1.0.0.vsix

Or in VS Code/Cursor:

Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
Run "Extensions: Install from VSIX..."
Select the mocha-test-lens-1.0.0.vsix file

From Source

Clone or copy the extension source code:

git clone <repository-url> mocha-test-lens-extension
cd mocha-test-lens-extension

Install dependencies:

npm install

Compile the TypeScript code:

npm run compile

Package the extension:

npx @vscode/vsce package

Install the generated VSIX file:

code --install-extension mocha-test-lens-*.vsix

Development Mode

To run the extension in development mode:

Open the extension folder in VS Code
Press F5 to launch a new VS Code window with the extension loaded
Make changes to the source code
Run npm run compile or npm run watch for automatic compilation
Reload the Extension Development Host window to test changes

Usage

Open any test file in a test/ or spec/ directory
You'll see CodeLens buttons above each test:
- ▶ Run Test: Runs the specific test in the terminal
- 🐛 Debug Test: Starts a debug session for the test

Configuration

Configure the extension in your VS Code settings:

{
    // Environment variables for test execution
    "mochaTestLens.env": {
        "NODE_ENV": "test",
        "TS_NODE_TRANSPILE_ONLY": "true"
    },

    // Path to node binary (leave empty for auto-detection)
    "mochaTestLens.nodePath": "",

    // Custom workspace root (auto-detected by default)
    "mochaTestLens.workspaceRoot": "",

    // VS Code task to run before debugging (optional, for nix environments)
    "mochaTestLens.debugPreLaunchTask": "nixenv",

    // Environment file to load when debugging (optional, for nix environments)
    "mochaTestLens.debugEnvFile": "${workspaceFolder}/.vscode/nixenv"
}

Note: Transpiler configuration (tsx, ts-node, etc.) is now handled by Mocha configuration files (.mocharc.json, .mocharc.js, etc.). See the Mocha Configuration Files section below.

Configuration Options

Setting	Type	Default	Description
`mochaTestLens.env`	object	`{}`	Environment variables to set when running tests
`mochaTestLens.nodePath`	string	`""`	Path to node binary (auto-detected if empty)
`mochaTestLens.workspaceRoot`	string	`""`	Workspace root directory (auto-detected if empty)
`mochaTestLens.debugPreLaunchTask`	string	`""`	VS Code task name to run before debugging (e.g., `"nixenv"`)
`mochaTestLens.debugEnvFile`	string	`""`	Path to environment file to load when debugging

Node Path Detection

The extension automatically detects the node binary using the following resolution strategy (checked in order):

Custom nodePath - If mochaTestLens.nodePath is configured, use that path directly
NODE_PATH environment variable - Derives node path from NODE_PATH (for nix environments)
- Converts /path/to/lib/node_modules → /path/to/bin/node
Nix bin stubs - Checks for .nix-bin-stubs/node in workspace root (for nix environments)
NVM with .nvmrc - If workspace contains .nvmrc file:
- Reads the version from .nvmrc (e.g., 18.17.0 or v18.17.0)
- Uses ~/.nvm/versions/node/v{version}/bin/node (or $NVM_DIR/versions/node/v{version}/bin/node)
NVM active - Uses $NVM_BIN/node if NVM is currently active
NVM current - Falls back to ~/.nvm/current/bin/node symlink
System PATH - Defaults to node command from system PATH

When nodePath is empty (default), the extension automatically detects the appropriate node binary based on your environment. This ensures compatibility with:

Nix environments - Automatically uses nix-managed node
NVM projects - Respects .nvmrc to use the correct Node.js version
Standard setups - Falls back to system node if no version manager is detected

How It Works

The extension:

Parses your test file to find all describe and it blocks
Builds precise grep patterns for each test
Executes Mocha with the --grep flag to run specific tests
Supports nested describe blocks and maintains test hierarchy
Defers to Mocha configuration files for transpiler setup, require modules, and other Mocha options

Mocha Configuration Files

The extension respects Mocha's configuration files (.mocharc.js, .mocharc.json, .mocharc.yaml, or package.json mocha property). This means:

Transpiler setup: Configure require modules (e.g., tsx, ts-node) in your Mocha config
Setup files: Add setup files via require in your Mocha config (e.g., test/setup.ts)
Other options: All Mocha options can be configured in these files

Example .mocharc.json:

{
    "require": ["tsx", "test/setup.ts"],
    "timeout": 5000,
    "reporter": "spec"
}

Example package.json:

{
    "mocha": {
        "require": ["tsx", "test/setup.ts"]
    }
}

Both when running tests in the terminal and when debugging, the extension runs Mocha directly and lets it load your configuration files automatically. This ensures consistency with how you run tests from the command line.

Example command generated:

node node_modules/.bin/mocha "path/to/test.ts" \
  --grep "^Parent Describe Child Describe specific test$"

Mocha will automatically load your .mocharc.json (or other config file) and apply the require modules, setup files, and other options you've configured there.

Troubleshooting

Extension Conflicts

If you see an error like "command 'mochaTestLens.runTest' already exists":

You may have multiple versions of the extension installed
Uninstall all versions: code --uninstall-extension mocha-test-lens.mocha-test-lens
Reinstall the latest version

CodeLens Not Appearing

Ensure your test file is either:
- Located in a test/, spec/, or tests/ directory (any TypeScript/JavaScript file)
- Has .test.ts, .spec.ts, .test.js, or .spec.js extension (anywhere in project)
Reload VS Code window: Cmd+Shift+P → "Developer: Reload Window"
Check Output panel: View → Output → Select "Mocha Test Lens"

Tests Not Running

Verify mocha is installed in your project
Configure transpiler in Mocha config: For TypeScript projects, ensure your transpiler (tsx or ts-node) is configured in your Mocha config file (.mocharc.json, .mocharc.js, etc.) via the require option
Setup files not loading: Ensure your setup files are configured in your Mocha config file via the require option (e.g., "require": ["tsx", "test/setup.ts"])
Check that your node_modules/.bin/ contains the required binaries (mocha and your transpiler if using TypeScript)
The extension runs mocha directly - all transpiler and setup configuration should be in your Mocha config files

Debug Configuration Issues

Pre-launch task not running: Ensure mochaTestLens.debugPreLaunchTask matches a task name in .vscode/tasks.json
Environment file not loading: Verify mochaTestLens.debugEnvFile path is correct (use ${workspaceFolder} for workspace-relative paths)
Nix environments: Configure debugPreLaunchTask to run your nix setup task and debugEnvFile to point to the generated environment file

Commands

Mocha Test Lens: Test Extension - Verify the extension is working correctly

Requirements

VS Code 1.74.0 or higher
Mocha installed in your project
For TypeScript projects: Configure your transpiler (tsx or ts-node) in your Mocha configuration file (.mocharc.json, .mocharc.js, etc.) via the require option

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Fork the repository
Clone your fork: git clone https://github.com/your-username/mocha-test-lens.git
Install dependencies: npm install
Make your changes
Run tests: npm test
Run linter: npm run lint
Build the extension: npm run compile
Test in VS Code: Press F5 to launch Extension Development Host

CI/CD and Publishing

This project uses GitHub Actions for automated CI/CD:

CI Workflow (.github/workflows/ci.yml): Runs on all pushes and PRs
- Runs tests, linting, and prettier checks
- Ensures code quality before merging
Release Workflow (.github/workflows/release.yml): Runs on pushes to main/master
- Uses semantic-release for automated versioning and changelog generation
- Publishes to VS Code Marketplace
- Publishes to Open VSX Registry
- Creates GitHub releases with VSIX assets

Required GitHub Secrets

To enable automated publishing, configure these secrets in your repository settings (Settings → Secrets and variables → Actions):

VSCE_PAT: VS Code Marketplace Personal Access Token
- Required for publishing to VS Code Marketplace
- Create at: https://dev.azure.com/ (Azure DevOps)
- Follow guide: https://code.visualstudio.com/api/working-with-extensions/publishing-extension#get-a-personal-access-token
OVSX_TOKEN: Open VSX Registry Access Token
- Required for publishing to Open VSX
- Create at: https://open-vsx.org/user-settings/tokens (after signing Publisher Agreement)
- Follow guide: https://github.com/EclipseFdn/open-vsx.org/wiki/Publishing-Extensions

Commit Message Format

This project uses Conventional Commits for automated versioning:

feat: - New feature (triggers minor version bump)
fix: - Bug fix (triggers patch version bump)
docs: - Documentation changes (no version bump)
chore: - Maintenance tasks (no version bump)
BREAKING CHANGE: - Breaking changes (triggers major version bump)

Example:

feat: add support for Jest test runner

This adds CodeLens support for Jest tests in addition to Mocha tests.

Code Style

This project uses Prettier for code formatting
ESLint is used for code quality checks
Run npm run lint:fix to automatically fix linting issues

Submitting Changes

Create a feature branch from main
Make your changes with tests
Ensure all tests pass: npm test
Ensure linting passes: npm run lint
Submit a pull request with a clear description of changes

Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub.

License

MIT

Author

Zahin Mohammad

GitHub: @zahin-mohammad