run-smoke-tests

name	run-smoke-tests
description	Run smoke tests to verify extension functionality in a real VS Code environment. Use this when checking if basic features work after changes.

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

Action	Command
Run all smoke tests	npm run compile && npm run compile-tests && npm run smoke-test
Run specific test	npm run smoke-test -- --grep "Extension activates"
Debug in VS Code	Debug panel → "Smoke Tests" → F5

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

Error	Cause	Fix
Extension not installed	Build failed or ID mismatch	Run npm run compile, check extension ID
Extension did not become active	Error in activate()	Debug with F5, check Debug Console
Command not registered	Missing from package.json	Add to contributes.commands
Timeout exceeded	Slow startup or infinite loop	Increase timeout or check for blocking code

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

File	Purpose
src/test/smoke/activation.smoke.test.ts	Extension activation tests
src/test/smoke/index.ts	Test runner entry point
src/test/testUtils.ts	Utilities (waitForCondition, etc.)

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