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

> Run tests for UditAkhourii/adhd with npm test or node --test. This guide makes testing your Node.js project simple and efficient.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: how-to-guide
- Published: 2026-07-30

---

**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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/package.json):

```bash
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:

```bash

# 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`](https://github.com/UditAkhourii/adhd/blob/main/tests/llm.test.ts) contains focused unit tests for the `buildQueryOptions` function located in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/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:

```typescript
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`](https://github.com/UditAkhourii/adhd/blob/main/.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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/.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.