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

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

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:

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 specifications, CI pipelines, and 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 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 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 script will flag non-compliant lessons during local development, preventing incomplete submissions from reaching the review stage.

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