pytest-given 0.5.0__tar.gz → 0.5.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {pytest_given-0.5.0 → pytest_given-0.5.2}/AGENTS.md +1 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/CHANGELOG.md +49 -1
- pytest_given-0.5.2/GLOSSARY.md +116 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/PKG-INFO +24 -10
- {pytest_given-0.5.0 → pytest_given-0.5.2}/README.md +23 -9
- {pytest_given-0.5.0 → pytest_given-0.5.2}/docs/site/configuration/narration-lint.md +3 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/noxfile.py +33 -8
- {pytest_given-0.5.0 → pytest_given-0.5.2}/pyproject.toml +6 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md +3 -5
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md +2 -2
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-authoring/references/lint.md +1 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-authoring/references/parameter-tables.md +5 -3
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md +3 -8
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-authoring/references/stories.md +1 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-citing/SKILL.md +9 -5
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md +9 -3
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-navigating/references/report-json.md +2 -8
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-reviewing/SKILL.md +20 -14
- pytest_given-0.5.2/src/pytest_given/.agents/skills/pytest-given-reviewing/references/completeness.md +22 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/hygiene.md +1 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/process_state.py +5 -4
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/steps.py +10 -5
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/template.py +11 -3
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/traceback.py +1 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/citations/check.py +20 -2
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/cli/__init__.py +2 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/cli/citations.py +6 -2
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/cli/report.py +11 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/cli/skills.py +21 -7
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/grouping/checks.py +47 -19
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/grouping/context.py +3 -4
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/grouping/group.py +16 -9
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/lint/ast_rules.py +21 -11
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/lint/config.py +9 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/markdown/blocks.py +28 -6
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/__init__.py +2 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/errors.py +5 -3
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/schema.py +12 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/serde.py +10 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/plugin/case_ids.py +25 -15
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/plugin/fixtures.py +5 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/plugin/options.py +27 -13
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/plugin/runtest.py +29 -4
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/plugin/session.py +78 -14
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/plugin/state.py +15 -3
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/__init__.py +4 -0
- pytest_given-0.5.2/src/pytest_given/report/console.py +12 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/html_renderer.py +22 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/sinks.py +19 -13
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/slugs.py +23 -7
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/source_link.py +20 -1
- pytest_given-0.5.2/src/pytest_given/report/staged_write.py +41 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/templates/_macros.html.j2 +26 -13
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/templates/report.html.j2 +6 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/templates/styles.css +65 -7
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/test_cli.py +50 -3
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/test_cli_citations.py +27 -2
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/test_plugin.py +349 -77
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/test_skills_cli.py +75 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_glossary.py +30 -26
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_kind_inference.py +47 -18
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_step_descriptor.py +32 -32
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_story.py +13 -24
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_template.py +16 -21
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_traceback_parser.py +1 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/citations/test_check.py +59 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/lint/test_ast_rules.py +37 -1
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/lint/test_config.py +29 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/markdown/test_blocks.py +21 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/model/test_serde.py +17 -0
- pytest_given-0.5.2/tests/unit/report/app_data.py +23 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_coverage.py +15 -37
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_html_renderer.py +783 -1190
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_sinks.py +47 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_slugs.py +21 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_source_link.py +30 -0
- pytest_given-0.5.2/tests/unit/report/test_staged_write.py +22 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_story_view.py +14 -19
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/test_grouping.py +152 -7
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/test_plugin.py +39 -1
- pytest_given-0.5.2/tests/unit/test_quickstart.py +35 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/uv.lock +415 -281
- pytest_given-0.5.0/GLOSSARY.md +0 -116
- pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-reviewing/references/citations.md +0 -10
- pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-reviewing/references/completeness.md +0 -28
- {pytest_given-0.5.0 → pytest_given-0.5.2}/.gitignore +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/LICENSE.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/THIRD-PARTY-LICENSES +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/conftest.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-citing/references/repair.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/story-coverage.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/collector.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/discovery.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/file_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/kind_inference.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/markdown_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/scenario.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/source.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/capture/story.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/citations/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/citations/markdown_links.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/citations/narrated.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/citations/targets.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/grouping/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/grouping/attachments.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/grouping/columns.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/grouping/percase.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/grouping/templatize.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/lint/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/lint/base.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/lint/runner.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/lint/runtime_rules.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/lint/summary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/markdown/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/markdown/plain_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/markdown/spans.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/narration.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/report_url.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/runtime.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/steps.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/model/text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/plugin/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/plugin/collection.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/py.typed +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/citation_index.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/coverage.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/function_source.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/glossary_view.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/inline_markdown.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/link_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/markdown_writer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/md_renderer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/palette.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/story_view.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/templates/alpine.min.js +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/templates/app.js +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/templates/fonts/source-code-pro-latin-wght-normal.woff2 +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/templates/fonts/source-sans-3-latin-wght-normal.woff2 +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/templates/logo.svg +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/src/pytest_given/report/theme.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/conftest.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/test_lazy_imports.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/test_plugin_file_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/test_plugin_lint.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/integration/test_plugin_session_isolation.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/ubiquitous_language.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_collector.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_discovery.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_file_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_markdown_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_rootdir_isolation.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/capture/test_source.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/citation_reports.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/citations/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/citations/fixtures/citation-forms.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/citations/test_markdown_links.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/citations/test_markdown_links_oracle.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/citations/test_narrated.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/citations/test_targets.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/lint/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/lint/test_runtime_rules.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/lint/test_summary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/markdown/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/markdown/test_plain_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/markdown/test_spans.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/model/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/model/test_errors.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/model/test_narration.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/model/test_report_url.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/model/test_schema.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/model/test_steps.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/model/test_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_citation_index.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_function_source.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_glossary_view.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_inline_markdown.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_link_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_markdown_writer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_md_renderer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_palette.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/report/test_theme.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/test_percase.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/test_plugin_traceback.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/test_project_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.2}/tests/unit/test_skills_data.py +0 -0
|
@@ -33,6 +33,7 @@ uv sync --group dev
|
|
|
33
33
|
- `uv run nox -s docs_build` builds the documentation site under `site/` with `zensical build --strict`; run it after changing anything under `docs/site/` (a broken cross-page link fails it) and preview with `uv run --group docs zensical serve`. `docs_deploy` is the CI-only counterpart that publishes with mike — see [docs/releasing.md](docs/releasing.md#documentation-site).
|
|
34
34
|
- Zensical builds every file in `docs/site/` and cannot exclude any, so a file single-sourced elsewhere gets in by a copy the build stages into a gitignored spot (listed in `_build_docs`) or by a `pymdownx.snippets` include — never by a committed second copy.
|
|
35
35
|
- `docs/pytest-given-diagram.svg`, the README's diagram and the Home page's full-size view, is derived with the font embedded and the colour tokens resolved: after editing the source SVG (`docs/site/assets/pytest-given-diagram.svg`) or its tokens, run `uv run nox -s diagram` and commit the result.
|
|
36
|
+
- `docs/site/assets/report-screenshot-{light,dark}.png`, shown on the README and the Home page, are captured by hand: the Hotel booking report at a 1120×588 viewport and device scale 2, with *Cancelling a paid booking refunds it and notifies the guest* expanded, one capture per setting of the report's theme switch. Retake both when the report's look changes.
|
|
36
37
|
- The site self-hosts its fonts so a visitor's browser contacts no third party — keep `font = false` in `zensical.toml` and don't `@import` a font CDN. Only the italics live in `docs/site/assets/fonts/` (latin subsets from Fontsource); a new face gets its `.woff2` there and its copyright line in that folder's `LICENSES.txt`.
|
|
37
38
|
|
|
38
39
|
## Releasing
|
|
@@ -11,6 +11,52 @@ form `## [x.y.z] - YYYY-MM-DD`.
|
|
|
11
11
|
|
|
12
12
|
<!-- --8<-- [start:site] -->
|
|
13
13
|
|
|
14
|
+
## [0.5.2] - 2026-11-07
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
- The HTML report is visually tidied: scrolled content now stops short of the tab rule, a step's attachments no longer crowd the step below, and a scenario's source link shares its last step's line when there is room.
|
|
19
|
+
- An HTML report's parameter table keeps the whitespace in its values, and shows a column narrated with `!r` or `!a` in a monospace font, in its cells and when a hovered row fills in its steps.
|
|
20
|
+
- The bundled `pytest-given-authoring` and `pytest-given-reviewing` skills hold glossary terms and definitions to concepts instead of implementation details.
|
|
21
|
+
- The bundled `pytest-given-authoring` and `pytest-given-reviewing` skills move a trivial control row out of a parameter table when it complicates the narration.
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- A parameter table no longer shows an id column for a long value that pytest 9.2's `parametrize_long_str_id_strategy = sha256` names by its digest.
|
|
26
|
+
- An HTML report Glossary entry now says when no scenario uses its term, so one without stories or forms no longer opens to an empty panel.
|
|
27
|
+
|
|
28
|
+
## [0.5.1] - 2026-10-24
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
|
|
32
|
+
- The documentation site has new [BDD](https://nwilbert.github.io/pytest-given/0.5/bdd/), [HTML report](https://nwilbert.github.io/pytest-given/0.5/html-report/) and [Markdown report](https://nwilbert.github.io/pytest-given/0.5/markdown-report/) pages.
|
|
33
|
+
- `pytest-given citations check` / `update` and `pytest-given report` read `given-report/report-data.json`, where a bare `--given-json` writes it, when no JSON report is passed.
|
|
34
|
+
|
|
35
|
+
### Changed
|
|
36
|
+
|
|
37
|
+
- **Breaking.** A pytest-xdist run (`-n`) that writes a report or runs the narration lint now stops with a usage error instead of writing an empty or partial report: run it without `-n`, or pass `--no-given-lint` to a `-n` run in a project that sets `given_lint = true`.
|
|
38
|
+
- **Breaking.** Brackets after the `::` in a `given_lint_ignore` entry now match a parametrize case literally instead of acting as a glob character class: replace a hand-escaped `[[]` with a plain `[`.
|
|
39
|
+
- **Breaking.** A failed parametrize case that narrates a step it shares with the baseline case differently now fails the run, instead of its row showing under wording it never narrated: narrate the shared steps the way the baseline does.
|
|
40
|
+
- The HTML report's Tags sidebar copy button is visually tidied.
|
|
41
|
+
- The bundled `pytest-given-reviewing` skill flags an assertion that would still pass with its claim false and a parameter-table column of Python reprs, accepts a contrast row under a conditional claim, and asks for a scenario per new rule.
|
|
42
|
+
- The bundled skills are tightened, `pytest-given-navigating` warns that a saved report may cover only a selection and points to where an area has no scenario, and `pytest-given-citing` leaves a claim no test can show uncited.
|
|
43
|
+
|
|
44
|
+
### Fixed
|
|
45
|
+
|
|
46
|
+
- A run that executes no test — `--collect-only`, `--setup-only`, `--setup-plan`, or a selection that matches nothing — no longer overwrites the previous report.
|
|
47
|
+
- An interrupted report write no longer leaves a half-written sink: each file is written to a temporary and moved into place once all of them are written.
|
|
48
|
+
- A chained exception's report now gives the error its own frames, with each cause shown above them as a separate block.
|
|
49
|
+
- A grouped scenario whose cases skipped for different reasons no longer shows one case's reason for all of them.
|
|
50
|
+
- Two scenarios no longer share a `#scenario=` slug when one falls back to its node ID.
|
|
51
|
+
- `pytest-given report --format md`, `citations check --list` and a bare `--given-md` now write UTF-8 to a Windows console whose code page lacks the status glyphs, instead of crashing or printing `\u` escapes.
|
|
52
|
+
- The `conditional-check` lint no longer flags a `then` that checks on every `if`/`else` branch, and `unused-interpolation` no longer flags a step that updates the interpolated name with an augmented assignment such as `total += 1`.
|
|
53
|
+
- `pytest-given citations update` now writes no document that changed on disk while it ran, replaces each document it writes in one atomic rename, and no longer splits a CRLF line break when an edit ends at a line end.
|
|
54
|
+
- `attach()` with content JSON cannot carry, such as non-string dict keys or a cycle, and `Template` with an unclosed brace now raise `PytestGivenError`.
|
|
55
|
+
- A `given_source_link` template with a bad format spec, conversion or brace is now rejected when the option is read, before the tests run, instead of failing the report at render time.
|
|
56
|
+
- A failure raised inside the Markdown-glossary reader now shows its pytest-given frame as internal.
|
|
57
|
+
- A pytest-given registered from a conftest under `PYTEST_DISABLE_PLUGIN_AUTOLOAD` now warns that it loaded too late, instead of silently losing the source links of import-time `Story` and `GlossaryTerm` declarations.
|
|
58
|
+
- `pytest-given skills install` now removes directories no bundled file lives in, and `--check` reports them as drift.
|
|
59
|
+
|
|
14
60
|
## [0.5.0] - 2026-10-18
|
|
15
61
|
|
|
16
62
|
### Added
|
|
@@ -433,7 +479,9 @@ First public release.
|
|
|
433
479
|
- Bundled authoring, navigating, and reviewing skills for AI agents, shipped in
|
|
434
480
|
the wheel and version-matched to the plugin.
|
|
435
481
|
|
|
436
|
-
[Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.5.
|
|
482
|
+
[Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.5.2...HEAD
|
|
483
|
+
[0.5.2]: https://github.com/nwilbert/pytest-given/compare/v0.5.1...v0.5.2
|
|
484
|
+
[0.5.1]: https://github.com/nwilbert/pytest-given/compare/v0.5.0...v0.5.1
|
|
437
485
|
[0.5.0]: https://github.com/nwilbert/pytest-given/compare/v0.4.1...v0.5.0
|
|
438
486
|
[0.4.1]: https://github.com/nwilbert/pytest-given/compare/v0.4.0...v0.4.1
|
|
439
487
|
[0.4.0]: https://github.com/nwilbert/pytest-given/compare/v0.3.0...v0.4.0
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Glossary
|
|
2
|
+
|
|
3
|
+
Canonical vocabulary for pytest-given. Use these terms in code, docs, commit messages, and conversation; flag inconsistencies in review.
|
|
4
|
+
|
|
5
|
+
This glossary covers pytest-given's own bounded context. The terminology a *user's* test suite adopts (the domain the user is testing — e.g., the coffee domain in `examples/coffeeshop/test_coffeeshop.py`) is a separate concern.
|
|
6
|
+
|
|
7
|
+
**Update rule:** rename or repurpose a term → update this file in the same commit.
|
|
8
|
+
|
|
9
|
+
## Core test model
|
|
10
|
+
|
|
11
|
+
| Term | Meaning |
|
|
12
|
+
|---|---|
|
|
13
|
+
| **Scenario** | A test that narrates the rule it demonstrates, marked with `@scenario`. Tests without the mark stay out of the report. |
|
|
14
|
+
| **Scenario title** | The statement of the rule a *Scenario* demonstrates. Not the test function's name, which the *Node ID* carries. |
|
|
15
|
+
| **Step** | A unit of narration in one *Phase*. Steps nest and may carry *Attachments*, but have no status or error of their own: a failure belongs to the *Scenario*, and to its *Case* in a *Parameter table*. |
|
|
16
|
+
| **Narration** | The human-readable text on a step or scenario title, which may mix plain text with values, placeholders and *term refs*. |
|
|
17
|
+
| **Phase** | The category of a step: `given`, `when`, or `then`. A step has exactly one phase. |
|
|
18
|
+
| **when_then** | One block that narrates a `when` action and its `then` outcome as two sibling steps. Used mainly to narrate an expected raise, so the action and its outcome stay distinct steps. |
|
|
19
|
+
| **Tag** | A free-form label on a scenario. A `/` nests it: `ticket/ABC-123` sits under `ticket`. |
|
|
20
|
+
| **Attachment** | A labeled piece of text or JSON bound to the step being narrated. |
|
|
21
|
+
|
|
22
|
+
## Parametrization
|
|
23
|
+
|
|
24
|
+
| Term | Meaning |
|
|
25
|
+
|---|---|
|
|
26
|
+
| **Parametrized scenario** | A *Scenario* whose test is parametrized, so it runs once per *Case*. pytest-given groups the results. |
|
|
27
|
+
| **Case** | One row of a parametrized scenario: its node ID, its parameter values, its status and any error. |
|
|
28
|
+
| **Case ID** | A *Case*'s pytest ID: its *Node ID*'s parametrize tail without the brackets (`touching-edges`), as the terminal prints it. *Custom* when it is more than its values' generated parts, as from `pytest.param(..., id=...)` or `ids=`. |
|
|
29
|
+
| **Parameter table** | The per-scenario table of cases and columns. A column is a `param` (a parametrize input), a `derived` (a narrated value that varies across cases) or an `attachment` (an attachment whose payload varies). |
|
|
30
|
+
| **Group** | Collapsing the cases of a parametrized scenario into one logical scenario carrying a *Parameter table*. Cases group when they share both the same name and the same *Node ID* without its parametrize tail — one test function; two same-named scenarios on different test functions stay separate. `@scenario(group_parametrized=False)` declines the merge, so each case lives on as its own scenario. |
|
|
31
|
+
| **Templatize** | Derive the grouped-template step text by comparing every comparable case: what all of them share stays inline, and anything that varies points at a parameter-table column. The baseline comes from the first passed case, and every other passed case must narrate that same template — a failed case too, over the steps it shares with the baseline. |
|
|
32
|
+
|
|
33
|
+
## Fixtures and recording
|
|
34
|
+
|
|
35
|
+
| Term | Meaning |
|
|
36
|
+
|---|---|
|
|
37
|
+
| **Step fixture** | A pytest fixture that narrates its setup as a `given` *Step*. A fixture cannot narrate `when` or `then`. |
|
|
38
|
+
| **Plain fixture** | A pytest fixture without a pytest-given decorator. It produces no step in the report unless a *Given annotation* on the test's parameter narrates it. |
|
|
39
|
+
| **Given annotation** | A `given(...)` in a test parameter's `Annotated[...]` type: `def test(room: Annotated[int, given('a room')])`. On a parametrize value or a *Plain fixture* it adds a childless `given` step; on a *Step fixture* it replaces the fixture's root label and its pins. Only `given` is allowed, and a `Template` in it may only hold a bare parametrize column. |
|
|
40
|
+
| **Fixture recording** | The steps and attachments a step fixture narrates during setup. A generator fixture's teardown records nothing — it refuses steps and attachments. |
|
|
41
|
+
| **Graft** | Attaching a fixture recording into the active scenario's step tree at the moment its host test starts. |
|
|
42
|
+
|
|
43
|
+
## Collector state
|
|
44
|
+
|
|
45
|
+
| Term | Meaning |
|
|
46
|
+
|---|---|
|
|
47
|
+
| **Collector** | What gathers a session's scenarios, fixture recordings and parameter info. |
|
|
48
|
+
| **Active scenario** | The scenario currently being recorded into. |
|
|
49
|
+
| **Node ID** | A pytest test identifier (e.g., `tests/test_x.py::test_y[a-b]`). |
|
|
50
|
+
| **Step stack** | The chain of currently-open steps. Opening a step adds it, and leaving its block removes it. |
|
|
51
|
+
|
|
52
|
+
## Report
|
|
53
|
+
|
|
54
|
+
| Term | Meaning |
|
|
55
|
+
|---|---|
|
|
56
|
+
| **Report** | The output artifact: a JSON data file and optional self-contained HTML and Markdown renderings derived from it. The JSON is the source of truth. |
|
|
57
|
+
| **Renderer** | Converts a JSON report into a rendering — a self-contained HTML page or a Markdown document. |
|
|
58
|
+
| **Parameter coloring** | Each parametrize column gets a stable highlight color; placeholders and matching values share that color wherever they appear in step text and the parameter table. |
|
|
59
|
+
| **Value highlight** | A neutral highlight applied to t-string interpolation values that don't correspond to a parametrize column and are constant across every case (e.g., a computed expression like `price * 1.2`). One that varies becomes a `derived` column instead. |
|
|
60
|
+
| **Source link** | A link to a file and line: a scenario's test function, or the declaration of a *Story* or *Term*. |
|
|
61
|
+
| **Report link** | A Markdown link to a scenario, tag or story in the HTML *Report*. Without a glyph it is a plain one, which claims only that its target exists. |
|
|
62
|
+
| **Citation** | A *Report link* led by its target's status glyph, citing a scenario, tag or story from a Markdown document: `✅ [title](<report URL>#scenario=…)`. A tag or story citation adds a summary after it, `(5 ✅ · 2 🔵)`. A target the *Report* lacks reads `❓`. |
|
|
63
|
+
| **Narrated citation** | A *Citation* of a scenario written as a collapsible block, the citation as its summary and the scenario's Markdown narration as its body. |
|
|
64
|
+
| **Citation finding** | One problem `pytest-given citations check` reports on one *Report link*: its kind (`stale`, `missing`, `failed`, `mistyped`, …), the document location and a message. |
|
|
65
|
+
| **Theme** | The HTML report's colour scheme — `light`, `dark`, or `auto` (follow the viewer's system). |
|
|
66
|
+
|
|
67
|
+
## Narration lint
|
|
68
|
+
|
|
69
|
+
| Term | Meaning |
|
|
70
|
+
|---|---|
|
|
71
|
+
| **Narration lint** | The `--given-lint` pass that checks recorded scenarios against the *Lint rule* catalog. It enforces the structural subset of the narration conventions — it cannot check whether a *Step*'s text is semantically true. |
|
|
72
|
+
| **Lint rule** | One named check, carrying a surface and a default *Severity*. A `runtime` rule reads the recorded scenarios; an `ast` rule parses the step bodies' source. |
|
|
73
|
+
| **Lint finding** | One *Lint rule* firing on one subject: the rule id, the *Severity* it fired at, the subject, a *Source link* location and a message naming the offender. |
|
|
74
|
+
| **Severity** | A *Lint rule*'s level — `off`, `warn` or `error`. Only `error` fails the run, `warn` reports in the terminal summary, and an `off` rule is not evaluated at all. |
|
|
75
|
+
|
|
76
|
+
## Domain Storytelling
|
|
77
|
+
|
|
78
|
+
The Domain-Driven Design layer atop the core surface. All terms here are optional features: a test suite can use none, some, or all.
|
|
79
|
+
|
|
80
|
+
Terms follow [Domain Storytelling](https://domainstorytelling.org/quick-start-guide)'s own, where actors and work objects connected by activities form sentences.
|
|
81
|
+
|
|
82
|
+
| Term | Meaning |
|
|
83
|
+
|---|---|
|
|
84
|
+
| **Glossary** | The shared vocabulary a domain speaks in: its Ubiquitous Language. |
|
|
85
|
+
| **File glossary** | A glossary loaded from the GFM pipe tables of a Markdown file. |
|
|
86
|
+
| **Deferred term** | A term handed over before its kind is settled: what `g('foo')` and `g['foo']` on a code glossary return, and a *file glossary* lookup of a row with no declared kind. *Kind inference* settles it later. |
|
|
87
|
+
| **Term** | A glossary entry: an Actor, Work Object, Activity, or kindless term. Each carries an id (slug), a canonical name, a kind unless kindless, and an optional definition. |
|
|
88
|
+
| **Handle** | What a glossary hands back for a *term*, the same from every accessor (`g.actor(...)`, `g('foo')`, `g['Guest']`, a captured `guest = ...`). It is what steps, scenario titles and sentences interpolate, in one of four surface forms: **bare** (`room` — the canonical display), **`.l`** (`room.l` — capitalized words lowercased, acronyms kept), **`.s`** (`room.s` — the *S-form*), or **called** (`room('Deluxe Suite')` — an *instance* on an Actor or Work Object, an inflection on an *Activity*). `.l` and `.s` also apply to a called form and chain (`room.l.s` reads *rooms*). Each form renders as a *term ref*. A story hands out a **sentence handle** the same way: `book_a_room['cancel']` by name or `book_a_room[3]` by number, which `pins=` takes. |
|
|
89
|
+
| **S-form** | A term's name with the regular English -s ending, from the `.s` handle form: the plural of an Actor or Work Object (*rooms*), the third person singular of an Activity (*books*). It adds -s to the last word, -es after s, x, z, ch or sh, and turns a consonant + y into -ies, but an acronym takes a plain -s (*APIs*); anything else, such as *people* or *checks in*, needs the called form. An S-form reference, in any case, is a reference to the term itself — not an *instance* or an *inflection*. |
|
|
90
|
+
| **Actor** | A glossary term for a participant in the domain (e.g., *Guest*). |
|
|
91
|
+
| **Work Object** | A glossary term for a thing acted on (e.g., *Room*, *Booking*). |
|
|
92
|
+
| **Activity** | A glossary term for what an actor does (e.g., *book*, *confirm*), which Domain Storytelling draws as an arrow labelled with a verb. Activities accept inflections: calling `search('searches for')` records *searches for* as a surface form of the canonical *search*. |
|
|
93
|
+
| **Term ref** | An occurrence of a term inside narration or a clause. |
|
|
94
|
+
| **Instance** | A named refinement of an Actor or Work Object (e.g., `guest('Alice')` is an instance of the *Guest* actor). |
|
|
95
|
+
| **Inflection** | A surface form of an Activity term other than its canonical name or *S-form* (e.g., *searches for* as an inflection of *search*). |
|
|
96
|
+
| **Story** | A named flow modeled as a sequence of sentences. Stories are the unit of coverage. |
|
|
97
|
+
| **Sentence** | What Domain Storytelling calls a sentence: an actor, an activity and its work objects, plus connective words. One row in a story, numbered by its position and optionally named, a name that stays put when rows are inserted. Usually one clause; several when the sentence has several arrows under one number. |
|
|
98
|
+
| **Clause part** | A piece of a clause's prose: a *term ref*, or a bare clause word. A bare clause word — a node label or edge connective — carries no kind or id, is never classified by inference, and never reaches the glossary. That last is what separates it from a kindless term, which has an id and is tracked. |
|
|
99
|
+
| **Clause** | One linear walk through a sentence's arrows, a node/edge alternation starting actor → verb → noun. A sentence with several arrow chains under one number, such as an actor handing a work object to two recipients, takes one clause per chain. Domain Storytelling names no such unit. |
|
|
100
|
+
| **Slot** | A position role in a clause, from its node/edge alternation: position 0 is the actor slot, odd positions are verb slots, and even positions ≥ 2 are noun slots. |
|
|
101
|
+
| **Scenario↔sentence binding** | The link between a scenario (or step) and story sentences. `@scenario(stories=...)` names the stories a scenario is narration-matched against; a *pin* (`pins=` on `@scenario` or on `given`/`when`/`then`) binds sentences explicitly, in any story, whether `stories=` names it or not. |
|
|
102
|
+
| **Pin** | What a *sentence handle* passed to `pins=` is recorded as, the way a term handle in narration is recorded as a *term ref*: a reference to a story and a sentence number. A pin binds explicitly and replaces narration matching — a step pin for that step, a scenario pin (`@scenario(pins=...)`) for every step of the scenario, which then covers its own pins plus its steps'. `pins=[]` pins nothing but still opts out of narration matching. A pin reaches under-anchored sentences too. |
|
|
103
|
+
| **Coverage** | The "did this scenario touch that sentence" relation. A sentence is covered when the set of terms it references is a subset of the terms a single step references — matching is per step, not against the union across steps, and on terms, not surface forms: an *instance* or *inflection* counts as its term. A *pin* covers its sentences directly instead, regardless of narration or term count. |
|
|
104
|
+
| **Kind inference** | The pass that assigns each undeclared term a kind from the *slot* positions it occupies across all story sentences; declared kinds are verified against observed positions instead. A term used in incompatible slots (or conflicting with its declared kind) raises. A term never referenced by any sentence stays *kindless*. |
|
|
105
|
+
| **Kindless** | A term with no kind, because *kind inference* finds no story *slot* to infer from (a term used only in t-string steps, never in a sentence). |
|
|
106
|
+
| **Undefined** | A term with no definition. Orthogonal to *kindless*. |
|
|
107
|
+
|
|
108
|
+
## Collaboration
|
|
109
|
+
|
|
110
|
+
The people and machines collaborating on a pytest-given test suite — the cast of the project's own domain story (defined in `tests/ubiquitous_language.py`).
|
|
111
|
+
|
|
112
|
+
| Term | Meaning |
|
|
113
|
+
|---|---|
|
|
114
|
+
| **Developer** | Person who writes the application code and — together with the *Agent* — the scenarios; curates the glossary with the *Domain Expert*. |
|
|
115
|
+
| **Domain Expert** | Person who owns the domain knowledge and the ubiquitous language; source of domain stories and reviewer of scenarios and reports. A stakeholder in the broad sense. |
|
|
116
|
+
| **Agent** | AI coding agent that authors and maintains scenarios alongside the *Developer*, guided by the pytest-given skills. |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: pytest-given
|
|
3
|
-
Version: 0.5.
|
|
3
|
+
Version: 0.5.2
|
|
4
4
|
Summary: A pytest plugin that generates interactive HTML reports from Given/When/Then annotated tests.
|
|
5
5
|
Project-URL: Homepage, https://github.com/nwilbert/pytest-given
|
|
6
6
|
Project-URL: Repository, https://github.com/nwilbert/pytest-given
|
|
@@ -43,6 +43,15 @@ Inspired by [JGiven](https://jgiven.org/) (Java).
|
|
|
43
43
|
|
|
44
44
|
**Documentation: <https://nwilbert.github.io/pytest-given/latest/>**
|
|
45
45
|
|
|
46
|
+
<p align="center">
|
|
47
|
+
<a href="https://nwilbert.github.io/pytest-given/latest/examples/hotel-booking.html#scenario=examples/hotel-booking/test_hotel_booking.py::test_cancel_booking">
|
|
48
|
+
<picture>
|
|
49
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/site/assets/report-screenshot-dark.png">
|
|
50
|
+
<img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/site/assets/report-screenshot-light.png" alt="The HTML report of the Hotel booking example: a sidebar of status filters and browse options beside a list of scenarios, one expanded to its Given, When and Then steps with glossary terms underlined." width="840">
|
|
51
|
+
</picture>
|
|
52
|
+
</a>
|
|
53
|
+
</p>
|
|
54
|
+
|
|
46
55
|
Live examples:
|
|
47
56
|
- **[Coffeeshop](https://nwilbert.github.io/pytest-given/latest/examples/coffeeshop.html)**: a tour of the core features.
|
|
48
57
|
- **[Hotel booking](https://nwilbert.github.io/pytest-given/latest/examples/hotel-booking.html)**: a glossary and domain stories, with story coverage.
|
|
@@ -73,16 +82,16 @@ from pytest_given import attach, given, scenario, then, when
|
|
|
73
82
|
|
|
74
83
|
|
|
75
84
|
@pytest.fixture
|
|
76
|
-
@given('a coffee machine')
|
|
85
|
+
@given('a coffee machine with 10 coffees')
|
|
77
86
|
def machine():
|
|
78
87
|
return {'coffees': 10, 'price': 2}
|
|
79
88
|
|
|
80
89
|
|
|
81
|
-
@scenario('
|
|
90
|
+
@scenario('Buying a coffee takes one from the machine', tags=['checkout'])
|
|
82
91
|
def test_buy_coffee(machine):
|
|
83
|
-
with when('I
|
|
92
|
+
with when('I buy a coffee'):
|
|
84
93
|
machine['coffees'] -= 1
|
|
85
|
-
with then('
|
|
94
|
+
with then('the machine has 9 coffees left'):
|
|
86
95
|
assert machine['coffees'] == 9
|
|
87
96
|
attach('Machine state', machine)
|
|
88
97
|
```
|
|
@@ -95,9 +104,13 @@ pytest --given-html
|
|
|
95
104
|
|
|
96
105
|
This produces `given-report/report.html` — one file you can open directly in a browser.
|
|
97
106
|
|
|
107
|
+
The Coffeeshop example's report shows this same scenario:
|
|
108
|
+
|
|
109
|
+
✅ [Buying a coffee takes one from the machine](https://nwilbert.github.io/pytest-given/latest/examples/coffeeshop.html#scenario=examples/coffeeshop/test_coffeeshop.py::test_buy_coffee)
|
|
110
|
+
|
|
98
111
|
## Why pytest-given?
|
|
99
112
|
|
|
100
|
-
Classical BDD tools (Cucumber, behave, pytest-bdd) center on Gherkin, a natural-language DSL: stakeholders write the tests, and engineers maintain the glue code behind each step.
|
|
113
|
+
Classical BDD tools (Cucumber, behave, pytest-bdd) center on Gherkin, a natural-language DSL: stakeholders write the tests, and engineers maintain the glue code behind each step. The [BDD page](https://nwilbert.github.io/pytest-given/latest/bdd/) writes the quick start's scenario that way, for comparison.
|
|
101
114
|
|
|
102
115
|
pytest-given works the other way round: **engineers or their agents write normal tests, and pytest-given turns them into readable documentation.** Stakeholders and domain experts can follow the HTML report without ever opening the test suite. Engineers get a view of the system's behavior that is easier to scan than test code, browsable by tag, glossary term, or module. The approach is the one [JGiven](https://jgiven.org/) pioneered for Java, brought to pytest.
|
|
103
116
|
|
|
@@ -107,10 +120,10 @@ pytest-given works the other way round: **engineers or their agents write normal
|
|
|
107
120
|
|
|
108
121
|
### Written by agents, reviewed by people
|
|
109
122
|
|
|
110
|
-
|
|
123
|
+
Most tests are no longer written by hand. A person describes the behavior they want, in a prompt or a spec, and an AI agent writes the tests along with the code. People review the narrated report first, and the test code behind it where it matters. The diagram shows this loop, and [Working with AI agents](https://nwilbert.github.io/pytest-given/latest/ai-agents/) explains how to set it up.
|
|
111
124
|
|
|
112
125
|
<p align="center">
|
|
113
|
-
<img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers
|
|
126
|
+
<img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report, which domain experts validate. Developers review all the artifacts, feeding back to the agents." width="640">
|
|
114
127
|
</p>
|
|
115
128
|
|
|
116
129
|
### Glossary and Domain Storytelling
|
|
@@ -119,7 +132,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
|
|
|
119
132
|
|
|
120
133
|
### Documents that stay true
|
|
121
134
|
|
|
122
|
-
A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and stories as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run
|
|
135
|
+
A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and stories as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run. `pytest-given citations check` in CI fails when a cited scenario stops passing or disappears, so the document can't quietly claim what the code no longer does.
|
|
123
136
|
|
|
124
137
|
## Features
|
|
125
138
|
|
|
@@ -128,6 +141,7 @@ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/lat
|
|
|
128
141
|
- **[Parametrized scenarios](https://nwilbert.github.io/pytest-given/latest/guide/parametrized/)**: one narrated tree plus a parameter table per case, or one scenario per case on request.
|
|
129
142
|
- **[Glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/)**: your domain's terms, declared in code or loaded from a `GLOSSARY.md`, rendered as highlighted term refs in the narration.
|
|
130
143
|
- **[Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/)**: Domain Stories as sequences of sentences, and per-sentence coverage in the report.
|
|
144
|
+
- **Reports**: a self-contained [HTML report](https://nwilbert.github.io/pytest-given/latest/html-report/) to browse and share, and a [Markdown report](https://nwilbert.github.io/pytest-given/latest/markdown-report/) for diffs, reviews and agents.
|
|
131
145
|
- **[Narration lint](https://nwilbert.github.io/pytest-given/latest/configuration/narration-lint/)**: structural checks that a step's text is honest about its body: empty steps, a `then` that checks nothing, a missing phase.
|
|
132
146
|
- **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags and stories, led by their status and checked against the latest run.
|
|
133
147
|
- **[Agent skills](https://nwilbert.github.io/pytest-given/latest/ai-agents/)**: bundled Agent Skills for authoring, navigating and reviewing narrated tests, installable with one command.
|
|
@@ -136,4 +150,4 @@ The full reference — pytest options, source links, the standalone CLI — is o
|
|
|
136
150
|
|
|
137
151
|
## License
|
|
138
152
|
|
|
139
|
-
[MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT
|
|
153
|
+
[MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT, with its notice in [THIRD-PARTY-LICENSES](https://github.com/nwilbert/pytest-given/blob/main/THIRD-PARTY-LICENSES).
|
|
@@ -12,6 +12,15 @@ Inspired by [JGiven](https://jgiven.org/) (Java).
|
|
|
12
12
|
|
|
13
13
|
**Documentation: <https://nwilbert.github.io/pytest-given/latest/>**
|
|
14
14
|
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="https://nwilbert.github.io/pytest-given/latest/examples/hotel-booking.html#scenario=examples/hotel-booking/test_hotel_booking.py::test_cancel_booking">
|
|
17
|
+
<picture>
|
|
18
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/site/assets/report-screenshot-dark.png">
|
|
19
|
+
<img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/site/assets/report-screenshot-light.png" alt="The HTML report of the Hotel booking example: a sidebar of status filters and browse options beside a list of scenarios, one expanded to its Given, When and Then steps with glossary terms underlined." width="840">
|
|
20
|
+
</picture>
|
|
21
|
+
</a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
15
24
|
Live examples:
|
|
16
25
|
- **[Coffeeshop](https://nwilbert.github.io/pytest-given/latest/examples/coffeeshop.html)**: a tour of the core features.
|
|
17
26
|
- **[Hotel booking](https://nwilbert.github.io/pytest-given/latest/examples/hotel-booking.html)**: a glossary and domain stories, with story coverage.
|
|
@@ -42,16 +51,16 @@ from pytest_given import attach, given, scenario, then, when
|
|
|
42
51
|
|
|
43
52
|
|
|
44
53
|
@pytest.fixture
|
|
45
|
-
@given('a coffee machine')
|
|
54
|
+
@given('a coffee machine with 10 coffees')
|
|
46
55
|
def machine():
|
|
47
56
|
return {'coffees': 10, 'price': 2}
|
|
48
57
|
|
|
49
58
|
|
|
50
|
-
@scenario('
|
|
59
|
+
@scenario('Buying a coffee takes one from the machine', tags=['checkout'])
|
|
51
60
|
def test_buy_coffee(machine):
|
|
52
|
-
with when('I
|
|
61
|
+
with when('I buy a coffee'):
|
|
53
62
|
machine['coffees'] -= 1
|
|
54
|
-
with then('
|
|
63
|
+
with then('the machine has 9 coffees left'):
|
|
55
64
|
assert machine['coffees'] == 9
|
|
56
65
|
attach('Machine state', machine)
|
|
57
66
|
```
|
|
@@ -64,9 +73,13 @@ pytest --given-html
|
|
|
64
73
|
|
|
65
74
|
This produces `given-report/report.html` — one file you can open directly in a browser.
|
|
66
75
|
|
|
76
|
+
The Coffeeshop example's report shows this same scenario:
|
|
77
|
+
|
|
78
|
+
✅ [Buying a coffee takes one from the machine](https://nwilbert.github.io/pytest-given/latest/examples/coffeeshop.html#scenario=examples/coffeeshop/test_coffeeshop.py::test_buy_coffee)
|
|
79
|
+
|
|
67
80
|
## Why pytest-given?
|
|
68
81
|
|
|
69
|
-
Classical BDD tools (Cucumber, behave, pytest-bdd) center on Gherkin, a natural-language DSL: stakeholders write the tests, and engineers maintain the glue code behind each step.
|
|
82
|
+
Classical BDD tools (Cucumber, behave, pytest-bdd) center on Gherkin, a natural-language DSL: stakeholders write the tests, and engineers maintain the glue code behind each step. The [BDD page](https://nwilbert.github.io/pytest-given/latest/bdd/) writes the quick start's scenario that way, for comparison.
|
|
70
83
|
|
|
71
84
|
pytest-given works the other way round: **engineers or their agents write normal tests, and pytest-given turns them into readable documentation.** Stakeholders and domain experts can follow the HTML report without ever opening the test suite. Engineers get a view of the system's behavior that is easier to scan than test code, browsable by tag, glossary term, or module. The approach is the one [JGiven](https://jgiven.org/) pioneered for Java, brought to pytest.
|
|
72
85
|
|
|
@@ -76,10 +89,10 @@ pytest-given works the other way round: **engineers or their agents write normal
|
|
|
76
89
|
|
|
77
90
|
### Written by agents, reviewed by people
|
|
78
91
|
|
|
79
|
-
|
|
92
|
+
Most tests are no longer written by hand. A person describes the behavior they want, in a prompt or a spec, and an AI agent writes the tests along with the code. People review the narrated report first, and the test code behind it where it matters. The diagram shows this loop, and [Working with AI agents](https://nwilbert.github.io/pytest-given/latest/ai-agents/) explains how to set it up.
|
|
80
93
|
|
|
81
94
|
<p align="center">
|
|
82
|
-
<img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers
|
|
95
|
+
<img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report, which domain experts validate. Developers review all the artifacts, feeding back to the agents." width="640">
|
|
83
96
|
</p>
|
|
84
97
|
|
|
85
98
|
### Glossary and Domain Storytelling
|
|
@@ -88,7 +101,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
|
|
|
88
101
|
|
|
89
102
|
### Documents that stay true
|
|
90
103
|
|
|
91
|
-
A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and stories as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run
|
|
104
|
+
A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and stories as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run. `pytest-given citations check` in CI fails when a cited scenario stops passing or disappears, so the document can't quietly claim what the code no longer does.
|
|
92
105
|
|
|
93
106
|
## Features
|
|
94
107
|
|
|
@@ -97,6 +110,7 @@ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/lat
|
|
|
97
110
|
- **[Parametrized scenarios](https://nwilbert.github.io/pytest-given/latest/guide/parametrized/)**: one narrated tree plus a parameter table per case, or one scenario per case on request.
|
|
98
111
|
- **[Glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/)**: your domain's terms, declared in code or loaded from a `GLOSSARY.md`, rendered as highlighted term refs in the narration.
|
|
99
112
|
- **[Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/)**: Domain Stories as sequences of sentences, and per-sentence coverage in the report.
|
|
113
|
+
- **Reports**: a self-contained [HTML report](https://nwilbert.github.io/pytest-given/latest/html-report/) to browse and share, and a [Markdown report](https://nwilbert.github.io/pytest-given/latest/markdown-report/) for diffs, reviews and agents.
|
|
100
114
|
- **[Narration lint](https://nwilbert.github.io/pytest-given/latest/configuration/narration-lint/)**: structural checks that a step's text is honest about its body: empty steps, a `then` that checks nothing, a missing phase.
|
|
101
115
|
- **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags and stories, led by their status and checked against the latest run.
|
|
102
116
|
- **[Agent skills](https://nwilbert.github.io/pytest-given/latest/ai-agents/)**: bundled Agent Skills for authoring, navigating and reviewing narrated tests, installable with one command.
|
|
@@ -105,4 +119,4 @@ The full reference — pytest options, source links, the standalone CLI — is o
|
|
|
105
119
|
|
|
106
120
|
## License
|
|
107
121
|
|
|
108
|
-
[MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT
|
|
122
|
+
[MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT, with its notice in [THIRD-PARTY-LICENSES](https://github.com/nwilbert/pytest-given/blob/main/THIRD-PARTY-LICENSES).
|
|
@@ -12,7 +12,7 @@ Each rule has a default severity. A `warn` lint finding is printed in the termin
|
|
|
12
12
|
|------|---------|---------|
|
|
13
13
|
| `empty-step` | `error` | A step whose body does nothing: it only contains constants or `pass`, or, for `when` and `then`, only an `attach(...)` call. |
|
|
14
14
|
| `then-without-check` | `error` | A `then` without an `assert` or a checking call. Checking calls are calls whose name starts with `assert`, and `pytest.raises`, `pytest.warns` and `pytest.fail`. Nothing else counts, not even `pytest.approx`. |
|
|
15
|
-
| `conditional-check` | `warn` | A `then` whose checks all sit under an `if`, a loop, a `match` or an `except`, so a run can pass it without checking anything. An `if` that calls `pytest.fail` counts as a check, and so
|
|
15
|
+
| `conditional-check` | `warn` | A `then` whose checks all sit under an `if`, a loop, a `match` or an `except`, so a run can pass it without checking anything. An `if` that calls `pytest.fail` counts as a check, and so do an `if`/`else` that checks on every branch and a loop over a literal such as `(a, b)`. |
|
|
16
16
|
| `missing-phase` | `warn` | A passed scenario that is missing one of the phases Given, When or Then. `@given` fixtures and `Annotated[..., given(...)]` parameters count as `given` steps. A parametrized scenario is checked once, not once per case. |
|
|
17
17
|
| `check-outside-then` | `warn` | An `assert` inside a `given` or `when`. The `when` part of a `when_then` is allowed to contain one. |
|
|
18
18
|
| `action-in-then` | `warn` | A scenario where no `when` performs an action, and a `then` performs it inside its assertion instead. |
|
|
@@ -24,6 +24,8 @@ Each rule has a default severity. A `warn` lint finding is printed in the termin
|
|
|
24
24
|
|
|
25
25
|
Change a rule's severity with `given_lint_rules`. Skip lint findings for specific tests with `given_lint_ignore`: each entry is a node-id pattern (with `*` wildcards), optionally limited to one rule with a `rule-id:` prefix.
|
|
26
26
|
|
|
27
|
+
Brackets after the `::` name a parametrize case, not a glob character class, so `tests/unit/test_math.py::test_add[water]` matches only that case.
|
|
28
|
+
|
|
27
29
|
```toml
|
|
28
30
|
[tool.pytest]
|
|
29
31
|
given_lint = true
|
|
@@ -94,7 +94,7 @@ def mypy(session: nox.Session) -> None:
|
|
|
94
94
|
|
|
95
95
|
@nox.session
|
|
96
96
|
def test(session: nox.Session) -> None:
|
|
97
|
-
_sync(session, include_project=True)
|
|
97
|
+
_sync(session, 'test', include_project=True)
|
|
98
98
|
session.run('pytest')
|
|
99
99
|
|
|
100
100
|
|
|
@@ -110,7 +110,7 @@ def compat(session: nox.Session, pytest_version: str) -> None:
|
|
|
110
110
|
only moves on `uv lock --upgrade`. pytest 9.0 predates the `max_warnings`
|
|
111
111
|
option, so there an unknown-option warning replaces the warnings gate.
|
|
112
112
|
"""
|
|
113
|
-
_sync(session, include_project=True)
|
|
113
|
+
_sync(session, 'test', include_project=True)
|
|
114
114
|
if pytest_version == 'latest':
|
|
115
115
|
installs = [
|
|
116
116
|
'pytest',
|
|
@@ -128,7 +128,7 @@ def compat(session: nox.Session, pytest_version: str) -> None:
|
|
|
128
128
|
|
|
129
129
|
@nox.session
|
|
130
130
|
def coverage(session: nox.Session) -> None:
|
|
131
|
-
_sync(session, 'coverage', include_project=True)
|
|
131
|
+
_sync(session, 'coverage', 'test', include_project=True)
|
|
132
132
|
session.run(
|
|
133
133
|
'coverage',
|
|
134
134
|
'run',
|
|
@@ -410,15 +410,16 @@ _EXAMPLES = (
|
|
|
410
410
|
_EXAMPLE_REPORTS = (*(example.slug for example in _EXAMPLES), 'self-report')
|
|
411
411
|
# The reports a document cites: `pytest-given citations` refuses one that no
|
|
412
412
|
# document links, so a report the docs only embed stays out.
|
|
413
|
-
_CITED_REPORTS = ('hotel-booking', 'self-report')
|
|
413
|
+
_CITED_REPORTS = ('coffeeshop', 'hotel-booking', 'self-report')
|
|
414
414
|
|
|
415
415
|
|
|
416
416
|
def _run_citations(
|
|
417
417
|
session: nox.Session, verb: Literal['check', 'update'], slug: str
|
|
418
418
|
) -> None:
|
|
419
419
|
"""Hold the documents citing one report to it: the site's pages, which link
|
|
420
|
-
it relatively,
|
|
421
|
-
one
|
|
420
|
+
it relatively, for the self-report the specs, which link the hosted one,
|
|
421
|
+
and for coffeeshop the README, which links the `/latest/` one like its
|
|
422
|
+
other links into the site."""
|
|
422
423
|
report = f'examples/{slug}/{slug}-data.json'
|
|
423
424
|
session.run(
|
|
424
425
|
'pytest-given',
|
|
@@ -434,6 +435,16 @@ def _run_citations(
|
|
|
434
435
|
session.run(
|
|
435
436
|
'pytest-given', 'citations', verb, 'docs/specs/', '--report', report
|
|
436
437
|
)
|
|
438
|
+
if slug == 'coffeeshop':
|
|
439
|
+
session.run(
|
|
440
|
+
'pytest-given',
|
|
441
|
+
'citations',
|
|
442
|
+
verb,
|
|
443
|
+
'README.md',
|
|
444
|
+
'--report',
|
|
445
|
+
report,
|
|
446
|
+
f'--report-url={_examples_url("latest")}/{slug}.html',
|
|
447
|
+
)
|
|
437
448
|
|
|
438
449
|
|
|
439
450
|
@nox.session
|
|
@@ -451,7 +462,7 @@ def reports_current(session: nox.Session) -> None:
|
|
|
451
462
|
against unnoticed: regenerate every report, then diff the tracked Markdown —
|
|
452
463
|
the reports' `.md` and the documents whose citations that updated. Markdown
|
|
453
464
|
alone, as it carries no commit SHA, timestamp or duration."""
|
|
454
|
-
_sync(session, include_project=True)
|
|
465
|
+
_sync(session, 'test', include_project=True)
|
|
455
466
|
_regenerate_examples(session)
|
|
456
467
|
_regenerate_self_report(session)
|
|
457
468
|
session.run('git', 'diff', '--exit-code', '--', '*.md', external=True)
|
|
@@ -504,6 +515,20 @@ def _regenerate_examples(session: nox.Session) -> None:
|
|
|
504
515
|
)
|
|
505
516
|
|
|
506
517
|
|
|
518
|
+
@nox.session
|
|
519
|
+
def bdd_example(session: nox.Session) -> None:
|
|
520
|
+
"""Run the pytest-bdd contrast, which has no report. A session of its own, so
|
|
521
|
+
pytest-bdd's plugin joins no other run."""
|
|
522
|
+
_sync(session, 'bdd', include_project=True)
|
|
523
|
+
session.run(
|
|
524
|
+
'pytest',
|
|
525
|
+
'examples/pytest-bdd',
|
|
526
|
+
'--gherkin-terminal-reporter',
|
|
527
|
+
'-vv',
|
|
528
|
+
'--no-header',
|
|
529
|
+
)
|
|
530
|
+
|
|
531
|
+
|
|
507
532
|
_DOCS_SITE = Path('docs/site')
|
|
508
533
|
_REPORT_TEMPLATES = Path('src/pytest_given/report/templates')
|
|
509
534
|
_REPORT_FONTS = _REPORT_TEMPLATES / 'fonts'
|
|
@@ -674,7 +699,7 @@ def self_report(session: nox.Session) -> None:
|
|
|
674
699
|
tests. The @scenario-decorated unit tests narrate the plugin's behavior in
|
|
675
700
|
the vocabulary of GLOSSARY.md (loaded as a FileGlossary in tests/conftest.py).
|
|
676
701
|
"""
|
|
677
|
-
_sync(session, include_project=True)
|
|
702
|
+
_sync(session, 'test', include_project=True)
|
|
678
703
|
_regenerate_self_report(session)
|
|
679
704
|
|
|
680
705
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "pytest-given"
|
|
3
|
-
version = "0.5.
|
|
3
|
+
version = "0.5.2"
|
|
4
4
|
description = "A pytest plugin that generates interactive HTML reports from Given/When/Then annotated tests."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
# PEP 639: an SPDX expression plus the files it refers to. Deliberately no
|
|
@@ -57,7 +57,11 @@ lint = ["ruff>=0.15.13"]
|
|
|
57
57
|
nox = ["nox>=2026.4.10"]
|
|
58
58
|
typecheck = ["mypy>=2.1.0", { include-group = "nox" }]
|
|
59
59
|
coverage = ["coverage>=7.14.0"]
|
|
60
|
+
# The suite's own: the xdist refusal runs inner pytester runs with `-n`.
|
|
61
|
+
test = ["pytest-xdist>=3.8.0"]
|
|
60
62
|
audit = ["pip-audit>=2.10.0"]
|
|
63
|
+
# only for the example:
|
|
64
|
+
bdd = ["pytest-bdd>=9.0.1"]
|
|
61
65
|
build = ["library-skills>=0.0.19", { include-group = "nox" }]
|
|
62
66
|
docs = [
|
|
63
67
|
"zensical>=0.0.61",
|
|
@@ -73,6 +77,7 @@ dev = [
|
|
|
73
77
|
{ include-group = "audit" },
|
|
74
78
|
{ include-group = "build" },
|
|
75
79
|
{ include-group = "docs" },
|
|
80
|
+
{ include-group = "test" },
|
|
76
81
|
]
|
|
77
82
|
|
|
78
83
|
[build-system]
|
|
@@ -13,7 +13,7 @@ Setup (installation, report flags, source links, lint configuration) is in the p
|
|
|
13
13
|
|
|
14
14
|
## Core
|
|
15
15
|
|
|
16
|
-
- **`@scenario(title, tags=None, *, stories=None, pins=None, group_parametrized=True)`** marks a test for the report. A test only appears in the report with it. `title` is a plain string, a `Template` (for parametrized titles), or a t-string whose interpolations are all glossary handles; those render as term refs in the title. `stories=` takes one or more stories whose sentences the steps are matched against. `pins=` takes sentence handles (`the_story['name']`, `the_story[3]`). The scenario then covers those sentences plus its steps' pins, with no narration matching. `pins=[]` keeps only the steps' pins. Bare numbers and names raise an error. The
|
|
16
|
+
- **`@scenario(title, tags=None, *, stories=None, pins=None, group_parametrized=True)`** marks a test for the report. A test only appears in the report with it. `title` is a plain string, a `Template` (for parametrized titles), or a t-string whose interpolations are all glossary handles; those render as term refs in the title. `stories=` takes one or more stories whose sentences the steps are matched against. `pins=` takes sentence handles (`the_story['name']`, `the_story[3]`). The scenario then covers those sentences plus its steps' pins, with no narration matching. `pins=[]` keeps only the steps' pins. Bare numbers and names raise an error. The plugin marks every scenario test, each parametrized case included, with the registered `pytest_given` marker, so `-m pytest_given` selects the scenarios and `-m "not pytest_given"` the plain tests. Don't apply the marker by hand: a plain test carrying it is selected but records nothing.
|
|
17
17
|
- **`given(text, *, pins=None)`, `when(text, *, pins=None)` and `then(text, *, pins=None)`** each have several uses. `pins=` binds the step to story sentences instead of narration matching, and `pins=[]` turns matching off for the step (see [stories.md](stories.md)).
|
|
18
18
|
- **As a context manager** in a test body: `with when('…'): result = sut(x)`. Steps can nest within one phase (a `when` inside a `when`). Nesting a step of another phase raises `PytestGivenError`. That includes calling a decorated helper of another phase inside an open step.
|
|
19
19
|
- **As a fixture decorator**, with `@given` only. `@pytest.fixture` must be **outermost** (above `@given('…')`), and the label must be a plain string. Generator fixtures work, at any scope. A step or attachment after `yield` raises an error.
|
|
@@ -34,16 +34,14 @@ Setup (installation, report flags, source links, lint configuration) is in the p
|
|
|
34
34
|
Hard rules (each raises `PytestGivenError`):
|
|
35
35
|
|
|
36
36
|
1. **`Template` accepts bare identifiers only:** `{name}`, `{name:spec}`, `{name!conv}`. No attribute access, no indexing, no expressions. To work around this, parametrize by the attribute, or move the step into the test body as a t-string.
|
|
37
|
-
2.
|
|
37
|
+
2. **Each form works only where the table puts it.** A `Template` in a test-body step is rejected: use a t-string. A t-string is rejected on a fixture or helper decorator, in `Annotated[..., given(...)]`, and in a title that interpolates a value: use a `Template` or a plain string. One title can't combine a term ref with a per-case value.
|
|
38
38
|
|
|
39
39
|
## Parametrized tests
|
|
40
40
|
|
|
41
41
|
- All cases are grouped into **one scenario with a parameter table**. T-string interpolations that name a parametrize column render as colored values in each row.
|
|
42
42
|
- **The steps of the first passing case are the template for every row**, but only their *structure*. A narrated value or an attachment content that varies between cases becomes its own column in the parameter table. When an authoring form can't be shown honestly against that template, pytest-given raises `PytestGivenError` instead of writing a wrong report, and each message names its fix. The habits that avoid these errors are in [parameter-tables.md](parameter-tables.md).
|
|
43
43
|
- **When the narration really differs per case**, use `@scenario(..., group_parametrized=False)`. It declines the merge and records one scenario per case, titled `<title> [<parametrize id>]`, with any `Template` placeholders filled in per case. There is no parameter table. On a test that isn't parametrized, it raises an error at collection.
|
|
44
|
-
-
|
|
45
|
-
- To show a parametrize value as a `given`, put `Annotated[int, given(Template('a {cup_size} ml cup'))]` on the parameter.
|
|
46
|
-
- **Stacking:** `@scenario(...)` and `@pytest.mark.parametrize(...)` work in either order. `@scenario` returns the function unwrapped, so neither hides the other's marks.
|
|
44
|
+
- **Stacking:** `@scenario(...)` and `@pytest.mark.parametrize(...)` work in either order. `@scenario` returns the function unwrapped, so it keeps its own signature and neither hides the other's marks.
|
|
47
45
|
|
|
48
46
|
## Glossary
|
|
49
47
|
|
|
@@ -65,7 +65,7 @@ Every handle offers the same four forms, whether you captured it (`guest = g.act
|
|
|
65
65
|
|
|
66
66
|
## Naming terms
|
|
67
67
|
|
|
68
|
-
- **Term names are natural language, not class names.** Name the concept the way a person would say it (`File glossary`, `Clause part`)
|
|
68
|
+
- **Term names are natural language, not class names.** Name the concept the way a person would say it (`File glossary`, `Clause part`). A one-word term may match its class name only when the class name is already the natural word. A multi-word CamelCase name never is.
|
|
69
69
|
- **Renaming or removing a term is a code change, not just a doc edit.** A term's slug is its lookup key: the name in lowercase, with each run of non-alphanumeric characters replaced by `-`. So `File glossary` and `FileGlossary` are *different* keys, and a rename breaks every `g['Old name']` reference. Search for the old name, update the references, and re-render the reports. Rename the implementation too: if the code keeps the old name, you create exactly the language drift the vocabulary rule forbids (see [scenarios.md](scenarios.md)). Adding a term is always safe.
|
|
70
70
|
|
|
71
71
|
## Kinds
|
|
@@ -81,5 +81,5 @@ Each term is an actor, an activity or a work object. A term gets its kind in one
|
|
|
81
81
|
|
|
82
82
|
- **Don't dilute the glossary.** A term deserves its row when the team really uses the word: someone would look it up, and its meaning is specific to the domain. Never add a term just to get more term refs or to satisfy the lint, and never without asking the user. A generic word stays a bare string. When a row doesn't deserve its place, delete it instead of inventing a reference to it.
|
|
83
83
|
- **Watch the size. A glossary is read as a whole, never in samples.** Reading every term in one pass is how you notice a near-duplicate before you add it. A glossary too long to read comfortably in one sitting probably covers more than one bounded context. Raise that with the user as a design question: one glossary per context means splitting the suite too.
|
|
84
|
-
- **A
|
|
84
|
+
- **A glossary names concepts and avoids implementation details.** Which component handles a term, where a screen or report shows it and how the code stores it belong in the docs. A behavior that does define the term, such as "must be unique" or "produces no step", makes a claim and is part of the spec. Back it with a scenario, and update the row when the behavior changes.
|
|
85
85
|
- **A term that nothing references is normal.** A glossary documents the domain, not the suite's coverage, which is why `dead-term` is off by default. If you turn it on, treat a lint finding as a reason to look at the term. If an undecorated test already shows its behavior, decorate that test. If a step uses the term as plain text, add the term ref.
|
|
@@ -6,7 +6,7 @@ The narration lint enforces the structural part of the rules in [scenarios.md](s
|
|
|
6
6
|
|---|---|---|
|
|
7
7
|
| `empty-step` | error | A step whose body does nothing: only constants or `pass`, or, for `when`/`then`, only an `attach(...)` call. |
|
|
8
8
|
| `then-without-check` | error | A `then` with no `assert` statement and no checking call. A checking call is one whose name starts with `assert` (`assert_totals(order)`, `result.assert_outcomes(...)`), or `pytest.raises` / `pytest.warns` / `pytest.fail`. Nothing else counts, not even `pytest.approx`. |
|
|
9
|
-
| `conditional-check` | warn | A `then` whose checks all sit under an `if`, a loop, a `match` or an `except`, so a run can pass it having checked nothing. An `if` that calls `pytest.fail` counts as a check, and so
|
|
9
|
+
| `conditional-check` | warn | A `then` whose checks all sit under an `if`, a loop, a `match` or an `except`, so a run can pass it having checked nothing. An `if` that calls `pytest.fail` counts as a check, and so do an `if`/`else` that checks on every branch and a loop over a literal such as `(a, b)`. Assert the condition itself (`assert 'index' not in entry`), or split the cases into rows. |
|
|
10
10
|
| `missing-phase` | warn | A passed scenario that doesn't cover all three phases. Fixture `@given`s and `Annotated[..., given(...)]` parameters count. |
|
|
11
11
|
| `check-outside-then` | warn | An `assert` inside a `given` or `when`. The `when` half of a `when_then` pair is exempt. |
|
|
12
12
|
| `action-in-then` | warn | No `when` performs an action, and a `then` folds the action into its assertion. |
|