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

> Learn how to run unit tests for I-Have-ADHD adapters with our comprehensive guide. Execute the full test suite easily from the repository root. Get started today!

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_omp_package.py) file verifies that [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py) file performs a sanity check on [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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:

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

```bash
python -m unittest tests.test_omp_package

```

This executes all test cases within [`tests/test_omp_package.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_omp_package.py) without running the full suite.

### Running Specific Test Cases

To run a single test method for rapid iteration:

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_omp_package.py). Common failure points include:

- **Manifest mismatches**: [`package.json`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) missing the `omp.extensions` or `pi` configuration arrays
- **Missing front-matter**: [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) or [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) | [`tests/test_omp_package.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_omp_package.py) | Declares OMP and Pi adapter extensions |
| [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | [`tests/test_omp_package.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_omp_package.py) | Contains skill metadata and invocation flags |
| `hooks/always-on.mjs` | [`tests/test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_always_on_hooks.py) | Always-on runtime hook entry point |
| [`extensions/i-have-adhd.ts`](https://github.com/ayghri/i-have-adhd/blob/main/extensions/i-have-adhd.ts) | [`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py) | TypeScript adapter implementation |
| [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) | [`tests/test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/package.json) and [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) when [`test_omp_package.py`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py) requires [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) to exist and be executable.