|
| 1 | +# Cached fixtures for Python test suites |
| 2 | + |
| 3 | +`gix.testtools` binds `gix-testtools`' native fixture cache. It is available in |
| 4 | +every build, including reduced hash configurations. Paths and return values |
| 5 | +follow the Rust API; fixture paths are `pathlib.Path` objects. |
| 6 | + |
| 7 | +Run tests from the test project's root. Fixtures and scripts live under |
| 8 | +`tests/fixtures`, generated directories under |
| 9 | +`tests/fixtures/generated-do-not-edit`, and reusable TAR archives under |
| 10 | +`tests/fixtures/generated-archives`. Names passed to `rust_fixture_*` must |
| 11 | +be a single path component, unique within that project. The Rust function |
| 12 | +names are retained even when Python supplies the producer: |
| 13 | + |
| 14 | +```python |
| 15 | +import gix |
| 16 | +from gix import testtools |
| 17 | + |
| 18 | +def make_fixture(state): |
| 19 | + path = state.path() |
| 20 | + if state.is_uninitialized(): |
| 21 | + repo = gix.init(path / "repo", options=gix.OpenOptions.isolated()) |
| 22 | + blob_id = repo.write_blob(b"fixture content") |
| 23 | + (path / "blob-id").write_text(str(blob_id)) |
| 24 | + return (path / "blob-id").read_text() |
| 25 | + |
| 26 | +fixture, blob_id = testtools.rust_fixture_read_only("objects", 1, make_fixture) |
| 27 | +repo = gix.open_opts(fixture / "repo", gix.OpenOptions.isolated()) |
| 28 | +assert repo.find_blob(blob_id).data == b"fixture content" |
| 29 | +``` |
| 30 | + |
| 31 | +The callback receives a `FixtureState`. `is_uninitialized()` is true when |
| 32 | +it must create or post-process contents; it is false when the fixture comes |
| 33 | +from the cache or an archive. The callback runs in either case to compute |
| 34 | +its return value. Increment `version` whenever the callback's generation |
| 35 | +behavior changes. The native lock coordinates concurrent creators, and a |
| 36 | +failed producer leaves a marker so the next call recreates the fixture. |
| 37 | +Python exceptions retain their original type and instance. |
| 38 | + |
| 39 | +Read-only fixtures are a usage contract, not filesystem write protection. |
| 40 | +Never mutate the returned directory or run Git operations that could change |
| 41 | +its index, references, or configuration. Use isolated native open options |
| 42 | +for reading. Post-process only while `is_uninitialized()` is true. |
| 43 | + |
| 44 | +For a script, use `scripted_fixture_read_only("make.sh")`, or provide a |
| 45 | +Python closure to `scripted_fixture_read_only_with_post("make.sh", 1, post)`. |
| 46 | +The corresponding `_with_args` functions forward a list of arguments; |
| 47 | +`scripted_fixture_read_only_with_args_with_post` accepts both. Scripts run |
| 48 | +with native Git environment isolation. Bash fixtures can use |
| 49 | +`gix_testtools_require_symlinks` and `fixture_has_symlinks()` for preflight. |
| 50 | +Scripts need Git and their own interpreter installed; Python-only producers |
| 51 | +can use native `gix` operations. Creating native archives still requires Git |
| 52 | +to record its version in the archive metadata; ignoring archive creation |
| 53 | +avoids that requirement. |
| 54 | + |
| 55 | +Tests that mutate a fixture use a writable temporary directory: |
| 56 | + |
| 57 | +```python |
| 58 | +temporary, blob_id = testtools.rust_fixture_writable( |
| 59 | + "objects", 1, testtools.Creation.CopyFromReadOnly, make_fixture |
| 60 | +) |
| 61 | +with temporary: |
| 62 | + work = temporary.path() |
| 63 | + # Mutate only this disposable copy. |
| 64 | +``` |
| 65 | + |
| 66 | +`TempDir.close()`, leaving its context, or dropping it removes the directory. |
| 67 | +The cached source remains available. `Creation.CopyFromReadOnly` may call |
| 68 | +the callback twice: once for the cache, then with a fresh state at the copy |
| 69 | +to compute a value for its final location. This native copy mode does not |
| 70 | +preserve symlinks. Use `Creation.Execute` for symlinks or absolute paths: |
| 71 | +it generates directly in the final temporary directory. The scripted |
| 72 | +writable helpers provide the same modes and post-processing overloads. |
| 73 | + |
| 74 | +Archive generation and extraction retain native behavior. Ignore generated |
| 75 | +directories with `tests/fixtures/generated-do-not-edit/` and, when archives |
| 76 | +are unwanted, ignore `tests/fixtures/generated-archives/*.tar`. Set |
| 77 | +`GIX_TEST_IGNORE_ARCHIVES=1` to regenerate locally, or use |
| 78 | +`scripted_fixture_read_only_needs_archive()` for native archive preference. |
| 79 | +It prefers an existing archive despite that variable and falls back to the |
| 80 | +script if no matching archive exists. This build uses TAR, without XZ. |
| 81 | +`GIX_TEST_FIXTURE_HASH` selects an enabled fixture hash kind. |
| 82 | + |
| 83 | +`fixture_path()` resolves a fixture input, `fixture_bytes()` reads its bytes, |
| 84 | +and `git(directory, arguments)` runs the native isolated Git helper for a |
| 85 | +reference result. The argument string follows its shell-like quote parsing. |
| 86 | +Git here is a test oracle, not a repository-operation fallback. |
| 87 | + |
| 88 | +Native work runs detached from Python. The producer callback attaches only |
| 89 | +while it runs; no repository state mutex is held by the binding. Callbacks |
| 90 | +must not recursively request the same fixture, whose native file lock is |
| 91 | +held until generation finishes. Avoid changing the process working |
| 92 | +directory or environment while fixtures run concurrently. Python retains |
| 93 | +ownership of signal handlers; importing the module and generating fixtures |
| 94 | +does not install native termination handlers. |
| 95 | + |
| 96 | +The binding covers the fixture APIs above, not every `gix-testtools` utility. |
| 97 | +Single-archive argument variants, Git-version predicates, process-environment |
| 98 | +guards, repository snapshots, Git daemons, and Cargo example builders are |
| 99 | +not currently exposed. |
0 commit comments