tessl/npm-vitest--ui

Web-based user interface for the Vitest testing framework with real-time test execution visualization and HTML reporting capabilities

—

Pending

Overview

Eval results

Files

Client API

Name: tessl/npm-vitest--ui
Author: tessl

The Client API provides browser-based functionality for interacting with Vitest through WebSocket connections, enabling real-time test execution, file management, and result viewing. These APIs are available in the browser context when the @vitest/ui interface is loaded.

Browser Context Access

The client APIs are available in the browser when the Vitest UI is running. They are not importable from the npm package but are accessible through the UI framework's module system. The UI API is exposed as a global object:

// UI API available as global in browser context
const ui = window.__vitest_ui_api__;

// Client is available through the UI framework's composables
// (actual access varies based on the UI framework implementation)

API

Client Instance

The main WebSocket client for communicating with Vitest.

declare const client: {
  state: {
    idMap: Map<string, Task>;
    filesMap: Map<string, File[]>;
    pathsSet: Set<string>;
    getPaths(): string[];
    getFiles(keys?: string[]): File[];
    getFilepaths(): string[];
    getFailedFilepaths(): string[];
    collectPaths(paths: string[]): void;
    collectFiles(files: File[]): void;
  };
  rpc: {
    rerun(files: string[], allTests: boolean): Promise<void>;
    rerunTask(taskId: string): Promise<void>;
    getFiles(): Promise<File[]>;
    getConfig(): Promise<SerializedConfig>;
    getUnhandledErrors(): Promise<unknown[]>;
    getResolvedProjectLabels(): Promise<string[]>;
    getTestFiles(): Promise<Array<[{ name: string; root: string }, string]>>;
    readTestFile(filepath: string): Promise<string>;
    saveTestFile(filepath: string, content: string): Promise<void>;
    updateSnapshot(file: File): Promise<void>;
  };
  ws: WebSocket;
};

Configuration and State

Reactive state objects for monitoring Vitest configuration and connection status.

declare const config: Ref<SerializedConfig>;
declare const status: Ref<WebSocketStatus>;
declare const current: ComputedRef<File | undefined>;
declare const currentLogs: ComputedRef<TaskLog[]>;

Connection State Helpers

Computed properties for checking WebSocket connection status.

declare const isConnected: ComputedRef<boolean>;
declare const isConnecting: ComputedRef<boolean>;
declare const isDisconnected: ComputedRef<boolean>;

Test Execution Functions

Functions for running tests and managing test execution.

declare function findById(id: string): File | undefined;
declare function runAll(): Promise<void>;
declare function runFiles(useFiles: File[]): Promise<void>;
declare function runTask(task: Task): Promise<void>;
declare function runCurrent(): Promise<void>;

Browser UI Interface

Interface exposed to browser contexts for programmatic control.

interface BrowserUI {
  setCurrentFileId(fileId: string): void;
  setIframeViewport(width: number, height: number): Promise<void>;
}

declare const ui: BrowserUI;

Usage Examples

Running Tests

// Available in browser context when UI is loaded
// Note: client access depends on the UI framework implementation
// These examples show the expected API structure

// Run all tests
await runAll();

// Run specific files
const files = client.state.getFiles().filter(f => f.name.includes('auth'));
await runFiles(files);

// Run a specific task
const task = findById('test-task-id');
if (task) {
  await runTask(task);
}

Monitoring Connection Status

// Available in browser context through UI framework composables
// Note: actual access may vary based on implementation

// Watch connection status
watch(status, (newStatus) => {
  console.log('WebSocket status:', newStatus);
});

// Check connection state
if (isConnected.value) {
  console.log('Connected to Vitest');
} else if (isConnecting.value) {
  console.log('Connecting to Vitest...');
}

Working with Test Files

// Available in browser context through UI framework composables
// Note: actual access may vary based on implementation

// Get all test files
const allFiles = client.state.getFiles();

// Get current active file
const activeFile = current.value;

// Find file by ID
const specificFile = findById('file-123');

// Read test file content
const fileContent = await client.rpc.readTestFile('/path/to/test.spec.ts');

// Save modified test file
await client.rpc.saveTestFile('/path/to/test.spec.ts', updatedContent);

// Update snapshots for a file
await client.rpc.updateSnapshot(testFile);

Browser Integration

// The UI API is automatically exposed to the browser context
window.__vitest_ui_api__.setCurrentFileId('test-file-id');
window.__vitest_ui_api__.setIframeViewport(1920, 1080);

WebSocket Events

The client handles several WebSocket events:

onTestAnnotate: Handles test annotations and metadata
onTaskUpdate: Processes test result updates in real-time
onFinished: Handles test run completion
onFinishedReportCoverage: Triggers coverage report reload

Constants

declare const PORT: string;
declare const HOST: string;
declare const ENTRY_URL: string;
declare const isReport: boolean;
declare const BASE_PATH: string;

Explorer Tree Integration

The client integrates with the Explorer Tree for test result visualization:

declare const explorerTree: {
  loadFiles(files: File[], projects: string[]): void;
  startRun(): void;
  endRun(): void;
  resumeRun(packs: TaskResultPack[], events: RunnerTaskEventPack[]): void;
  annotateTest(testId: string, annotation: TestAnnotation): void;
};

Types

type WebSocketStatus = 'CONNECTING' | 'OPEN' | 'CLOSED';

interface File {
  id: string;
  name: string;
  filepath: string;
  projectName?: string;
  result?: TaskResult;
  mode: 'run' | 'skip' | 'only' | 'todo';
}

interface Task {
  id: string;
  name: string;
  type: 'test' | 'suite';
  mode: 'run' | 'skip' | 'only' | 'todo';
  result?: TaskResult;
  tasks?: Task[];
}

interface TaskLog {
  type: 'stdout' | 'stderr';
  content: string;
  time: number;
}

interface TaskResult {
  state?: 'pass' | 'fail' | 'skip' | 'todo';
  duration?: number;
  error?: unknown;
}

interface TaskResultPack {
  id: string;
  result: TaskResult;
}

interface RunnerTaskEventPack {
  type: string;
  taskId: string;
  data: unknown;
}

interface TestAnnotation {
  type: string;
  message?: string;
  attachment?: TestAttachment;
}

interface TestAttachment {
  path?: string;
  body?: string | Buffer;
  contentType?: string;
}

// External types from dependencies:
// - Ref, ComputedRef: from Vue.js or compatible reactivity system
// - SerializedConfig: from 'vitest'

Install with Tessl CLI

npx tessl i tessl/npm-vitest--ui

docs