docs: document test layers, shared course fixtures, and CI expectations#69
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites the
## Testingsection ofdocs/development.mdto give contributors a current contract for the test suite. It documents the unit-vs-integration split with exact commands, the sharedcreate_temporary_coursefactory andcourse_creation_lockfixture consolidated in #62 (including why course creation is serialized acrosspytest-xdistworkers), 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 sharedcreate_temporary_course(session, base_url, sesskey, *, prefix, **kwargs)factory andcourse_creation_lockfixture fromtests/conftest.py, why creation is serialized (Moodle-sidemdl_contextunique-constraint race, cross-process file lock), and that new integration modules needing a temp course must use the factory instead of callingcreate_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:
pytest tests/unit -q-> all tests passed (.....100%, no failures).python -m mkdocs buildcompleted ("Documentation built in 1.55 seconds"). The only warnings are pre-existing and unrelated to this change (the auto-generated, git-ignoredcli.mdreferenced bynav/quickstart); no new warning referencesdevelopment.md.create_temporary_course,course_creation_lock, and_course_creation_lockintests/conftest.py;make test-unit,make test-local,make test-staging,make test,make docsin theMakefile; the CI matrix inREADME.md's Testing section.Test plan
Commands run:
Backwards compatibility
No behavior change. Documentation only; no source, test, or fixture files touched.
Documentation
docs/development.mdonly: the## Testingsection 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 sharedcreate_temporary_coursefactory.Notes for reviewers
I stayed strictly within my file-ownership boundary: the only file changed is
docs/development.md(confirmed viagit status/git diff --stat). No source file, no test file, notests/conftest.py, noREADME.md, nodocs/recipes.md, and no other docs were touched. Fixture and command names were verified against the livetests/conftest.pyandMakefile. The #68 reference is intentionally a forward reference (that sibling PR owns the actual scaffolding); this PR does not duplicate its content.