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

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, tests/test_omp_package.py, and related modules.

Some tests in 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 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:

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.

  python3 -m unittest tests.test_always_on_hooks

• OpenCode plugin: Verify plugin loading and banner injection (requires Node).

  python3 -m unittest tests.test_opencode_plugin

• OMP package: Check extension registration and package loading logic.

  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.

Execute the validation command:

python3 scripts/run_evals.py validate

This script, located at 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 configuration invokes:

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.

Frequently Asked Questions

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

No. While 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. 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 script performs integration validation by reading test cases from evals/cases.jsonl and applying the quality rubric in 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 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.

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