# Testing Requirements for Each Lesson’s Code Directory in AI Engineering from Scratch

> Discover testing requirements for each lesson in AI Engineering from Scratch. Ensure 5+ unit tests, exit code 0, and adherence to AGENTS.md conventions for robust code.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: testing
- Published: 2026-06-21

---

**Every lesson in the rohitg00/ai-engineering-from-scratch curriculum must contain at least five unit tests inside a `code/tests/` directory, execute with exit code 0, and adhere to the language-specific conventions defined in the repository’s [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) contract.**

The **testing requirements for each lesson's code directory** are strictly enforced to ensure educational code remains functional and demonstrable. These standards are codified in the **AGENTS.md** document (lines 108–112) and validated through both continuous integration and local linting tools.

## Minimum Test Coverage Standards

Each lesson must provide **at least 5 unit tests** that exercise the core functionality implemented in that module. This minimum threshold ensures sufficient coverage for educational examples without imposing undue overhead on simple concepts. The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specification explicitly mandates this count as part of the curriculum’s quality gate.

## Directory Structure and File Naming Conventions

All test artifacts must reside in a dedicated subdirectory path: `code/tests/`.

File naming must follow standard language conventions to ensure automatic discovery by test runners:

- **Python**: `test_*.py`
- **TypeScript**: `test_*.ts`
- **Rust / Julia**: Use the language’s inline test facilities with appropriate module naming

This placement pattern allows the [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validation script to programmatically verify the presence of a non-empty `tests/` folder within every lesson’s `code/` directory.

## Language-Specific Execution Commands

Tests must be runnable using the language’s standard-library or canonical test runner without additional dependencies:

- **Python**: Execute with `python3 -m unittest discover` from the `code/` directory
- **TypeScript**: Run via `npx tsx --test`
- **Rust**: Utilize `cargo test` (inline tests)
- **Julia**: Employ the built-in `Test` module facilities

Regardless of language, the test suite must terminate with **exit code 0** to indicate a successful run. Any non-zero exit status constitutes a failure in the CI pipeline.

## CI Pipeline and Local Validation

The repository enforces these standards through two mechanisms:

1. **Per-PR validation**: The continuous integration pipeline checks every pull request against the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) contract, verifying that modified lessons include the required `code/tests/` directory and meet the minimum test count.

2. **Local audit script**: The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) utility allows contributors to validate lessons locally before submission. This script scans the `phases/*/*/code/` hierarchy to confirm:
   - Existence of a non-empty `tests/` subdirectory
   - Compliance with naming conventions
   - Minimum test threshold satisfaction

## Example Test Implementation

Below is a minimal Python test file that satisfies the five-test requirement. Place this at [`phases/xx-phase-slug/yy-lesson-slug/code/tests/test_main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/xx-phase-slug/yy-lesson-slug/code/tests/test_main.py):

```python
import unittest
from main import add, mul  # example functions from the lesson implementation

class TestLessonFunctions(unittest.TestCase):
    def test_add_positive(self):
        self.assertEqual(add(2, 3), 5)

    def test_add_negative(self):
        self.assertEqual(add(-1, -1), -2)

    def test_mul_positive(self):
        self.assertEqual(mul(2, 3), 6)

    def test_mul_zero(self):
        self.assertEqual(mul(0, 5), 0)

    def test_mul_negative(self):
        self.assertEqual(mul(-2, 3), -6)

if __name__ == "__main__":
    unittest.main()

```

Execute the suite locally from the lesson’s `code/` directory:

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

```

This command must exit with code `0` to satisfy the CI requirements.

## Summary

- **Location**: All tests must live in `phases/*/*/code/tests/` (or the equivalent lesson path).
- **Quantity**: A minimum of 5 unit tests is required per lesson.
- **Naming**: Follow `test_*` prefixes for Python and TypeScript files to enable auto-discovery.
- **Execution**: Use standard runners (`unittest`, `tsx --test`, `cargo test`) and ensure exit code 0.
- **Enforcement**: Validated by [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specifications, CI pipelines, and [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py).

## Frequently Asked Questions

### How many unit tests are required for each lesson?

Each lesson must contain **at least 5 unit tests** as specified in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) document. This minimum ensures adequate coverage of the lesson’s learning objectives while maintaining a consistent quality baseline across the curriculum.

### Where should test files be placed within a lesson directory?

Test files must be placed in the `code/tests/` subdirectory relative to the lesson root. For example, a lesson located at `phases/01-fundamentals/02-data-structures/` would store its tests in `phases/01-fundamentals/02-data-structures/code/tests/`. Files should follow naming patterns like `test_*.py` or `test_*.ts` depending on the implementation language.

### How do I run the test suite locally before submitting a pull request?

Navigate to the lesson’s `code/` directory and use the standard test runner for the lesson’s language. For Python lessons, execute `python3 -m unittest discover tests -v`. For TypeScript, use `npx tsx --test`. Ensure the process exits with code 0. You can also run [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) from the repository root to validate all lessons at once.

### What happens if my lesson does not meet the testing requirements?

The **CI pipeline** will reject pull requests that fail to include a non-empty `code/tests/` directory or that contain fewer than 5 tests. Additionally, the [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script will flag non-compliant lessons during local development, preventing incomplete submissions from reaching the review stage.