Skip to content

docs: document test layers, shared course fixtures, and CI expectations#69

Merged
erseco merged 2 commits into
mainfrom
issue-67-test-layer-docs
Jul 7, 2026
Merged

docs: document test layers, shared course fixtures, and CI expectations#69
erseco merged 2 commits into
mainfrom
issue-67-test-layer-docs

Conversation

@erseco

@erseco erseco commented Jul 7, 2026

Copy link
Copy Markdown
Owner

Summary

Rewrites the ## Testing section of docs/development.md to give contributors a current contract for the test suite. It documents the unit-vs-integration split with exact commands, the shared create_temporary_course factory and course_creation_lock fixture consolidated in #62 (including why course creation is serialized across pytest-xdist workers), a forward reference to the HTML-fixture regression scaffolding from #68, and CI expectations cross-referenced to the README (single source of truth for version numbers).

Linked issue

Closes #67

Specification (SDD)

Update only docs/development.md's Testing section to document: (a) the unit (tests/unit/, no Moodle) vs integration (tests/test_*.py, --integration + live Moodle) layers with the exact commands (make test-unit / pytest tests/unit / make test-local / pytest --integration --moodle-env local -m integration -n auto); (b) the shared create_temporary_course(session, base_url, sesskey, *, prefix, **kwargs) factory and course_creation_lock fixture from tests/conftest.py, why creation is serialized (Moodle-side mdl_context unique-constraint race, cross-process file lock), and that new integration modules needing a temp course must use the factory instead of calling create_course() directly; (c) a short forward reference to the HTML-fixture regression tests; (d) CI expectations by cross-reference, keeping authoritative Python/Moodle numbers in the README. Public contract: every documented command must actually work.

TDD evidence

No automated test is added because this change is documentation-only (issue section 6 states classic red/green does not apply). Verification per the issue's adapted test plan:

  • Unit layer still green: pytest tests/unit -q -> all tests passed (..... 100%, no failures).
  • Docs build: python -m mkdocs build completed ("Documentation built in 1.55 seconds"). The only warnings are pre-existing and unrelated to this change (the auto-generated, git-ignored cli.md referenced by nav/quickstart); no new warning references development.md.
  • Every referenced name verified to exist: create_temporary_course, course_creation_lock, and _course_creation_lock in tests/conftest.py; make test-unit, make test-local, make test-staging, make test, make docs in the Makefile; the CI matrix in README.md's Testing section.

Test plan

  • Added/authored failing test(s) first (or: docs-only, N/A). Docs-only, N/A.
  • Confirmed red before implementing. Docs-only, N/A.
  • Implemented minimal change.
  • Focused tests green.
  • Full "pytest tests/unit" green.

Commands run:

pytest tests/unit -q
PYTHONPATH=src python -m mkdocs build

Backwards compatibility

No behavior change. Documentation only; no source, test, or fixture files touched.

Documentation

docs/development.md only: the ## Testing section was restructured to add a "Test Layers" overview, a "Shared Course-Creation Fixtures" subsection (with a "Why course creation is serialized" explanation and a mandatory-use note), an "HTML-Fixture Regression Tests" forward reference to #68, and a "CI Expectations" subsection that cross-references the README rather than duplicating version numbers. The example test now uses the shared create_temporary_course factory.

Notes for reviewers

I stayed strictly within my file-ownership boundary: the only file changed is docs/development.md (confirmed via git status/git diff --stat). No source file, no test file, no tests/conftest.py, no README.md, no docs/recipes.md, and no other docs were touched. Fixture and command names were verified against the live tests/conftest.py and Makefile. The #68 reference is intentionally a forward reference (that sibling PR owns the actual scaffolding); this PR does not duplicate its content.

@erseco erseco merged commit fdcc21e into main Jul 7, 2026
31 of 33 checks passed
@erseco erseco deleted the issue-67-test-layer-docs branch July 7, 2026 23:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document test layers, shared fixtures, and contributor test commands

1 participant