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

> Learn to run individual lesson tests in AI Engineering From Scratch using Python and TypeScript stdlib test runners. Execute tests easily with simple commands.

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

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```bash
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)](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:

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

npm install

tsx --test tests/*.test.ts

```

The [`package.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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)](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:

```bash
#!/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/run-tests.sh), make it executable (`chmod +x run-tests.sh`), and invoke it with the relative path to any lesson:

```bash
./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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file, and global policy is summarized in [[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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)](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.