How to Run Individual Lesson Tests Using stdlib Test Runners in AI‑Engineering‑From‑Scratch

Every lesson in the AI‑Engineering‑From‑Scratch repository includes a self-contained test suite that you can execute using language-specific stdlib runners: python3 -m unittest discover for Python and tsx --test for TypeScript.

The rohitg00/ai-engineering-from-scratch curriculum follows a strict convention where each lesson ships with its own implementation and matching test suite. Rather than relying on external testing frameworks like pytest or Jest, the repository leverages the standard library test runners built into Python and Node.js to keep dependencies minimal and the learning curve gentle.

Lesson Structure and Test Conventions

Each lesson lives under phases/<phase-slug>/<lesson-slug>/ and adheres to a predictable layout that the stdlib runners can automatically discover:

• code/main.<ext> – The entry-point implementation file.
• code/tests/ – A directory containing test modules (test*.py or *_test.py for Python, *.test.ts for TypeScript).
• docs/en.md – Lesson documentation that includes the exact terminal command to invoke the tests.

This structure allows the Python unittest module to recursively walk code/tests and the Node.js --test flag to match tests/*.test.ts patterns without additional configuration files.

Running Python Tests with unittest

Python lessons use the built-in unittest framework. The discovery mechanism automatically locates any file matching test*.py or *_test.py inside the specified directory.

Navigate to the lesson root and execute the discovery command with verbose output:

cd phases/14-agent-engineering/54-build-the-feedback-ratchet

python3 -m unittest discover -s code/tests -v

The command appears in the lesson documentation at lines 91‑94 of [phases/14-agent-engineering/54-build-the-feedback-ratchet/docs/en.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/54-build-the-feedback-ratchet/docs/en.md). The -v flag produces a verbose summary of each test case, while -s code/tests sets the discovery start directory relative to your current position.

Running TypeScript Tests with tsx

TypeScript lessons utilize tsx, a Node.js-compatible wrapper that invokes the native node --test runner. This keeps the workflow entirely within the standard library ecosystem without requiring Jest, Mocha, or Vitest.

After installing dependencies once per lesson, run the test suite:

cd phases/19-capstone-projects/17-personal-ai-tutor

npm install

tsx --test tests/*.test.ts

The package.json at [phases/19-capstone-projects/17-personal-ai-tutor/code/ts/package.json](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/17-personal-ai-tutor/code/ts/package.json) defines the test script as "test": "tsx --test tests/*.test.ts", ensuring the command uses the built-in Node.js test runner. The glob pattern tests/*.test.ts matches all TypeScript test files in the lesson directory.

Optional: Cross-Language Test Helper Script

If you frequently validate multiple lessons across the curriculum, create a universal helper script that detects the language and invokes the appropriate stdlib runner:

#!/usr/bin/env bash

# usage: run-tests.sh <lesson-path>

lesson="$1"
if [[ -f "$lesson/code/main.py" ]]; then
    python3 -m unittest discover -s "$lesson/code/tests" -v
elif [[ -f "$lesson/code/ts/package.json" ]]; then
    (cd "$lesson/code/ts" && npm install && tsx --test tests/*.test.ts)
else
    echo "No recognized test runner found for $lesson"
fi

Save the file as run-tests.sh, make it executable (chmod +x run-tests.sh), and invoke it with the relative path to any lesson:

./run-tests.sh phases/14-agent-engineering/54-build-the-feedback-ratchet

Summary

• Python lessons rely on python3 -m unittest discover -s code/tests -v to find and execute all test*.py modules.
• TypeScript lessons use tsx --test tests/*.test.ts to leverage Node.js's built-in test runner without external frameworks.
• Documentation for each lesson includes the exact command in its docs/en.md file, and global policy is summarized in [AGENTS.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).
• Exit codes follow stdlib conventions: 0 for success, non-zero for failures, making these commands suitable for CI/CD pipelines.

Frequently Asked Questions

Can I run tests without installing additional frameworks?

Yes. The repository intentionally uses only standard library tools. Python lessons require only the built-in unittest module (included with every Python installation), and TypeScript lessons require only tsx (which wraps Node.js's native --test flag). No pytest, Jest, or Mocha installations are necessary.

Where are the test commands documented for each lesson?

The exact terminal command appears in the lesson's docs/en.md file, located at phases/<phase-slug>/<lesson-slug>/docs/en.md. Additionally, the global [AGENTS.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file contains a centralized reference to the stdlib runner policy used across the entire curriculum.

How do I run tests for a single file instead of all tests?

For Python, specify the module path directly: python3 -m unittest code.tests.test_specific_module. For TypeScript, pass the individual file to tsx: tsx --test tests/specific.test.ts. Both runners support targeting single files while maintaining the same stdlib interface.

What exit codes do the stdlib runners return?

Both unittest and Node.js's built-in test runner return exit code 0 when all tests pass and a non-zero code (typically 1) when any assertion fails or an error occurs. This behavior integrates seamlessly with shell scripts, pre-commit hooks, and GitHub Actions workflows.

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