How to Run Unit Tests for I-Have-ADHD Adapters: A Complete Guide

Run python -m unittest discover -s tests -v from the repository root to execute the complete test suite for I-Have-ADHD adapters.

The ayghri/i-have-adhd repository ships with a lightweight Python unit test suite that validates every runtime adapter including Pi, OMP, Claude, and Codex implementations. These tests ensure that package manifests, skill metadata, and hook systems remain consistent across the codebase without requiring any third-party dependencies.

What the I-Have-ADHD Test Suite Covers

The test suite in the tests/ directory focuses on four core areas that guarantee adapter integrity. Each test file maps directly to a critical component of the runtime system.

Package Manifest Validation

The tests/test_omp_package.py file verifies that package.json correctly declares the extensions used by each adapter. Specifically, it checks that the omp and pi fields contain the expected TypeScript extension paths, ensuring that the OMP (Open Model Platform) and Pi runtimes can locate and load the adapter code.

Skill Metadata Verification

This test validates the canonical skill definition in skills/i-have-adhd/SKILL.md. It asserts the presence of required front-matter flags including name: i-have-adhd and disable-model-invocation: true, which control how the AI platform interprets and invokes the adapter.

Runtime and Hook Integrity

Two test files handle runtime validation:

• tests/test_always_on_hooks.py ensures that the always-on hooks (implemented in hooks/always-on.mjs) load without JavaScript errors
• tests/test_opencode_plugin.py verifies that the OpenCode plugin entry point can be imported and initialized correctly

Evaluation Driver Smoke Tests

The tests/test_run_evals.py file performs a sanity check on scripts/run_evals.py, confirming that the evaluation driver can be invoked with a minimal configuration. This prevents breaking changes to the benchmarking infrastructure.

Prerequisites for Running Adapter Tests

The I-Have-ADHD test suite requires only a recent Python 3 interpreter. The tests use the standard library unittest framework and do not require pytest, pip install, or any virtual environment setup. The only requirement is that your current working directory must be the repository root so Python can import the repository as a module and locate relative paths like package.json and skills/.

Running the Unit Tests for I-Have-ADHD Adapters

Running the Full Test Suite

Navigate to the repository root and execute the discovery command:

python -m unittest discover -s tests -v

The -s tests flag directs the test runner to the tests/ directory, while -v enables verbose output showing individual test case results. Successful execution produces output similar to:

test_omp_package.OmpPackageTest.test_omp_and_pi_extension_manifests_are_declared ... ok
test_omp_package.OmpPackageTest.test_skill_remains_explicitly_invoked ... ok
test_always_on_hooks.AlwaysOnHooksTest.test_hook_loads ... ok
test_run_evals.RunEvalsTest.test_can_execute_driver ... ok
----------------------------------------------------------------------
Ran 4 tests in 0.123s
OK

Running Individual Test Files

For targeted debugging, run a specific test module using Python's dot notation:

python -m unittest tests.test_omp_package

This executes all test cases within tests/test_omp_package.py without running the full suite.

Running Specific Test Cases

To run a single test method for rapid iteration:

python -m unittest tests.test_omp_package.OmpPackageTest.test_skill_remains_explicitly_invoked

This pattern follows tests.<module_name>.<ClassName>.<method_name> and is useful when troubleshooting a specific assertion failure.

Understanding Test Failures

When a test fails, the traceback points to the specific assertion in files like tests/test_omp_package.py. Common failure points include:

• Manifest mismatches: package.json missing the omp.extensions or pi configuration arrays
• Missing front-matter: skills/i-have-adhd/SKILL.md lacking the required YAML headers
• Import errors: JavaScript hooks in hooks/always-on.mjs containing syntax errors that prevent loading

Inspect the failing test source and the corresponding artifact (e.g., package.json or SKILL.md) to identify discrepancies between expected and actual values.

Key Source Files and Test Mappings

The following files work in concert with the test suite:

Source File	Test File	Purpose
package.json	tests/test_omp_package.py	Declares OMP and Pi adapter extensions
skills/i-have-adhd/SKILL.md	tests/test_omp_package.py	Contains skill metadata and invocation flags
hooks/always-on.mjs	tests/test_always_on_hooks.py	Always-on runtime hook entry point
extensions/i-have-adhd.ts	tests/test_opencode_plugin.py	TypeScript adapter implementation
scripts/run_evals.py	tests/test_run_evals.py	Evaluation benchmarking driver

Summary

• Run python -m unittest discover -s tests -v from the repository root to execute the complete I-Have-ADHD adapter test suite
• The suite validates package manifests, skill metadata, hook loading, and evaluation drivers using pure Python standard library
• No dependencies required: The tests run on any Python 3 installation without pip packages
• Targeted execution: Use python -m unittest tests.test_<module> to run individual files or specific test methods
• Debugging: Check package.json and skills/i-have-adhd/SKILL.md when test_omp_package.py fails

Frequently Asked Questions

Do I need to install dependencies to run the I-Have-ADHD adapter tests?

No. The test suite uses only Python's built-in unittest framework and standard library modules like json and pathlib. As long as you have Python 3 installed and your working directory is the repository root, the tests will execute without any pip install requirements.

What Python version is required to run the unit tests?

The tests expect a recent Python 3 interpreter (3.7+). The code uses modern standard library features like pathlib.Path and f-strings. Python 2 is not supported due to syntax and module differences.

How do I debug a failing test in test_omp_package.py?

First, read the assertion error message to identify which specific check failed. If the test test_omp_and_pi_extension_manifests_are_declared fails, open package.json and verify that the omp.extensions array contains "./extensions/i-have-adhd.ts" and that the pi field exists. For test_skill_remains_explicitly_invoked, inspect skills/i-have-adhd/SKILL.md to ensure the front-matter between the --- delimiters includes both name: i-have-adhd and disable-model-invocation: true.

Can I run the tests without the evaluation driver scripts?

Yes. The tests are modular. If you run python -m unittest tests.test_omp_package or python -m unittest tests.test_always_on_hooks, you bypass the evaluation driver entirely. Only tests/test_run_evals.py requires scripts/run_evals.py to exist and be executable.

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