How to Test Understand-Anything Components in the Lum1104 Repository

Run pnpm test from the root to execute Vitest across all browser-safe packages, or use pnpm --filter @understand-anything/core test to isolate the native-dependent engine.

Understand-Anything is a mono-repo that ships three logical parts: a static-analysis core engine, browser-safe dashboard utils, and TypeScript skill source code for the /understand-* commands. The project relies on Vitest as its unified test runner, with a root vitest.config.ts that aggregates dashboard and skill tests while deliberately excluding the core package. Learning how to test Understand-Anything components ensures you can validate graph-building logic, LLM analyzers, and layout utilities without pulling unnecessary native modules.

Why the Repository Splits Its Test Suites

The division is deliberate. The core package imports native tree-sitter bindings that are not bundled for the browser, so merging its suite into the root config would force heavy native modules to load even when you only need to validate dashboard utilities. Conversely, the dashboard utils are strictly browser-safe and import only from core sub-path exports such as ./search, ./types, and ./schema; their tests run in a pure Node environment to guarantee they never invoke Node-only APIs. This architecture keeps the dashboard bundle lightweight and lets contributors iterate quickly on UI logic without compiling native dependencies.

Running the Full Aggregated Suite

The root vitest.config.ts discovers three globs: tests/**/*.test.* for skill-level integration tests, understand-anything-plugin/src/**/*.test.* for skill TypeScript unit tests, and understand-anything-plugin/packages/dashboard/**/*.test.* for dashboard utility tests. Notable files picked up here include understand-anything-plugin/src/__tests__/onboard-builder.test.ts, which validates the onboarding guide generator, and understand-anything-plugin/src/__tests__/diff-analyzer.test.ts, which verifies diff impact analysis.

Before executing any suite, install workspace dependencies with Node 22 or later and pnpm 10 or later:

pnpm install

After installation, run the aggregated suite:

pnpm test

This command invokes the root Vitest runner and validates every component except the core engine.

Testing the Core Engine Separately

The core engine contains graph-builder, analyzer, persistence, and extractor logic that is validated through its own vitest.config.ts. Because this layer relies on tree-sitter, you isolate it with pnpm’s filter flag:

pnpm --filter @understand-anything/core test

This command loads understand-anything-plugin/packages/core/src/graph-builder.test.ts to validate the graph-building pipeline and understand-anything-plugin/packages/core/src/analyzer/llm-analyzer.test.ts to verify LLM-driven analysis steps. Keeping this suite separate prevents platform-specific binding errors from breaking dashboard or skill test runs.

Testing Dashboard Utilities in Isolation

When you need rapid feedback on layout or filtering logic alone, bypass the root aggregator and target the dashboard package directly:

pnpm --filter @understand-anything/dashboard test

Key files exercised by this command include understand-anything-plugin/packages/dashboard/src/utils/__tests__/layerStats.test.ts, which checks layer-grouping logic, and understand-anything-plugin/packages/dashboard/src/utils/__tests__/elk-layout.test.ts, which ensures the ELK layout algorithm produces sane coordinates.

Watch Mode and Coverage Reports

For test-driven development, start Vitest in watch mode so it re-runs affected tests on every file change:

pnpm test --watch

To generate an HTML coverage report under coverage/, append the coverage flag:

pnpm test --coverage

These flags work with both the root aggregator and filtered package commands.

How Tests Run in CI

The repository’s .github/workflows/ci.yml executes the three commands in sequence: dependency installation, the root aggregated suite, and the filtered core suite. It caches node_modules between runs and publishes a coverage artifact, so reviewers can inspect test quality without cloning the Lum1104/Understand-Anything repository locally. Any failure in either suite fails the entire job, keeping the main branch green.

Troubleshooting Common Test Failures

Cannot Find Module '@understand-anything/core'

This error appears when pnpm test runs without a prior pnpm install. Re-install dependencies to restore workspace symlinks and rebuild native bindings.

tree-sitter Binding Failed on macOS arm64

The core package uses native tree-sitter bindings that are not pre-built for Apple Silicon. As implemented in the source code, the core already falls back to web-tree-sitter, or you can run tests inside the CI container on Linux x86-64 where pre-built binaries are available.

Test Hangs on generate-large-graph.mjs

This script creates a 3,000-node graph and is memory-intensive. Instead of running the full suite, isolate lightweight unit tests by passing a title filter:

pnpm test -- -t "extract-structure"

Summary

• Run pnpm test to execute the aggregated Vitest suite covering skill and dashboard tests.
• Isolate the core engine with pnpm --filter @understand-anything/core test because it depends on native tree-sitter bindings.
• Target dashboard utilities alone with pnpm --filter @understand-anything/dashboard test.
• Enable watch mode with --watch and generate HTML coverage reports with --coverage.
• The CI pipeline in .github/workflows/ci.yml runs both suites, caches dependencies, and publishes coverage artifacts for reviewers.

Frequently Asked Questions

Do I need to install dependencies differently for core tests?

No. A single pnpm install at the root installs every workspace dependency, including those required by @understand-anything/core. The separation is handled at test execution time by Vitest’s include and exclude globs in vitest.config.ts, not by different node_modules trees.

Can I run Understand-Anything tests with npm or yarn instead of pnpm?

The repository is explicitly configured for pnpm 10 or later and Node 22 or later. Using npm or yarn may break workspace resolution and native binding paths, so pnpm is required as documented in the source workflow and root lockfile.

Why are dashboard tests kept out of the core package?

Dashboard utils are designed to be browser-safe and import only lightweight sub-path exports such as ./search, ./types, and ./schema from the core. If they were bundled with the core suite, the native tree-sitter module would leak into browser-targeted builds and bloat the bundle.

What should I do if only one specific test file is failing?

Use Vitest’s filename or title filtering. For example, run pnpm test -- -t "extract-structure" to skip heavy integration scripts like generate-large-graph.mjs, or pass the specific file path to the Vitest CLI to narrow execution to a single module.

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