pytest-given 0.5.0__tar.gz → 0.5.1__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.1}/CHANGELOG.md +34 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/GLOSSARY.md +1 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/PKG-INFO +15 -10
- {pytest_given-0.5.0 → pytest_given-0.5.1}/README.md +14 -9
- {pytest_given-0.5.0 → pytest_given-0.5.1}/docs/site/configuration/narration-lint.md +3 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/noxfile.py +33 -8
- {pytest_given-0.5.0 → pytest_given-0.5.1}/pyproject.toml +8 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md +3 -5
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-authoring/references/lint.md +1 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-authoring/references/parameter-tables.md +1 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md +3 -8
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-authoring/references/stories.md +1 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-citing/SKILL.md +9 -5
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md +9 -3
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-navigating/references/report-json.md +2 -8
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-reviewing/SKILL.md +18 -14
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/completeness.md +7 -13
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/process_state.py +5 -4
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/steps.py +10 -5
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/template.py +11 -3
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/traceback.py +1 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/citations/check.py +20 -2
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/cli/__init__.py +2 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/cli/citations.py +6 -2
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/cli/report.py +11 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/cli/skills.py +21 -7
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/grouping/checks.py +47 -19
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/grouping/context.py +3 -4
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/grouping/group.py +16 -9
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/lint/ast_rules.py +21 -11
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/lint/config.py +9 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/markdown/blocks.py +28 -6
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/__init__.py +2 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/schema.py +12 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/serde.py +10 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/plugin/options.py +27 -13
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/plugin/runtest.py +29 -4
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/plugin/session.py +78 -14
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/plugin/state.py +15 -3
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/__init__.py +4 -0
- pytest_given-0.5.1/src/pytest_given/report/console.py +12 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/sinks.py +19 -13
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/slugs.py +23 -7
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/source_link.py +20 -1
- pytest_given-0.5.1/src/pytest_given/report/staged_write.py +41 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/templates/_macros.html.j2 +24 -13
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/templates/styles.css +9 -2
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/test_cli.py +50 -3
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/test_cli_citations.py +27 -2
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/test_plugin.py +282 -12
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/test_skills_cli.py +75 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_step_descriptor.py +21 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_template.py +5 -2
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_traceback_parser.py +1 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/citations/test_check.py +59 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/lint/test_ast_rules.py +37 -1
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/lint/test_config.py +29 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/markdown/test_blocks.py +21 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/model/test_serde.py +17 -0
- pytest_given-0.5.1/tests/unit/report/app_data.py +23 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_html_renderer.py +726 -1190
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_sinks.py +47 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_slugs.py +21 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_source_link.py +30 -0
- pytest_given-0.5.1/tests/unit/report/test_staged_write.py +22 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/test_grouping.py +152 -7
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/test_plugin.py +5 -1
- pytest_given-0.5.1/tests/unit/test_quickstart.py +35 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/uv.lock +246 -124
- pytest_given-0.5.0/src/pytest_given/.agents/skills/pytest-given-reviewing/references/citations.md +0 -10
- {pytest_given-0.5.0 → pytest_given-0.5.1}/.gitignore +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/AGENTS.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/LICENSE.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/THIRD-PARTY-LICENSES +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/conftest.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-citing/references/repair.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/hygiene.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/story-coverage.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/collector.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/discovery.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/file_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/kind_inference.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/markdown_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/scenario.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/source.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/capture/story.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/citations/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/citations/markdown_links.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/citations/narrated.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/citations/targets.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/grouping/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/grouping/attachments.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/grouping/columns.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/grouping/percase.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/grouping/templatize.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/lint/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/lint/base.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/lint/runner.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/lint/runtime_rules.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/lint/summary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/markdown/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/markdown/plain_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/markdown/spans.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/errors.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/narration.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/report_url.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/runtime.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/steps.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/model/text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/plugin/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/plugin/case_ids.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/plugin/collection.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/plugin/fixtures.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/py.typed +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/citation_index.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/coverage.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/function_source.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/glossary_view.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/html_renderer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/inline_markdown.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/link_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/markdown_writer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/md_renderer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/palette.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/story_view.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/templates/alpine.min.js +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/templates/app.js +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/templates/fonts/source-code-pro-latin-wght-normal.woff2 +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/templates/fonts/source-sans-3-latin-wght-normal.woff2 +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/templates/logo.svg +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/templates/report.html.j2 +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/src/pytest_given/report/theme.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/conftest.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/test_lazy_imports.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/test_plugin_file_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/test_plugin_lint.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/integration/test_plugin_session_isolation.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/ubiquitous_language.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_collector.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_discovery.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_file_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_kind_inference.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_markdown_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_rootdir_isolation.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_source.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/capture/test_story.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/citation_reports.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/citations/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/citations/fixtures/citation-forms.md +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/citations/test_markdown_links.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/citations/test_markdown_links_oracle.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/citations/test_narrated.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/citations/test_targets.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/lint/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/lint/test_runtime_rules.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/lint/test_summary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/markdown/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/markdown/test_plain_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/markdown/test_spans.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/model/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/model/test_errors.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/model/test_narration.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/model/test_report_url.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/model/test_schema.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/model/test_steps.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/model/test_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/__init__.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_citation_index.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_coverage.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_function_source.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_glossary_view.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_inline_markdown.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_link_text.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_markdown_writer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_md_renderer.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_palette.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_story_view.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/report/test_theme.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/test_percase.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/test_plugin_traceback.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/test_project_glossary.py +0 -0
- {pytest_given-0.5.0 → pytest_given-0.5.1}/tests/unit/test_skills_data.py +0 -0
|
@@ -11,6 +11,38 @@ form `## [x.y.z] - YYYY-MM-DD`.
|
|
|
11
11
|
|
|
12
12
|
<!-- --8<-- [start:site] -->
|
|
13
13
|
|
|
14
|
+
## [0.5.1] - 2026-10-24
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- 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.
|
|
19
|
+
- `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.
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
|
|
23
|
+
- **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`.
|
|
24
|
+
- **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 `[`.
|
|
25
|
+
- **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.
|
|
26
|
+
- The HTML report's Tags sidebar copy button is visually tidied.
|
|
27
|
+
- 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.
|
|
28
|
+
- 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.
|
|
29
|
+
|
|
30
|
+
### Fixed
|
|
31
|
+
|
|
32
|
+
- A run that executes no test — `--collect-only`, `--setup-only`, `--setup-plan`, or a selection that matches nothing — no longer overwrites the previous report.
|
|
33
|
+
- 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.
|
|
34
|
+
- A chained exception's report now gives the error its own frames, with each cause shown above them as a separate block.
|
|
35
|
+
- A grouped scenario whose cases skipped for different reasons no longer shows one case's reason for all of them.
|
|
36
|
+
- Two scenarios no longer share a `#scenario=` slug when one falls back to its node ID.
|
|
37
|
+
- `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.
|
|
38
|
+
- 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`.
|
|
39
|
+
- `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.
|
|
40
|
+
- `attach()` with content JSON cannot carry, such as non-string dict keys or a cycle, and `Template` with an unclosed brace now raise `PytestGivenError`.
|
|
41
|
+
- 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.
|
|
42
|
+
- A failure raised inside the Markdown-glossary reader now shows its pytest-given frame as internal.
|
|
43
|
+
- 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.
|
|
44
|
+
- `pytest-given skills install` now removes directories no bundled file lives in, and `--check` reports them as drift.
|
|
45
|
+
|
|
14
46
|
## [0.5.0] - 2026-10-18
|
|
15
47
|
|
|
16
48
|
### Added
|
|
@@ -433,7 +465,8 @@ First public release.
|
|
|
433
465
|
- Bundled authoring, navigating, and reviewing skills for AI agents, shipped in
|
|
434
466
|
the wheel and version-matched to the plugin.
|
|
435
467
|
|
|
436
|
-
[Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.5.
|
|
468
|
+
[Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.5.1...HEAD
|
|
469
|
+
[0.5.1]: https://github.com/nwilbert/pytest-given/compare/v0.5.0...v0.5.1
|
|
437
470
|
[0.5.0]: https://github.com/nwilbert/pytest-given/compare/v0.4.1...v0.5.0
|
|
438
471
|
[0.4.1]: https://github.com/nwilbert/pytest-given/compare/v0.4.0...v0.4.1
|
|
439
472
|
[0.4.0]: https://github.com/nwilbert/pytest-given/compare/v0.3.0...v0.4.0
|
|
@@ -28,7 +28,7 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
|
|
|
28
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
29
|
| **Parameter table** | The per-scenario grouping of typed columns + cases. A column is a `param` (a `@pytest.mark.parametrize` input), a `derived` (a narrated value that varies across cases) or an `attachment` (an attachment whose payload varies). |
|
|
30
30
|
| **Group** | Collapsing the N scenario records 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 becomes a `{name}` placeholder or attachment badge pointing at a parameter-table column. The baseline tree comes from the first passed case, and every other passed case must narrate that same template. |
|
|
31
|
+
| **Templatize** | Derive the grouped-template step text by comparing every comparable case: what all of them share stays inline, and anything that varies becomes a `{name}` placeholder or attachment badge pointing at a parameter-table column. The baseline tree 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
32
|
|
|
33
33
|
## Fixtures and recording
|
|
34
34
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: pytest-given
|
|
3
|
-
Version: 0.5.
|
|
3
|
+
Version: 0.5.1
|
|
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
|
|
@@ -73,16 +73,16 @@ from pytest_given import attach, given, scenario, then, when
|
|
|
73
73
|
|
|
74
74
|
|
|
75
75
|
@pytest.fixture
|
|
76
|
-
@given('a coffee machine')
|
|
76
|
+
@given('a coffee machine with 10 coffees')
|
|
77
77
|
def machine():
|
|
78
78
|
return {'coffees': 10, 'price': 2}
|
|
79
79
|
|
|
80
80
|
|
|
81
|
-
@scenario('
|
|
81
|
+
@scenario('Buying a coffee takes one from the machine', tags=['checkout'])
|
|
82
82
|
def test_buy_coffee(machine):
|
|
83
|
-
with when('I
|
|
83
|
+
with when('I buy a coffee'):
|
|
84
84
|
machine['coffees'] -= 1
|
|
85
|
-
with then('
|
|
85
|
+
with then('the machine has 9 coffees left'):
|
|
86
86
|
assert machine['coffees'] == 9
|
|
87
87
|
attach('Machine state', machine)
|
|
88
88
|
```
|
|
@@ -95,9 +95,13 @@ pytest --given-html
|
|
|
95
95
|
|
|
96
96
|
This produces `given-report/report.html` — one file you can open directly in a browser.
|
|
97
97
|
|
|
98
|
+
The Coffeeshop example's report shows this same scenario:
|
|
99
|
+
|
|
100
|
+
✅ [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)
|
|
101
|
+
|
|
98
102
|
## Why pytest-given?
|
|
99
103
|
|
|
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.
|
|
104
|
+
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
105
|
|
|
102
106
|
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
107
|
|
|
@@ -107,10 +111,10 @@ pytest-given works the other way round: **engineers or their agents write normal
|
|
|
107
111
|
|
|
108
112
|
### Written by agents, reviewed by people
|
|
109
113
|
|
|
110
|
-
|
|
114
|
+
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
115
|
|
|
112
116
|
<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
|
|
117
|
+
<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
118
|
</p>
|
|
115
119
|
|
|
116
120
|
### Glossary and Domain Storytelling
|
|
@@ -119,7 +123,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
|
|
|
119
123
|
|
|
120
124
|
### Documents that stay true
|
|
121
125
|
|
|
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
|
|
126
|
+
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
127
|
|
|
124
128
|
## Features
|
|
125
129
|
|
|
@@ -128,6 +132,7 @@ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/lat
|
|
|
128
132
|
- **[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
133
|
- **[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
134
|
- **[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.
|
|
135
|
+
- **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
136
|
- **[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
137
|
- **[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
138
|
- **[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 +141,4 @@ The full reference — pytest options, source links, the standalone CLI — is o
|
|
|
136
141
|
|
|
137
142
|
## License
|
|
138
143
|
|
|
139
|
-
[MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT
|
|
144
|
+
[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).
|
|
@@ -42,16 +42,16 @@ from pytest_given import attach, given, scenario, then, when
|
|
|
42
42
|
|
|
43
43
|
|
|
44
44
|
@pytest.fixture
|
|
45
|
-
@given('a coffee machine')
|
|
45
|
+
@given('a coffee machine with 10 coffees')
|
|
46
46
|
def machine():
|
|
47
47
|
return {'coffees': 10, 'price': 2}
|
|
48
48
|
|
|
49
49
|
|
|
50
|
-
@scenario('
|
|
50
|
+
@scenario('Buying a coffee takes one from the machine', tags=['checkout'])
|
|
51
51
|
def test_buy_coffee(machine):
|
|
52
|
-
with when('I
|
|
52
|
+
with when('I buy a coffee'):
|
|
53
53
|
machine['coffees'] -= 1
|
|
54
|
-
with then('
|
|
54
|
+
with then('the machine has 9 coffees left'):
|
|
55
55
|
assert machine['coffees'] == 9
|
|
56
56
|
attach('Machine state', machine)
|
|
57
57
|
```
|
|
@@ -64,9 +64,13 @@ pytest --given-html
|
|
|
64
64
|
|
|
65
65
|
This produces `given-report/report.html` — one file you can open directly in a browser.
|
|
66
66
|
|
|
67
|
+
The Coffeeshop example's report shows this same scenario:
|
|
68
|
+
|
|
69
|
+
✅ [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)
|
|
70
|
+
|
|
67
71
|
## Why pytest-given?
|
|
68
72
|
|
|
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.
|
|
73
|
+
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
74
|
|
|
71
75
|
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
76
|
|
|
@@ -76,10 +80,10 @@ pytest-given works the other way round: **engineers or their agents write normal
|
|
|
76
80
|
|
|
77
81
|
### Written by agents, reviewed by people
|
|
78
82
|
|
|
79
|
-
|
|
83
|
+
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
84
|
|
|
81
85
|
<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
|
|
86
|
+
<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
87
|
</p>
|
|
84
88
|
|
|
85
89
|
### Glossary and Domain Storytelling
|
|
@@ -88,7 +92,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
|
|
|
88
92
|
|
|
89
93
|
### Documents that stay true
|
|
90
94
|
|
|
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
|
|
95
|
+
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
96
|
|
|
93
97
|
## Features
|
|
94
98
|
|
|
@@ -97,6 +101,7 @@ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/lat
|
|
|
97
101
|
- **[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
102
|
- **[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
103
|
- **[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.
|
|
104
|
+
- **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
105
|
- **[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
106
|
- **[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
107
|
- **[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 +110,4 @@ The full reference — pytest options, source links, the standalone CLI — is o
|
|
|
105
110
|
|
|
106
111
|
## License
|
|
107
112
|
|
|
108
|
-
[MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT
|
|
113
|
+
[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.1"
|
|
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.0"]
|
|
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]
|
|
@@ -110,6 +115,8 @@ include = [
|
|
|
110
115
|
|
|
111
116
|
[tool.uv]
|
|
112
117
|
exclude-newer = "7d"
|
|
118
|
+
# CVE fixes younger than the cooldown, exempted until they age past it.
|
|
119
|
+
exclude-newer-package = { certifi = false, filelock = false, virtualenv = false }
|
|
113
120
|
|
|
114
121
|
[tool.ruff]
|
|
115
122
|
# Generated by gen_large_scenarios.py and gitignored; the generator is linted.
|
|
@@ -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
|
|
|
@@ -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. |
|
|
@@ -4,7 +4,7 @@ A parametrized scenario renders as one narrated tree above a parameter table. A
|
|
|
4
4
|
|
|
5
5
|
- **Step structure must not depend on parameter values.** Every row is shown against the step structure of the first case, so a `with given/when/then(...)` inside an `if` on a parametrize value fails the run. When the steps really differ per case, decline the merge with `@scenario(..., group_parametrized=False)`. When the cases are different behaviors, not one behavior narrated two ways, split them into separate scenarios.
|
|
6
6
|
- **Narrate what varies with a t-string that interpolates a bare name.** `when(t'the drink costs {price} euros')` puts a `{price}` token in the step and adds a column with each case's value. Keep everything else the same across cases: the sentence, the `attach` labels, the term refs. To narrate an input derived from a column, bind it to its own local first (`price = cup_size * 0.01`, then `{price}`); an expected outcome is a column of its own (see the last rule).
|
|
7
|
-
- **A column must make sense on its own.** Sometimes the outcome depends on how a varied input relates to a fixed one. Then the column holds the relation (`hours_later`, `same_room`), not the varied input's raw value. `existing_start=50` or `existing_room='B'` only make sense next to a new booking that another step fixes in room A at hours 10 to 20. Merged tables fall into this too: parametrizing the value an old step text happened to name produces such columns. Arrange the fixed side first, so the relation has something to refer to. Whole objects as columns fail the same way, because a reader can't compare two `Booking(...)` reprs at a glance.
|
|
7
|
+
- **A column must make sense on its own.** Sometimes the outcome depends on how a varied input relates to a fixed one. Then the column holds the relation (`hours_later`, `same_room`), not the varied input's raw value. `existing_start=50` or `existing_room='B'` only make sense next to a new booking that another step fixes in room A at hours 10 to 20. Merged tables fall into this too: parametrizing the value an old step text happened to name produces such columns. Arrange the fixed side first, so the relation has something to refer to. Whole objects as columns fail the same way, because a reader can't compare two `Booking(...)` reprs at a glance. A list or a tuple reads no better.
|
|
8
8
|
- **Never turn a label back into data.** The body may unpack a relation column the way its narration says (`'A' if same_room else 'B'` under "same room: {same_room}"). It never maps a descriptive label to the input (`{'40 hours later': 40}[shift]`). Nor does a label column sit next to the data it describes. A case ID is not such a column, because the body never reads it. Either way, the report shows a claim that nothing checks against the input. A document is the exception, because it can't be shown as a column: parametrize a label, look the document up, and `attach` it, so the row shows both.
|
|
9
9
|
- **Contrast rows show what decides.** For each input that decides the outcome, include a row that changes only that input and flips the outcome. Put it at the boundary if there is one: moved 10 hours later, a booking still shares an hour; 11 hours later, it doesn't. A table whose rows all have the same outcome can't show which column matters, even when another scenario has the flipped case. Two exceptions need no flip: a column that lists forms the rule treats alike, and a flip that would need other steps, which stays in its own scenario.
|
|
10
10
|
- **A complex row can carry a custom ID.** When a row's values don't say what it is for, as with a boundary or a named edge case, `pytest.param(..., id='touching-edges')` annotates it. The table then starts with a `case ID` column, and `test_overlap[touching-edges]` in a failure points at its row. Leave plain rows to pytest's ids, and name the row's purpose, never a value the columns show (`start-10`).
|
|
@@ -31,10 +31,6 @@ Readers scan titles first, often without the steps: in the report's list, in Mar
|
|
|
31
31
|
- **When building the object *is* the action under test, `when` builds it and `given` shows only the input.** This applies when a scenario asserts a property of a freshly loaded, parsed or built object (`Order(lines)` computes its total, `parse(doc)` yields all rows). The `given` holds the raw input and, when useful, `attach`es it. The `when` runs the constructor, and the `then` asserts on the result. A `given` that both arranges the input *and* builds the object under test is the most common missed `when`.
|
|
32
32
|
- **Two phases are fine when honest, but rarer than they look.** If the assertion inspects a *static property of the arranged state*, not the return value of an action, then `given` + `then` is truthful. Don't invent a `when` for it. Likewise, a pure "constructing X raises" check needs no `given`.
|
|
33
33
|
|
|
34
|
-
## Parameter tables
|
|
35
|
-
|
|
36
|
-
A parametrized scenario renders as one narrated tree above a parameter table. Before you decorate a parametrized test or merge sibling scenarios into one, read [parameter-tables.md](parameter-tables.md).
|
|
37
|
-
|
|
38
34
|
## Arrangement
|
|
39
35
|
|
|
40
36
|
- **Show the arrangement as a `given`. Don't hide it in the `when` or the assertion.** When the action uses a module constant or a value built on the fly (a document string, a path, a list of rows), bind it in a `with given(...)` block. Don't pass it as a literal into the `when`, the `then` or the `pytest.raises` call.
|
|
@@ -71,18 +67,17 @@ A parametrized scenario renders as one narrated tree above a parameter table. Be
|
|
|
71
67
|
|
|
72
68
|
- **Narrate in glossary vocabulary.** Reference terms through handles in t-string step text, like `t'a {g["Room"].l} is booked'` (see [glossaries.md](glossaries.md)). They then render as kind-colored words and feed the Glossary tab's per-term filter. Use `.l` in the middle of a sentence and the bare handle at its start. Use `.s` for a regular plural or verb -s (`.l.s` in the middle of a sentence). Pick a term for its meaning, not its word: a term ref whose definition isn't what the sentence means sends the reader to the wrong row. (Skip this rule if the project has no glossary yet.)
|
|
73
69
|
- **The code speaks the language too.** Each referenced term should show up in the names inside the step: in the body, and in the names of the code it calls directly. `File glossary` over a `FileGlossary` call matches by design, since term names are natural language. But `{g["Reservation"]}` over code that only knows `Booking` is language drift, so rename one side.
|
|
70
|
+
- **Keep step text short.** A t-string with two or three term refs reaches your line-length limit fast. Move detail into nested steps instead of one long sentence.
|
|
74
71
|
- **Keep tags separate from the glossary.** A tag that repeats a term is redundant; filter by the term instead. `tag-shadows-term` catches exact collisions. It doesn't catch a tag that names a feature area the glossary covers under another word (`markdown` on scenarios that reference `File glossary`).
|
|
75
72
|
- **Expect few tags.** Tags carry only what the glossary can't: behavior (`validation`) and mechanism (`parametrization`). A tag must cut across modules, because a tag used in only one test file repeats the module grouping. It must also stay on a minority of the suite: `happy-path` on most scenarios filters nothing. Once you use a tag, put it on every scenario it describes, or filtering by it will miss some.
|
|
76
|
-
- **A `/` nests a tag
|
|
77
|
-
- **A work-item tag marks one piece of work.** `ticket/ABC-123` or `spec/<slug>` means "added by this piece of work", not "describes this behavior": it need not cut across modules, and other scenarios of the same behavior need not carry it.
|
|
78
|
-
- **Keep step text short.** A t-string with two or three term refs reaches your line-length limit fast. Move detail into nested steps instead of one long sentence.
|
|
73
|
+
- **A work-item tag marks one piece of work.** `ticket/ABC-123` or `spec/<slug>` means "added by this piece of work", not "describes this behavior": it need not cut across modules, and other scenarios of the same behavior need not carry it. A `/` nests a tag: the Tags sidebar files `ticket/ABC-123` under a `ticket` heading, which filters like a package, so the family takes one row.
|
|
79
74
|
|
|
80
75
|
## Keeping it truthful
|
|
81
76
|
|
|
82
77
|
Step text may abstract, but it must never overstate.
|
|
83
78
|
|
|
84
79
|
- **A value in the text must match the body.** A quantity, date or amount you narrate is a claim about the data the step actually holds. `'three copies'` over `catalog={'Dune': 1}` is a lie, even when every assertion passes. Interpolate a value the body takes from a constant (`t'a batch of {BATCH_SIZE} rows'`), so the text can't go stale when the constant changes.
|
|
85
|
-
- **Everything a `then` claims must be asserted in it.** A `then` that says "…and recorded in the ledger" without such an assertion describes behavior nobody checked. Assert it, or drop the clause. A `then` that sets the value it asserts, or asserts a constant, checks nothing. The asserted value must come from the code under test.
|
|
80
|
+
- **Everything a `then` claims must be asserted in it.** A `then` that says "…and recorded in the ledger" without such an assertion describes behavior nobody checked. Assert it, or drop the clause. A `then` that sets the value it asserts, or asserts a constant, checks nothing. The asserted value must come from the code under test, in a form that can show the claim: an order is asserted nowhere when the data keeps the two parts in separate fields.
|
|
86
81
|
- **A stub that raises when called checks nothing in the `then`.** The code under test may catch its `AssertionError` and fall back to the very outcome the `then` expects. To show a collaborator is never called, record its calls and assert `calls == []` (or `mock.assert_not_called()`) in the `then`.
|
|
87
82
|
- **What the `when` names must be what the body calls.** Narrate the action the step performs, not the one the scenario is loosely about. A common mistake: the `when` text reads like more arrangement, but its body arranges *and* makes the call the `then` reports. The action then appears nowhere in the report. Move the setup into a `given`.
|
|
88
83
|
- **"Each", "every", "both" and "all" are claims about every item.** A `then` or scenario title with one of these words must assert every item it covers. "Each slot becomes a term ref", backed by assertions on two of three slots, overstates. Assert them all, or narrow the text to what is checked.
|
|
@@ -59,7 +59,7 @@ What this means when you write:
|
|
|
59
59
|
|
|
60
60
|
**Check coverage after you change a sentence or a covering step.** Read it from the `coverage[]` of `pytest <selection> --given-json=report.json` instead of working out the rule yourself. Its shape and the query for uncovered sentences are in the navigating skill's [report-json.md](../../pytest-given-navigating/references/report-json.md).
|
|
61
61
|
|
|
62
|
-
A step can also **pin** sentences: `given(text, pins=book_a_group_trip['confirm'])` takes a sentence handle or a list of them. A pin *replaces* narration matching for that step
|
|
62
|
+
A step can also **pin** sentences: `given(text, pins=book_a_group_trip['confirm'])` takes a sentence handle or a list of them. A pin *replaces* narration matching for that step: the step covers exactly the sentences the pin names, in any story. Only a pin can cover a sentence with fewer than two terms. Pin when the sentence is phrased at a higher level than the vocabulary the step narrates, such as a process-level sentence implemented by a technical test. Pin it on the one step that demonstrates it. `pins=[]` and `@scenario(pins=...)` are in [api.md](api.md).
|
|
63
63
|
|
|
64
64
|
**Pin by name, not by number.** Sentence numbers are positions. Inserting a sentence renumbers every sentence after it, and `the_story[5]` then silently points at a different sentence. Name each sentence you pin (`sentence(..., name='confirm')`) and pin `the_story['confirm']`.
|
|
65
65
|
|
|
@@ -14,7 +14,11 @@ A **narrated citation** is a scenario citation written as a `<details>` block, i
|
|
|
14
14
|
|
|
15
15
|
A **plain report link** has no glyph: it keeps its own wording and claims only that its target exists.
|
|
16
16
|
|
|
17
|
-
`pytest-given citations check DOCS
|
|
17
|
+
`pytest-given citations check DOCS…` verifies every report link. `citations update` (same arguments) fixes what the first triage row lists, and exits 1 while other citation findings remain. Both commands:
|
|
18
|
+
|
|
19
|
+
- **read the JSON report of a run of every scenario:** `pytest -m pytest_given --given-json`, without xdist's `-n`. They read `given-report/report-data.json` unless `--report PATH` names another. A target the run left out counts as gone.
|
|
20
|
+
- **recognize a report link by its URL:** the one the JSON stores (`given_report_url`), or the one `--report-url` names. A relative link counts only with `--report-path`, the HTML report's place in the repository.
|
|
21
|
+
- **exit 2** when they have neither a URL nor a path, or when no document links the report: check the URL and path first.
|
|
18
22
|
|
|
19
23
|
## Triage
|
|
20
24
|
|
|
@@ -24,7 +28,7 @@ A **plain report link** has no glyph: it keeps its own wording and claims only t
|
|
|
24
28
|
| Cited target fails | The document claims what doesn't hold now. Fix the code, or, if the claim itself is outdated, tell the human: the prose is theirs. |
|
|
25
29
|
| Summary after a scenario citation | Delete it, unless the author wrote it as prose — then reword it so it no longer reads as a summary. |
|
|
26
30
|
| A tag or story citation "takes no narration" | Rewrite it as a one-line citation: only a scenario has a narration. |
|
|
27
|
-
| Mistyped citation | Fix the fragment to `#scenario=<node ID>`, `#tag=<tag>` or `#view=stories&story=<id>`, or drop the glyph if a plain link is meant. For a `<details>` block
|
|
31
|
+
| Mistyped citation | Fix the fragment to `#scenario=<node ID>`, `#tag=<tag>` or `#view=stories&story=<id>`, or drop the glyph if a plain link is meant. For a `<details>` block, match the shape under [Writing citations](#writing-citations). |
|
|
28
32
|
| Target not in the report | Rule out the report first: a partial run, or one from another rootdir (node IDs are relative to it), loses many targets at once. Then follow [references/repair.md](references/repair.md). |
|
|
29
33
|
|
|
30
34
|
## Finding what cites a scenario
|
|
@@ -36,17 +40,17 @@ A **plain report link** has no glyph: it keeps its own wording and claims only t
|
|
|
36
40
|
Citations are optional. A document such as a spec uses them to tie its prose to the code and to show the rules it describes at work. Cite only where the user asks. Where a passage cites:
|
|
37
41
|
|
|
38
42
|
- The cited scenario must not contradict the prose that cites it.
|
|
39
|
-
- The citations cover all the logic the passage describes: every case, not just one.
|
|
43
|
+
- The citations cover all the logic the passage describes: every case, not just one. A claim no test can show, such as an instruction in an agent prompt, stays uncited. Tell the user, rather than citing a scenario that only looks related.
|
|
40
44
|
- If the project has a glossary, the passage uses its terms consistently, as the cited scenarios do.
|
|
41
45
|
|
|
42
46
|
You cannot click a copy button. Write a placeholder — a typed `?` glyph and empty text — and let `update` fill it:
|
|
43
47
|
|
|
44
48
|
? [](https://example.org/report.html#scenario=tests/test_x.py::test_y)
|
|
45
49
|
|
|
46
|
-
Choose the target as in a repair
|
|
50
|
+
Choose the target as in a [repair](references/repair.md), not by its title.
|
|
47
51
|
|
|
48
52
|
- Narrate a scenario where the document states the behavior it demonstrates: a reader sees its steps, and a diff shows them change. A one-line citation only points at it.
|
|
49
|
-
- To narrate, write a `<details markdown="1">` block: a `<summary>` of the glyph and an `<a href="…#scenario=…">` with no other attribute, `</summary>` ending its line, a blank line, an empty body, `</details>` on its own line. `update` fills the body with the scenario's `--given-md` narration and rewrites it whole from then on, so write your own prose outside the block. On a Python-Markdown site, keep the block at the top level. Keep formatters off it (Prettier: `<!-- prettier-ignore-start -->` … `<!-- prettier-ignore-end -->`).
|
|
53
|
+
- To narrate, write a `<details markdown="1">` block after a blank line: on the next line a `<summary>` of the glyph and an `<a href="…#scenario=…">` with no other attribute, `</summary>` ending its line, then a blank line, an empty body, and `</details>` on its own line. `update` fills the body with the scenario's `--given-md` narration and rewrites it whole from then on, so write your own prose outside the block. On a Python-Markdown site, keep the block at the top level. Keep formatters off it (Prettier: `<!-- prettier-ignore-start -->` … `<!-- prettier-ignore-end -->`).
|
|
50
54
|
- Write the glyph and link bare: `**✅**` or `*[…](…)*` no longer reads as a citation.
|
|
51
55
|
- On a versioned docs site, link the report relatively (`../examples/report.html#tag=…`), so each version's page opens its own report. A copied citation links `given_report_url`: replace its URL up to the `#`.
|
|
52
56
|
- To cite a piece of work as a whole, give it one tag (`spec/<slug>`) and cite that. Don't cite a broad area tag, whose summary every later scenario changes: link it with a plain report link.
|
|
@@ -9,7 +9,7 @@ The test suite describes itself. The rendered scenarios are a behavioral spec, t
|
|
|
9
9
|
|
|
10
10
|
## Orientation: first contact
|
|
11
11
|
|
|
12
|
-
1. **Look for an existing report.** A `*.md` or `*.json` report that is committed or published by CI (often under `given-report/`) is the spec of the last run. Reading it costs nothing: no test environment, no suite run. To re-render a saved JSON report as Markdown, run `pytest-given report <data.json> --format md`. Render a fresh one only when there is none, or when the question is about *this* checkout.
|
|
12
|
+
1. **Look for an existing report.** A `*.md` or `*.json` report that is committed or published by CI (often under `given-report/`) is the spec of the last run. Reading it costs nothing: no test environment, no suite run. To re-render a saved JSON report as Markdown, run `pytest-given report <data.json> --format md`. Render a fresh one only when there is none, or when the question is about *this* checkout. A report covers only what its run selected, so a local one may be partial: compare the test files it lists (`[.scenarios[].source.relpath] | unique`) with the suite's, and its `metadata.commit_sha` with HEAD, before treating it as the whole spec.
|
|
13
13
|
2. **Read the glossary first.** Read `GLOSSARY.md`, or the `Glossary()` or `FileGlossary` declaration the tests import. It holds the domain vocabulary, with definitions.
|
|
14
14
|
3. **Render the spec.** `pytest <selection> --given-md` runs the selected tests and prints a Markdown spec of every scenario to stdout, between `<!-- pytest-given:md:start -->` and `:end`. The ``file.py:line::test_name`` line under each heading leads back to the code. Select tests with pytest's own arguments (`-k`, node IDs, `--lf`); the report covers whatever ran. When a full run is slow, add `-m pytest_given`: the report holds only scenarios, so leaving the plain tests out changes nothing in it.
|
|
15
15
|
4. **Read the stories.** The `story(...)` definitions are the flows between actors that the scenarios implement. `stories=` on a `@scenario`, or a pin on a scenario or a step, links a scenario to them.
|
|
@@ -18,13 +18,19 @@ The test suite describes itself. The rendered scenarios are a behavioral spec, t
|
|
|
18
18
|
|
|
19
19
|
For questions like "which scenarios are tagged X, reference term Y, fail, or implement story Z", write the data file and query it. The full shape and more recipes are in [references/report-json.md](references/report-json.md).
|
|
20
20
|
|
|
21
|
+
"Is this area covered?" usually spans several glossary terms, a tag and a directory. Match any of them:
|
|
22
|
+
|
|
21
23
|
```bash
|
|
22
24
|
pytest <selection> --given-json=report.json
|
|
23
|
-
jq -r '.scenarios[] | select(.
|
|
25
|
+
jq -r '.scenarios[] | select(([.. | .term_id? // empty] | any(IN("late-fee", "waitlist")))
|
|
26
|
+
or (.tags | any(startswith("billing")))
|
|
27
|
+
or (.source.relpath | startswith("tests/billing/")))
|
|
24
28
|
| .narration.text + " — " + .source.relpath + ":" + (.source.line|tostring)' report.json
|
|
25
29
|
```
|
|
26
30
|
|
|
27
|
-
The reference has recipes by status, words, term, tag and story. Use them rather than writing your own: a parametrized scenario keeps its failures per case, term refs nest at any depth, and `.story_ids` misses a scenario that only pins a story.
|
|
31
|
+
The reference has recipes by status, words, term, tag and story. Use them rather than writing your own: a parametrized scenario keeps its failures per case, term refs nest at any depth, and `.story_ids` misses a scenario that only pins a story. Without jq, load the JSON with Python's `json` module. The recipes' logic carries over.
|
|
32
|
+
|
|
33
|
+
These queries find only what exists. For where an area has no scenario, the reviewing skill's [completeness.md](../pytest-given-reviewing/references/completeness.md) lists the undecorated tests and the test files without a single scenario.
|
|
28
34
|
|
|
29
35
|
## Traps
|
|
30
36
|
|