How to Run Tests for UditAkhourii/adhd: Complete Node.js Test Guide

Execute npm test in the repository root to run the full test suite, or use node --test directly on individual TypeScript files like tests/llm.test.ts to validate specific components.

The UditAkhourii/adhd repository ships with a lightweight test suite written in TypeScript that leverages Node.js's built-in test runner. These tests validate critical LLM integration logic—particularly the buildQueryOptions function that constructs API payloads for Claude models—ensuring that generation-only queries properly disable built-in tools.

Prerequisites

Before executing any tests, ensure your environment meets the following requirements:

• Node.js ≥ 18 (required by the project's runtime and test engine, as indicated in the README badge)
• Installed dependencies (run npm install once after cloning to pull TypeScript and runtime dependencies)

The repository handles TypeScript compilation automatically through the test runner, so no separate build step is required.

Running the Full Test Suite

The standard method for validating the entire codebase uses the npm script defined in package.json:

npm test

This command executes node --test under the hood, automatically discovering all *.test.ts files within the tests/ directory. According to the project's configuration, this runs the complete validation suite including the LLM query builder tests.

When successful, you'll see output confirming the test count:

✓ generation-only queries disable all built-in tools (tests/llm.test.ts:6:1)
  1 passing

Running Individual Test Files

For targeted debugging or faster iteration while working on specific features, run individual test files directly using Node's test runner:

# Run a specific test file

node --test tests/llm.test.ts

# Run all test files matching a pattern

node --test tests/**/*.test.ts

This approach bypasses npm and executes TypeScript files directly, which is useful when you need immediate feedback on a single component without waiting for the full suite.

Understanding the Test Structure

The primary test file tests/llm.test.ts contains focused unit tests for the buildQueryOptions function located in src/llm.ts. This function constructs request payloads for Claude models, and the test specifically verifies that generation-only prompts disable all tool usage to prevent accidental tool invocation.

The test validates three specific conditions:

import assert from "node:assert/strict";
import test from "node:test";
import { buildQueryOptions } from "../src/llm.ts";

test("generation-only queries disable all built-in tools", () => {
  const options = buildQueryOptions({
    model: "claude-sonnet-4-5",
    systemPrompt: "Think divergently.",
    userPrompt: "Generate ideas.",
  });

  assert.deepEqual(options.tools, []);               // no tools enabled
  assert.equal("allowedTools" in options, false);   // no whitelist present
  assert.equal("permissionMode" in options, false); // no permission overrides
});

This contract ensures that when the system processes pure generation requests (no tool calling), the resulting payload explicitly excludes tool configurations.

Continuous Integration Setup

The repository's GitHub Action workflow (.github/workflows/ci.yml) automatically executes npm test on every push and pull request. This means the same command you run locally is the exact validation step used in CI to verify correctness.

If you're contributing changes, running npm test locally before pushing prevents CI failures and ensures your modifications maintain the core LLM-query contract.

Summary

• Install dependencies first with npm install after cloning UditAkhourii/adhd
• Run the full suite using npm test to execute all *.test.ts files in the tests/ directory
• Debug specific files using node --test tests/llm.test.ts for faster iteration
• Node.js ≥ 18 is required for the TypeScript test runner to function correctly
• The buildQueryOptions function in src/llm.ts is validated to ensure generation-only queries disable tool usage

Frequently Asked Questions

Do I need to compile TypeScript before running tests?

No. The Node.js test runner handles TypeScript compilation on-the-fly. Simply run npm test or node --test directly against .ts files without generating separate JavaScript output.

What Node.js version is required for the test suite?

Node.js version 18 or higher is required, as specified in the repository README. The built-in node:test runner and TypeScript support depend on features available in these newer Node versions.

How do I run only the LLM-related tests?

Execute node --test tests/llm.test.ts from the repository root. This targets specifically the test file that validates the buildQueryOptions function and LLM query construction logic.

Where is the test command configured for CI?

The test execution is defined in .github/workflows/ci.yml, which invokes npm test automatically on every push. This configuration ensures consistency between your local development environment and the GitHub Actions validation pipeline.

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