# How to Run Tests in the i-have-adhd Project

> Easily run tests in the i-have-adhd project. Execute the full suite or target specific modules to ensure code quality and functionality. Learn how to test effectively.

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

---

**Run the full test suite with `python3 -m unittest discover -s tests -v` to validate all components, or execute individual modules like `tests.test_always_on_hooks` for targeted testing of specific functionality.**

The `i-have-adhd` repository ships with a comprehensive Python-based testing framework located in the `tests/` directory. If you are contributing to the project or verifying local modifications, understanding how to run tests in the i-have-adhd project ensures that skill markdown, always-on hook scripts, and OpenCode plugin integrations function correctly across platforms. The suite is self-contained and designed to run on any system with Python 3 installed.

## Prerequisites for Running Tests

According to the ayghri/i-have-adhd source code, the test suite requires minimal dependencies. You need a recent Python 3 interpreter to execute the unit tests located in [`tests/test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_always_on_hooks.py), [`tests/test_omp_package.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_omp_package.py), and related modules.

Some tests in [`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py) require the `node` executable to validate plugin banner injection and runtime compatibility. However, these tests automatically skip themselves if Node.js is unavailable, ensuring the rest of the suite executes without errors.

## Running the Complete Test Suite

The canonical command documented in [`CONTRIBUTING.md`](https://github.com/ayghri/i-have-adhd/blob/main/CONTRIBUTING.md) uses Python’s built-in unittest discovery mechanism. This approach finds every file matching `test_*.py` inside the `tests/` directory and executes them with verbose output.

Execute the following from the repository root:

```bash
python3 -m unittest discover -s tests -v

```

This command validates front-matter stripping logic, always-on hook behavior for shell and PowerShell runtimes, and OMP package registration as implemented in the test modules.

## Testing Individual Components

For targeted validation during development, run specific test modules directly rather than the entire discovery sweep. This saves time when modifying isolated features.

- **Always-on hooks**: Validate hook script injection and front-matter handling.
  ```bash
  python3 -m unittest tests.test_always_on_hooks
  ```

- **OpenCode plugin**: Verify plugin loading and banner injection (requires Node).
  ```bash
  python3 -m unittest tests.test_opencode_plugin
  ```

- **OMP package**: Check extension registration and package loading logic.
  ```bash
  python3 -m unittest tests.test_omp_package
  ```

## Validation with the Evaluation Harness

After unit tests pass, run the higher-level evaluation script to verify end-to-end skill behavior against structured test cases. The harness reads case definitions from `evals/cases.jsonl` and applies the scoring rubric defined in [`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md).

Execute the validation command:

```bash
python3 scripts/run_evals.py validate

```

This script, located at [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py), performs integration testing beyond individual unit assertions, ensuring the skill responds correctly to the defined evaluation scenarios.

## Continuous Integration Setup

The repository’s GitHub Actions workflows automatically execute these test commands on every push and pull request. The [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) configuration invokes:

```bash
python -m unittest tests.test_always_on_hooks -v

```

These CI checks ensure that `python3 -m unittest discover -s tests -v` runs consistently across Linux, macOS, and Windows environments, preventing regressions in the always-on hook scripts or OpenCode plugin functionality.

## Summary

- **Primary command**: Use `python3 -m unittest discover -s tests -v` to execute the full suite under `tests/`.
- **Modular testing**: Target `tests.test_always_on_hooks`, `tests.test_opencode_plugin`, or `tests.test_omp_package` for specific component validation.
- **Evaluation layer**: Run `python3 scripts/run_evals.py validate` to check skill behavior against `evals/cases.jsonl`.
- **Requirements**: Python 3 is mandatory; Node.js is optional and tests skip gracefully if absent.
- **CI alignment**: Local commands mirror the GitHub Actions workflows defined in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml).

## Frequently Asked Questions

### Do I need Node.js installed to run the test suite?

No. While [`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py) validates OpenCode plugin functionality that requires the `node` executable, the unittest framework automatically detects missing dependencies and skips those specific tests. The core Python tests for always-on hooks and OMP packages execute regardless of Node availability.

### How do I run only the always-on hooks validation?

Execute `python3 -m unittest tests.test_always_on_hooks` to run exclusively the tests defined in [`tests/test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_always_on_hooks.py). This module verifies hook script behavior across different runtimes including shell, Node, and PowerShell, making it ideal for testing front-matter stripping and injection logic without running unrelated plugin tests.

### What does the evaluation harness check?

The [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) script performs integration validation by reading test cases from `evals/cases.jsonl` and applying the quality rubric in [`evals/rubric.md`](https://github.com/ayghri/i-have-adhd/blob/main/evals/rubric.md). Running `python3 scripts/run_evals.py validate` after unit tests ensures the skill responds correctly to real-world scenarios beyond isolated unit assertions.

### Are the tests executed automatically in CI?

Yes. The GitHub Actions workflows in [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) trigger the identical unittest commands on every commit and pull request. These workflows run `python -m unittest tests.test_always_on_hooks -v` and related discovery commands to maintain cross-platform stability.