Documentation: English | 한국어

Visual Studio Marketplace · Demo video · Report an issue

Browse, run, and debug Pintos tests from a dedicated VS Code sidebar

Pintos Test Explorer is a VS Code extension for browsing and running tests in a Pintos project. It displays tests by project and group in the sidebar and provides commands to run or debug individual tests and open their source files.

Tests are executed through Pintos's existing Make targets. The extension and the pt CLI share the same execution helper and determine test status from the .output, .result, and .errors files generated by Pintos.

Pintos Test Explorer showing grouped tests and row actions in the VS Code sidebar

Features

Feature	Description
Test list	Displays Threads, User Programs, Virtual Memory, and File System tests by project and group.
Run and debug	Provides commands to run or debug an individual test and open its source file.
Batch runs	Runs checked tests and folders in sequence. A running batch can be stopped after the current test finishes.
Test results	Distinguishes PASS, FAIL, and BUILD ERROR and displays the related result files below each test.
Custom tests	Creates, renames, and deletes custom tests and folders while keeping `Make.tests` registration and generated result files in sync.
CLI	Provides the same test discovery and execution features through `pt` and `pintos-tests`.

For Virtual Memory projects, enable User Programs for VM to run and debug User Programs tests from vm/build. The tests remain listed under User Programs while only the build directory changes.

Installation

Install Pintos Test Explorer from the Visual Studio Marketplace, or run:

code --install-extension YoojinKoh.pintos-test-explorer

After installation, open a Pintos project and reload the VS Code window.

Requirements

VS Code 1.85 or later
A Pintos project with a working build toolchain
Python 3
gdb and Microsoft C/C++ (ms-vscode.cpptools) when using the debugging features

Microsoft C/C++ is only required for GDB debugging. It is not required to browse or run tests, reset test results, or open result files.

Usage

Open a Pintos project or a repository that contains Pintos in a subdirectory.
Select the Pintos icon in the Activity Bar.
Expand a project and test group.
Use the actions on a test row to open its source file, run it, or debug it.
Expand a completed test to open its output, result, or errors file.

To run multiple tests, check individual tests or folders and select Run Checked Tests.

Test execution flow

When the extension runs a test, it invokes the <test>.result Make target in the selected project's build directory. Output from Pintos and QEMU is written to .output, the final verdict from the Pintos checker is written to .result, and build or setup errors are written to .errors.

flowchart LR
    A["VS Code sidebar"] --> C["Execution helper"]
    B["pt / pintos-tests"] --> C
    C --> D["Discover tests"]
    C --> E["make test.result"]
    E --> F["Pintos / QEMU"]
    F --> G["output / result / errors"]
    G --> A
    C --> H["GDB server"]
    H --> I["VS Code debugger"]

The sidebar and CLI use the same project root, build directory, and Make target. The same rules are also used to discover tests and locate their result files.

Test results

File	Contents
`*.output`	Runtime output from the Pintos kernel
`*.result`	Final PASS/FAIL verdict written by the Pintos checker
`*.errors`	Errors raised while building or preparing a test run

A pass() message from a test program is part of the kernel output, not the final verdict. The host-side Pintos checker determines whether the test passed, and the extension reads .result to display PASS or FAIL. If the build stops before the checker can produce a verdict, the extension displays BUILD ERROR.

CLI

After the extension activates, pt and pintos-tests are available in newly opened VS Code integrated terminals.

pt list threads
pt run threads alarm-zero
pt debug threads alarm-zero
pt artifacts threads alarm-zero

To use these commands outside VS Code, run Pintos: Install CLI Wrappers to Shell. Command options and test selection syntax are documented in the CLI reference.

Supported repository layouts

Pintos Test Explorer recognizes a direct Pintos root, a repository containing pintos/, a src/ root, and nested lab repositories such as pintos_22.04_lab_docker.

The CLI searches for the Pintos root from the current directory. When running it outside the Pintos tree, set the path with PINTOS_ROOT=/path/to/pintos.

GDB debugging requires a POSIX-based Pintos environment in which gdb can run. The extension UI and CLI messages are provided in English, while the documentation is maintained in English and Korean.

Development and packaging

Use the following commands to build a distributable VSIX and verify the CLI entry point:

python3 scripts/build-pintos-test-explorer-vsix.py
python3 extension/bundled/pintos-test-cli.py --help

The VSIX is written to dist/pintos-test-explorer-<version>.vsix. Extension source files and Marketplace assets are located in extension/.

Support and contributing

Report bugs and request features through GitHub Issues. When opening an issue, include the VS Code version, whether a Dev Container is in use, the Pintos project and test name, and relevant output from Pintos Tests.

Pull requests should describe the user-visible change, steps to reproduce it, and the local verification performed. Known setup problems and their solutions are documented in Troubleshooting.