unit-tests

name	unit-tests
description	Run Django unit tests in the edx-enterprise Docker container. Use when the user wants to run tests, check if tests pass, or verify test coverage.
argument-hint	<TEST_FILES>
allowed-tools	Bash(docker *), Bash(make *), Bash(colima *)

Arguments

<TEST_FILES> (optional): One or more folders, test file paths, or pytest node IDs to run. Coverage is only enabled when a single folder representing a code domain is provided or no arguments are provided.

Examples:

• /unit-tests — run all tests with coverage
• /unit-tests tests/test_enterprise/test_tasks.py — run one test file without coverage
• /unit-tests tests/test_enterprise/test_tasks.py tests/test_consent/test_helpers.py — run multiple test files without coverage
• /unit-tests tests/test_enterprise/test_tasks.py::TestSomeClass::test_method — run a single test by node ID without coverage

Routing rules (evaluate in order)

• No arguments → Step 2b (whole-project tests + whole-project coverage)
• Everything else → Step 2a (targeted tests, NO coverage)

Steps

1. Make sure the test-shell container is running

Always run this first — it is idempotent, and it also generates the .env file which gives each clone of this repo its own docker compose project name (so multiple clones don't fight over the same container):

make dev.up

IMPORTANT: always interact with the container via docker compose (which reads .env), never via bare docker commands with a hardcoded container name — the container name is different in every clone.

2a. Run specific unit test files or functions

If <TEST_FILES> is provided, run only those tests using pytest.local.ini to disable coverage and warnings:

docker compose exec test-shell bash -c "pytest -c pytest.local.ini <TEST_FILES>"

Never enable coverage reports (by adding --cov) when only testing specific files, since the results will be misleading.

2b. Run whole-project unit tests and generate coverage

If no arguments are given, assume the user wants to run the full test suite for the entire project:

docker compose exec test-shell make test

Whole-project coverage will be reported in the console output. Specific line numbers with missing coverage will be reported.

Troubleshooting

ModuleNotFoundError

If tests fail due to missing imports, first try to install requirements:

docker compose exec test-shell make requirements

This is necessary at least when adding new requirements which have not yet been built into the image.

Failed to connect to the docker API on MacOS

This likely just means colima needs to be started:

colima start