Skip to content

docs: document caplog, capsys, capfd, recwarn, tmp_path_factory built-in fixtures#664

Merged
MatthewMckee4 merged 1 commit intomainfrom
docs/builtin-fixtures
Apr 11, 2026
Merged

docs: document caplog, capsys, capfd, recwarn, tmp_path_factory built-in fixtures#664
MatthewMckee4 merged 1 commit intomainfrom
docs/builtin-fixtures

Conversation

@MatthewMckee4
Copy link
Copy Markdown
Member

Summary

The built-in fixtures page at docs/usage/fixtures/builtin.md only documented tmp_path and monkeypatch, but since alpha.4 Karva has shipped several more built-in fixtures that are fully implemented and integration-tested: caplog, capsys, capfd, capsysbinary, capfdbinary, recwarn, and the session-scoped tmp_path_factory/tmpdir_factory. None of them were discoverable from the docs, so users looking for pytest-equivalents had no way to find them short of reading the source. This PR closes that gap.

The new sections follow the existing tone and structure of the page. Each fixture gets a short description of what it does, a note about which names are accepted (where there are multiple aliases), and one or two minimal runnable examples lifted directly from the integration tests in crates/karva/tests/it/extensions/fixtures/builtins.rs — so everything documented is behaviour the test suite already pins down.

For caplog, the page explains at_level vs set_level and walks through records, messages, record_tuples, and text:

import logging


def test_caplog_records(caplog):
    with caplog.at_level(logging.WARNING):
        logging.warning("something happened")

    assert len(caplog.records) == 1
    assert caplog.records[0].levelname == "WARNING"
    assert "something happened" in caplog.text

For capsys, the page covers readouterr(), the fact that log messages are captured through stderr, and the capsys.disabled() context manager. capfd is documented as the file-descriptor-level counterpart, and capsysbinary/capfdbinary get a shorter section that points out the only difference (.out/.err are bytes). recwarn is documented as a list-like container with pop(category) and clear().

tmp_path_factory is slotted in right after tmp_path and notes that it is session-scoped, so it can be consumed by longer-lived user fixtures — tmp_path itself is function-scoped and cannot.

Test Plan

  • uvx prek run -a passes clean (markdownlint-fix, mdformat, typos, and the rest).
  • Examples are lifted verbatim from passing integration tests in crates/karva/tests/it/extensions/fixtures/builtins.rs, so the documented behaviour is what the test suite already asserts.

@MatthewMckee4 MatthewMckee4 added documentation Improvements or additions to documentation extensions/fixtures Related to fixtures labels Apr 11, 2026
@MatthewMckee4 MatthewMckee4 force-pushed the docs/builtin-fixtures branch from fa12357 to 01d1bdd Compare April 11, 2026 17:04
@MatthewMckee4 MatthewMckee4 merged commit e536e42 into main Apr 11, 2026
7 checks passed
@MatthewMckee4 MatthewMckee4 deleted the docs/builtin-fixtures branch April 11, 2026 17:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation extensions/fixtures Related to fixtures

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant