Mocha Test Debug Helper

A VS Code extension to help debug Mocha-style tests by automatically commenting/uncommenting code blocks based on special markers.

Version 0.3.0+ uses AST-based parsing (ts-morph) for more accurate scope detection and improved handling of complex code structures.

Features

Keyboard Shortcut (Ctrl+Shift+D)

Quickly toggle debug markers with a keyboard shortcut:

1. First press: Insert // @debug at the current cursor line
2. Second press (on // @debug line): Replace with // @undebug
3. Third press (on // @undebug line): Delete the line

The shortcut automatically preserves indentation and only works in TypeScript/JavaScript files.

Debug Mode (// @debug)

When you add a // @debug comment in your test file, the extension will automatically comment out:

1. Statements before the debug line in the current step
2. All statements in previous steps (at the same test level)
3. All statements at test level (code between steps, e.g., console.log('before step'))
4. All statements in before() and beforeEach() blocks

This allows you to focus on debugging a specific part of your test without executing earlier code.

Example:

Before (with // @debug):

test("my test", {}, async () => {
    await step('first step', async () => {
        const content = [];
        await sleep(3000);
    });

    await step('second step', async () => {
        await sleep(3000);
        await $('selector').tap();
        // @debug
        await $('other-selector').setValue('value');
    });
});

After save:

test("my test", {}, async () => {
    await step('first step', async () => {
        // const content = [];
        // await sleep(3000);
    });

    await step('second step', async () => {
        // await sleep(3000);
        // await $('selector').tap();
        // @debug
        await $('other-selector').setValue('value');
    });
});

Example with test-level code:

Before (with code between steps):

test("my test", {}, async () => {
    console.log('before first step');
    await step('first step', async () => {
        await doSomething();
    });

    console.log('before second step');
    await step('second step', async () => {
        // @debug
        await targetAction();
    });
});

After save:

test("my test", {}, async () => {
    // console.log('before first step');
    await step('first step', async () => {
        // await doSomething();
    });

    // console.log('before second step');
    await step('second step', async () => {
        // @debug
        await targetAction();
    });
});

Undebug Mode (// @undebug)

When you add a // @undebug comment, the extension will uncomment code that was previously commented by the debug mode.

Important: The extension uses pattern matching to identify code vs. intentional comments. It only uncomments lines that match common code patterns (keywords like const, await, function calls, assignments, etc.). Natural language comments are preserved.

Example:

With // @undebug:

test("my test", {}, async () => {
    await step('first step', async () => {
        // const content = [];
        // await sleep(3000);
    });

    await step('second step', async () => {
        // await sleep(3000);
        // await $('selector').tap();
        // @undebug
        await $('other-selector').setValue('value');
    });
});

After save:

test("my test", {}, async () => {
    await step('first step', async () => {
        const content = [];
        await sleep(3000);
    });

    await step('second step', async () => {
        await sleep(3000);
        await $('selector').tap();
        // @undebug
        await $('other-selector').setValue('value');
    });
});

Usage

Quick Method (Keyboard Shortcut)

1. Place your cursor where you want to add a debug marker
2. Press Ctrl+Shift+D to insert // @debug
3. Save the file (Cmd+S / Ctrl+S) - the extension automatically comments out code
4. Press Ctrl+Shift+D again to toggle to // @undebug
5. Save again to uncomment the code
6. Press Ctrl+Shift+D once more to remove the marker

Manual Method

1. Manually type // @debug or // @undebug comment in your test file where you want to apply the commenting/uncommenting
2. Save the file (Cmd+S / Ctrl+S)
3. The extension automatically processes the markers and updates your code

Supported File Types

• TypeScript (.ts)
• JavaScript (.js)

Installation

From Source

1. Clone this repository
2. Run npm install
3. Run npm run compile
4. Press F5 to open a new VS Code window with the extension loaded
5. Open a test file and try it out!

From VSIX

1. Package the extension: vsce package
2. Install the .vsix file in VS Code

Development

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch for changes
npm run watch

# Package extension
vsce package

Requirements

• VS Code 1.85.0 or higher

Technical Details

AST-Based Parsing (v0.3.0+)

The extension uses ts-morph (TypeScript compiler API) to parse code structure, providing:

• Accurate scope detection: Uses AST parsing instead of regex/brace counting for reliable detection of step, describe, test, before, and beforeEach blocks
• Handles complex structures: Correctly identifies scopes even with nested objects, function calls, and other complex code patterns
• Precise boundary detection: Accurately determines scope start and end lines, preventing false positives (e.g., closing braces of nested structures won't be mistaken for scope boundaries)

Known Limitations

• The extension uses pattern matching to distinguish code from intentional comments when uncommenting. It only uncomments lines that match common code patterns (keywords, function calls, assignments, etc.). Natural language comments are preserved.
• Works best with properly formatted and indented code
• Assumes standard Mocha test structure with describe, test, step, before, and beforeEach blocks
• For step functions, they must be wrapped in await (e.g., await step(...)) to be detected

License

MIT