run-smoke-tests— agent skill

Run smoke tests to verify the extension loads and basic functionality works in a real VS Code environment.

When to Use This Skill

• After making changes to extension activation code
• After modifying commands or API exports
• Before submitting a PR to verify nothing is broken
• When the user asks to "run smoke tests" or "verify the extension works"

Quick Reference

How Smoke Tests Work

Unlike unit tests (which mock VS Code), smoke tests run inside a real VS Code instance:

1. npm run smoke-test uses @vscode/test-cli
2. The CLI downloads a standalone VS Code binary (cached in .vscode-test/)
3. It launches that VS Code with your extension installed
4. Mocha runs test files inside that VS Code process
5. Results are reported back to your terminal

This is why smoke tests are slower (~10-60s) but catch real integration issues.

Workflow

Step 1: Compile and Run

npm run compile && npm run compile-tests && npm run smoke-test

Step 2: Interpret Results

Pass: 4 passing (2s) → Extension works, proceed.

Fail: See error message and check Debugging section.

Running Individual Tests

To run a specific test instead of the whole suite:

# By test name (grep pattern)
npm run smoke-test -- --grep "Extension activates"

# Or temporarily add .only in code:
test.only('Extension activates without errors', ...)

Debugging Failures

For detailed debugging, use VS Code: Debug panel → "Smoke Tests" → F5

Adding New Smoke Tests

Create a new file in src/test/smoke/ with the naming convention *.smoke.test.ts:

import * as assert from 'assert';
import * as vscode from 'vscode';
import { waitForCondition } from '../testUtils';
import { ENVS_EXTENSION_ID } from '../constants';

suite('Smoke: [Feature Name]', function () {
    this.timeout(60_000);

    test('[Test description]', async function () {
        // Arrange
        const extension = vscode.extensions.getExtension(ENVS_EXTENSION_ID);
        assert.ok(extension, 'Extension not found');

        // Ensure extension is active
        if (!extension.isActive) {
            await extension.activate();
        }

        // Act
        const result = await someOperation();

        // Assert
        assert.strictEqual(result, expected, 'Description of what went wrong');
    });
});

Key patterns:

• Use waitForCondition() instead of sleep() for async assertions
• Set generous timeouts (this.timeout(60_000))
• Include clear error messages in assertions

Test Files

Prerequisites

• CI needs webpack build: The extension must be built with npm run compile (webpack) before tests run. The test runner uses dist/extension.js which is only created by webpack, not by npm run compile-tests (tsc)
• Extension builds: Run npm run compile before tests

Notes

• First run downloads VS Code (~100MB, cached in .vscode-test/)
• Tests auto-retry once on failure