# i-Have-ADHD Plugin Testing Frameworks: How unittest Powers the Test Suite

> Discover how the i-have-adhd plugin leverages Python's unittest framework for robust testing. Learn about its test suite structure and execution.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: deep-dive
- Published: 2026-08-18

---

**The i-have-adhd plugin uses Python's standard-library `unittest` as its sole testing framework, with all test modules in the `tests/` directory subclassing `unittest.TestCase` and CI workflows invoking the suite via `python -m unittest discover`.**

The `i-have-adhd` repository by ayghri is an OpenCode plugin project that emphasizes reliable, automated testing. The testing infrastructure leverages Python's built-in capabilities rather than external dependencies, making the project lightweight and maintainable. Understanding the testing frameworks for the i-have-adhd plugin reveals a deliberate choice to minimize dependency overhead while delivering comprehensive coverage across evaluation harnesses, plugin integrations, and packaging logic.

## Core Testing Framework: Python's unittest

Every test file in the `tests/` directory imports `unittest` and follows standard patterns for defining test cases. The framework requires no pip installation, reducing environment setup complexity for contributors.

### Test File Structure

Each test module subclasses `unittest.TestCase` and uses native assertion methods:

```python

# From tests/test_run_evals.py

import unittest

class EvaluationHarnessTest(unittest.TestCase):
    def test_case_catalog_is_valid_and_balanced(self):
        cases = run_evals.load_cases(ROOT / "evals" / "cases.jsonl")
        errors = run_evals.validate_cases(cases)
        self.assertEqual([], errors)               # unittest assertion

        self.assertGreaterEqual(len(cases), 12)    # unittest assertion

```

This pattern appears consistently across all four test modules, demonstrating uniform adherence to `unittest` conventions.

## Test Coverage Areas in the tests/ Directory

The `tests/` directory contains four specialized test modules, each targeting distinct plugin functionality:

- **[`tests/test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py)** — Validates the evaluation harness, including case loading, JSONL parsing, and schema validation
- **[`tests/test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_opencode_plugin.py)** — Exercises OpenCode plugin integration and protocol compliance
- **[`tests/test_omp_package.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_omp_package.py)** — Verifies OMP (Open Model Package) artifact generation and structure
- **[`tests/test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_always_on_hooks.py)** — Tests persistent hook scripts and their lifecycle management

All four files use identical import statements (`import unittest`) and assertion styles, confirming no mixing of testing frameworks occurs.

## CI Integration: How Tests Execute

The continuous integration configuration explicitly invokes `unittest` through Python's module execution interface. The [`plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/plugin-load-check.yml) workflow contains:

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

```

This command discovers all `unittest.TestCase` subclasses in the `tests/` directory and runs them with verbose output. No [`pytest.ini`](https://github.com/ayghri/i-have-adhd/blob/main/pytest.ini), [`setup.py`](https://github.com/ayghri/i-have-adhd/blob/main/setup.py) test commands, or third-party test runners appear in the repository.

## The Role of scripts/run_evals.py

The [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) file is frequently mistaken for a testing framework component, but it serves a distinct purpose. According to the source analysis, this script is an **evaluation driver utility**, not a test framework.

### What run_evals.py Actually Does

- Loads evaluation cases from JSONL files
- Validates case structure and content balance
- Aggregates model performance scores across evaluation runs
- Generates reports for model benchmarking

The script is invoked by CI pipelines for model evaluation workflows, but it does not import any testing libraries itself. Instead, [`tests/test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py) imports and tests the functions within [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py), creating a clean separation between evaluation logic and test infrastructure.

## Why unittest Over pytest or nose?

The i-have-adhd plugin's choice of `unittest` reflects several practical considerations evident in the codebase:

1. **Zero dependency overhead** — No [`requirements-dev.txt`](https://github.com/ayghri/i-have-adhd/blob/main/requirements-dev.txt) entries for testing frameworks
2. **Standard library stability** — Python's built-in testing module avoids version conflicts
3. **Simple CI configuration** — Single-command execution without plugin installation
4. **Familiar patterns** — Subclass-based test organization matches plugin architecture

This approach sacrifices some pytest conveniences (fixture autodiscovery, parameterized tests, rich assertion introspection) in favor of minimal tooling and predictable behavior across Python versions.

## Summary

- **Python `unittest`** is the exclusive testing framework for the i-have-adhd plugin, with all four test modules in `tests/` subclassing `unittest.TestCase`
- **Test discovery** runs via `python -m unittest discover -s tests -v` in CI workflows
- **[`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py)** is an evaluation utility, not a testing framework—it loads and scores model evaluation cases without using any test libraries
- **Four test modules** cover evaluation harnesses ([`test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_run_evals.py)), plugin integration ([`test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_opencode_plugin.py)), packaging ([`test_omp_package.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_omp_package.py)), and hook scripts ([`test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_always_on_hooks.py))
- The standardized `unittest` approach eliminates external testing dependencies and simplifies contributor onboarding

## Frequently Asked Questions

### Does the i-have-adhd plugin use pytest for testing?

No. The plugin uses only Python's standard-library `unittest` framework. All test files import `unittest` directly, and the CI workflows invoke `python -m unittest discover` rather than `pytest`. No pytest configuration files or dependencies exist in the repository.

### What is the purpose of scripts/run_evals.py if it's not a test framework?

[`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) is an evaluation driver that loads model evaluation cases from JSONL files, validates their structure, and aggregates performance scores. It supports model benchmarking workflows but contains no test assertions or testing framework imports. The actual tests for this script reside in [`tests/test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/tests/test_run_evals.py), which uses `unittest` to verify the script's functions.

### How are the i-have-adhd plugin tests executed in continuous integration?

The [`.github/workflows/plugin-load-check.yml`](https://github.com/ayghri/i-have-adhd/blob/main/.github/workflows/plugin-load-check.yml) workflow executes `python -m unittest discover -s tests -v`. This command auto-discovers all `unittest.TestCase` subclasses in the `tests/` directory and runs them with verbose output, producing detailed pass/fail reporting without requiring additional test runner installation.

### Which test modules exist in the tests/ directory and what do they cover?

Four test modules comprise the suite: [`test_run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_run_evals.py) (evaluation harness validation), [`test_opencode_plugin.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_opencode_plugin.py) (OpenCode protocol integration), [`test_omp_package.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_omp_package.py) (package artifact generation), and [`test_always_on_hooks.py`](https://github.com/ayghri/i-have-adhd/blob/main/test_always_on_hooks.py) (persistent hook lifecycle management). All use identical `unittest` patterns and assertion styles.