How to Run Tests in Automattic/harper: Complete Guide for Rust Core and Extensions

The Harper repository uses a unified justfile to orchestrate Rust unit tests, WebAssembly builds, and Playwright-based integration tests for the VS Code extension, Obsidian plugin, and browser extensions.

Automattic/harper is a grammar checker built with a Rust core engine and TypeScript/JavaScript frontends. The test suite spans the Rust-based language server (harper-ls), the WebAssembly-powered JavaScript library, and multiple editor extensions. All testing is coordinated through the justfile at the repository root, providing consistent commands for local development and CI pipelines.

Run the Complete Test Suite

To execute every test target in the correct order, use the top-level test recipe. This runs Rust unit tests, builds WebAssembly artifacts, and triggers Playwright suites for all supported platforms:

just test

According to the justfile (lines 99-100), this recipe bundles all individual test tasks together to ensure the entire workspace validates correctly.

Test the Rust Core and Language Server

Harper’s core engine, command-line interface, and language server protocol (LSP) implementation live in the Rust workspace. Run these unit and integration tests using Cargo:

just test-rust

Internally, the test-rust recipe executes cargo test -q across the entire workspace (lines 94-96), covering crates like harper-core and harper-ls. For example, core linting logic is validated in harper-core/tests/linters.rs using standard Rust test assertions.

Test the WebAssembly JavaScript Wrapper (Harper.js)

Harper.js provides the WebAssembly-based JavaScript API. Its test suite validates the WASM bundle and browser compatibility:

just test-harperjs

This recipe first calls build-harperjs to compile the Rust source to WASM, installs Node dependencies with pnpm, runs Playwright tests, and launches the example runner to verify the demo application functions correctly (lines 104-116).

Test Editor Extensions

The VS Code and Obsidian extensions require the compiled language server binary or WASM artifacts to test correctly.

VS Code Extension

The VS Code extension tests depend on the harper-ls binary being present in the extension's bin/ directory. The test flow defined in the test-vscode target (lines 30-57) rebuilds the binary in release mode, copies it to the correct location, installs Node dependencies, and executes the extension test suite:

just test-vscode

On Linux CI environments, this runs under headless Xvfb to simulate a display server. The justfile handles all prerequisite steps automatically.

Obsidian Plugin

For the Obsidian plugin, tests validate the integration between the TypeScript plugin code and the WebAssembly core:

just test-obsidian

This target builds the required WASM bundle, installs the plugin's dependencies, and runs Playwright tests against the Obsidian plugin environment (lines 18-26).

Test Browser Extensions

Harper provides extensions for Chrome and Firefox that rely on the compiled WebAssembly module and extension assets.

Chrome Extension

Run the Chrome extension tests with:

just test-chrome-plugin

The recipe first builds the Chrome plugin assets and WASM bundle, installs dependencies, then invokes Playwright (lines 91-107). On Linux systems, it automatically wraps the execution with Xvfb for headless CI compatibility.

Firefox Extension

Firefox extension testing follows an identical pattern:

just test-firefox-plugin

This builds the Firefox-specific plugin, installs dependencies, and runs Playwright with the same Xvfb handling used for Chrome testing on Linux CI runners (lines 110-124).

Summary

• just test runs the entire test suite across Rust, JavaScript, and all extension platforms in the correct dependency order.
• Rust tests use cargo test -q and cover the core engine and language server in harper-core/tests/ and related crates.
• Harper.js tests require WASM compilation and run via Playwright to validate the WebAssembly API.
• Extension tests for VS Code, Obsidian, Chrome, and Firefox use Playwright and automatically rebuild their binary or WASM dependencies before execution.
• Most recipes handle prerequisite builds automatically, so you can run individual test targets without manual compilation steps.

Frequently Asked Questions

What testing framework does Harper use for Rust code?

Harper uses the standard Rust testing framework via cargo test. The workspace contains unit and integration tests in crates like harper-core, with test files located in harper-core/tests/linters.rs and similar directories. The just test-rust command runs cargo test -q across the entire workspace according to the justfile implementation.

Do I need to build WebAssembly or the language server before running tests?

No. The justfile recipes automatically handle dependency builds. For example, just test-harperjs invokes build-harperjs first, and just test-vscode rebuilds harper-ls in release mode before copying it to the extension directory. You can invoke test targets directly without manual build steps.

How do I run only the VS Code extension tests?

Use just test-vscode to run only the VS Code extension test suite. This command compiles the harper-ls binary in release mode, copies it to packages/vscode-plugin/bin/, installs Node dependencies, and runs the extension tests. It handles Linux headless environments automatically using Xvfb when necessary.

Why do some tests require Xvfb on Linux?

Browser and VS Code extension tests use Playwright to automate UI interactions that require a display server. On Linux CI environments where no display is available, the justfile wraps these tests with Xvfb (X Virtual Framebuffer) to provide a virtual display. This is handled automatically in the test-vscode, test-chrome-plugin, and test-firefox-plugin recipes when running on Linux.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}