pytest-given 0.5.1__tar.gz → 0.6.0__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.1 → pytest_given-0.6.0}/AGENTS.md +12 -12
- {pytest_given-0.5.1 → pytest_given-0.6.0}/CHANGELOG.md +48 -1
- pytest_given-0.6.0/GLOSSARY.md +122 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/PKG-INFO +18 -5
- {pytest_given-0.5.1 → pytest_given-0.6.0}/README.md +17 -4
- {pytest_given-0.5.1 → pytest_given-0.6.0}/docs/site/configuration/narration-lint.md +2 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/noxfile.py +65 -33
- {pytest_given-0.5.1 → pytest_given-0.6.0}/pyproject.toml +5 -7
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md +2 -2
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md +8 -4
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md +22 -20
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/lint.md +2 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/parameter-tables.md +7 -4
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md +3 -3
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-authoring/references/stories.md +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-citing/SKILL.md +11 -7
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-citing/references/repair.md +2 -2
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-navigating/references/report-json.md +8 -4
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-reviewing/SKILL.md +7 -2
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/completeness.md +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/hygiene.md +3 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/__init__.py +6 -2
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/__init__.py +13 -12
- pytest_given-0.6.0/src/pytest_given/capture/definition_refs.py +55 -0
- pytest_given-0.6.0/src/pytest_given/capture/file_glossary.py +154 -0
- pytest_given-0.6.0/src/pytest_given/capture/glossary.py +433 -0
- pytest_given-0.6.0/src/pytest_given/capture/glossary_resolution.py +34 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/kind_inference.py +1 -1
- pytest_given-0.6.0/src/pytest_given/capture/markdown_glossary.py +284 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/process_state.py +13 -8
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/source.py +13 -2
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/story.py +11 -82
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/template.py +7 -3
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/traceback.py +25 -11
- pytest_given-0.6.0/src/pytest_given/citations/check.py +325 -0
- pytest_given-0.5.1/src/pytest_given/citations/narrated.py → pytest_given-0.6.0/src/pytest_given/citations/details.py +32 -17
- pytest_given-0.6.0/src/pytest_given/citations/link_checks.py +410 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/citations/markdown_links.py +19 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/citations/targets.py +34 -5
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/cli/report.py +32 -4
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/cli/skills.py +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/grouping/checks.py +65 -7
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/grouping/columns.py +44 -25
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/grouping/context.py +5 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/grouping/group.py +10 -22
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/grouping/percase.py +4 -2
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/grouping/templatize.py +32 -20
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/lint/__init__.py +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/lint/ast_rules.py +1 -1
- pytest_given-0.5.1/src/pytest_given/lint/base.py → pytest_given-0.6.0/src/pytest_given/lint/catalog.py +4 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/lint/config.py +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/lint/runner.py +1 -1
- pytest_given-0.6.0/src/pytest_given/lint/runtime_rules.py +360 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/lint/summary.py +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/markdown/__init__.py +32 -3
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/markdown/blocks.py +61 -9
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/markdown/plain_text.py +8 -0
- pytest_given-0.5.1/src/pytest_given/report/inline_markdown.py → pytest_given-0.6.0/src/pytest_given/markdown/rendering.py +13 -19
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/markdown/spans.py +16 -0
- pytest_given-0.6.0/src/pytest_given/markdown/writing.py +74 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/model/__init__.py +41 -7
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/model/errors.py +5 -3
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/model/narration.py +82 -15
- pytest_given-0.6.0/src/pytest_given/model/report_order.py +33 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/model/schema.py +85 -12
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/model/serde.py +54 -8
- pytest_given-0.6.0/src/pytest_given/model/session_capture.py +38 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/model/text.py +29 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/plugin/__init__.py +9 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/plugin/case_ids.py +25 -15
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/plugin/collection.py +13 -4
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/plugin/fixtures.py +5 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/plugin/options.py +25 -13
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/plugin/session.py +63 -37
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/plugin/state.py +25 -2
- pytest_given-0.6.0/src/pytest_given/plugin/workers.py +115 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/__init__.py +5 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/citation_index.py +79 -61
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/console.py +5 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/coverage.py +10 -10
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/glossary_view.py +118 -17
- pytest_given-0.5.1/src/pytest_given/report/text.py → pytest_given-0.6.0/src/pytest_given/report/glyphs.py +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/html_renderer.py +143 -56
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/link_text.py +12 -10
- pytest_given-0.6.0/src/pytest_given/report/md_narration.py +68 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/md_renderer.py +33 -4
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/sinks.py +36 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/templates/_macros.html.j2 +3 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/templates/app.js +151 -66
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/templates/report.html.j2 +159 -77
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/templates/styles.css +95 -14
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/conftest.py +7 -3
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/integration/test_cli.py +126 -14
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/integration/test_cli_citations.py +38 -1
- pytest_given-0.5.1/tests/integration/test_skills_cli.py → pytest_given-0.6.0/tests/integration/test_cli_skills.py +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/integration/test_plugin.py +488 -162
- pytest_given-0.6.0/tests/integration/test_plugin_file_glossary.py +169 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/integration/test_plugin_lint.py +84 -0
- pytest_given-0.6.0/tests/integration/test_plugin_xdist.py +456 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/ubiquitous_language.py +3 -3
- pytest_given-0.6.0/tests/unit/capture/test_definition_refs.py +81 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_file_glossary.py +254 -45
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_glossary.py +217 -58
- pytest_given-0.6.0/tests/unit/capture/test_glossary_resolution.py +88 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_kind_inference.py +47 -18
- pytest_given-0.6.0/tests/unit/capture/test_markdown_glossary.py +640 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_step_descriptor.py +11 -32
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_story.py +18 -75
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_template.py +42 -26
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_traceback_parser.py +12 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/citation_reports.py +49 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/citations/test_check.py +467 -8
- pytest_given-0.5.1/tests/unit/citations/test_narrated.py → pytest_given-0.6.0/tests/unit/citations/test_details.py +78 -20
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/citations/test_targets.py +21 -2
- {pytest_given-0.5.1/tests/unit → pytest_given-0.6.0/tests/unit/grouping}/test_grouping.py +369 -9
- {pytest_given-0.5.1/tests/unit → pytest_given-0.6.0/tests/unit/grouping}/test_percase.py +45 -2
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/lint/test_ast_rules.py +36 -7
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/lint/test_config.py +1 -1
- pytest_given-0.6.0/tests/unit/lint/test_runtime_rules.py +680 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/lint/test_summary.py +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/markdown/test_blocks.py +56 -1
- pytest_given-0.6.0/tests/unit/markdown/test_rendering.py +43 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/markdown/test_spans.py +12 -0
- pytest_given-0.6.0/tests/unit/markdown/test_writing.py +45 -0
- pytest_given-0.6.0/tests/unit/model/test_narration.py +251 -0
- pytest_given-0.6.0/tests/unit/model/test_report_order.py +74 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/model/test_schema.py +107 -19
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/model/test_serde.py +132 -1
- pytest_given-0.6.0/tests/unit/model/test_session_capture.py +59 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/model/test_text.py +22 -0
- pytest_given-0.6.0/tests/unit/plugin/__init__.py +0 -0
- {pytest_given-0.5.1/tests/unit → pytest_given-0.6.0/tests/unit/plugin}/test_plugin.py +35 -1
- pytest_given-0.6.0/tests/unit/report/__init__.py +0 -0
- pytest_given-0.6.0/tests/unit/report/term_refs.py +30 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_citation_index.py +158 -51
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_coverage.py +25 -47
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_glossary_view.py +219 -2
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_html_renderer.py +356 -35
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_link_text.py +30 -0
- pytest_given-0.5.1/tests/unit/report/test_markdown_writer.py → pytest_given-0.6.0/tests/unit/report/test_md_narration.py +28 -47
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_md_renderer.py +46 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_sinks.py +106 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_story_view.py +39 -22
- pytest_given-0.5.1/tests/unit/report/test_inline_markdown.py → pytest_given-0.6.0/tests/unit/report/test_title_spans.py +8 -45
- pytest_given-0.6.0/tests/unit/test_architecture.py +211 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/test_project_glossary.py +1 -1
- {pytest_given-0.5.1 → pytest_given-0.6.0}/uv.lock +366 -255
- pytest_given-0.5.1/GLOSSARY.md +0 -116
- pytest_given-0.5.1/src/pytest_given/capture/discovery.py +0 -68
- pytest_given-0.5.1/src/pytest_given/capture/file_glossary.py +0 -103
- pytest_given-0.5.1/src/pytest_given/capture/glossary.py +0 -295
- pytest_given-0.5.1/src/pytest_given/capture/markdown_glossary.py +0 -121
- pytest_given-0.5.1/src/pytest_given/citations/check.py +0 -702
- pytest_given-0.5.1/src/pytest_given/lint/runtime_rules.py +0 -177
- pytest_given-0.5.1/src/pytest_given/report/markdown_writer.py +0 -105
- pytest_given-0.5.1/tests/integration/test_plugin_file_glossary.py +0 -60
- pytest_given-0.5.1/tests/unit/capture/test_discovery.py +0 -119
- pytest_given-0.5.1/tests/unit/capture/test_markdown_glossary.py +0 -265
- pytest_given-0.5.1/tests/unit/lint/test_runtime_rules.py +0 -343
- pytest_given-0.5.1/tests/unit/model/test_narration.py +0 -120
- {pytest_given-0.5.1 → pytest_given-0.6.0}/.gitignore +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/LICENSE.md +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/THIRD-PARTY-LICENSES +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/conftest.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/.agents/skills/pytest-given-reviewing/references/story-coverage.md +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/collector.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/scenario.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/capture/steps.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/citations/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/cli/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/cli/citations.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/grouping/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/grouping/attachments.py +0 -0
- /pytest_given-0.5.1/src/pytest_given/model/runtime.py → /pytest_given-0.6.0/src/pytest_given/model/raw_params.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/model/report_url.py +0 -0
- /pytest_given-0.5.1/src/pytest_given/model/steps.py → /pytest_given-0.6.0/src/pytest_given/model/step_tree.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/plugin/runtest.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/py.typed +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/function_source.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/palette.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/slugs.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/source_link.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/staged_write.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/story_view.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/templates/alpine.min.js +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/templates/fonts/source-code-pro-latin-wght-normal.woff2 +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/templates/fonts/source-sans-3-latin-wght-normal.woff2 +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/templates/logo.svg +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/src/pytest_given/report/theme.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/integration/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/integration/test_lazy_imports.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/integration/test_plugin_session_isolation.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_collector.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_rootdir_isolation.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/capture/test_source.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/citations/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/citations/fixtures/citation-forms.md +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/citations/test_markdown_links.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/citations/test_markdown_links_oracle.py +0 -0
- {pytest_given-0.5.1/tests/unit/lint → pytest_given-0.6.0/tests/unit/grouping}/__init__.py +0 -0
- {pytest_given-0.5.1/tests/unit/markdown → pytest_given-0.6.0/tests/unit/lint}/__init__.py +0 -0
- {pytest_given-0.5.1/tests/unit/model → pytest_given-0.6.0/tests/unit/markdown}/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/markdown/test_plain_text.py +0 -0
- {pytest_given-0.5.1/tests/unit/report → pytest_given-0.6.0/tests/unit/model}/__init__.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/model/test_errors.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/model/test_report_url.py +0 -0
- /pytest_given-0.5.1/tests/unit/model/test_steps.py → /pytest_given-0.6.0/tests/unit/model/test_step_tree.py +0 -0
- {pytest_given-0.5.1/tests/unit → pytest_given-0.6.0/tests/unit/plugin}/test_plugin_traceback.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/app_data.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_function_source.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_palette.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_slugs.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_source_link.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_staged_write.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/report/test_theme.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/test_quickstart.py +0 -0
- {pytest_given-0.5.1 → pytest_given-0.6.0}/tests/unit/test_skills_data.py +0 -0
|
@@ -16,7 +16,7 @@ uv sync --group dev
|
|
|
16
16
|
|
|
17
17
|
## Quality gates
|
|
18
18
|
|
|
19
|
-
`uv run nox` runs the default gate — `format`, `lint`, `mypy`, `
|
|
19
|
+
`uv run nox` runs the default gate — `format`, `lint`, `mypy`, `coverage` (the test suite, held to 100% coverage), `citations` (the documents' citations held to the committed reports), `audit` (a `pip-audit` of the locked dependencies). **Run it (or at minimum `uv run nox -s format lint mypy coverage`) before every commit.** The sessions below are on-demand; list them all with `uv run nox -l`.
|
|
20
20
|
|
|
21
21
|
- `uv run nox -s examples` regenerates the example reports under `examples/`. Run after changes to the renderer, templates, plugin output schema, or any example test file, and commit the updated outputs.
|
|
22
22
|
- `uv run nox -s self_report` regenerates `examples/self-report/` — pytest-given applied to its own backend tests (see [Writing self-report scenarios](#writing-self-report-scenarios)). Run after decorating more tests or changing decorated ones, and after renderer or template changes (its HTML is one of the site's example reports), and commit the updated outputs.
|
|
@@ -30,10 +30,7 @@ uv sync --group dev
|
|
|
30
30
|
- `uv run nox -s benchmark` generates the large-scenarios suite and renders its JSON + HTML into `benchmarks/` (outputs gitignored). Run it when a change could move report-generation cost; `benchmarks/bench.py` does size sweeps and cProfile runs directly.
|
|
31
31
|
- `uv run nox -s compat` runs the suite against the oldest supported pytest and markdown-it-py and the newest, on every supported Python — raising either floor in `pyproject.toml` moves its pin there too. The default gate tests only the locked versions on one Python, so this is the only check of the rest. Before a release, the [Compat workflow](.github/workflows/compat.yml) runs it on GitHub's Linux and Windows runners.
|
|
32
32
|
- `uv run nox -s build` builds the wheel + sdist and verifies them as a consumer would. The in-repo suite imports from `src/`, so this session is the only thing that catches a packaging regression. CI and the release workflow both run it.
|
|
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)
|
|
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
|
-
- `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
|
-
- 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`.
|
|
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). Before changing anything under `docs/site/`, the README's diagram or its screenshots, read [docs/site-development.md](docs/site-development.md): staging, the derived diagram, the screenshot recipe, self-hosted fonts.
|
|
37
34
|
|
|
38
35
|
## Releasing
|
|
39
36
|
|
|
@@ -42,10 +39,11 @@ Releases go to PyPI via a manually dispatched [Release workflow](.github/workflo
|
|
|
42
39
|
## Architecture
|
|
43
40
|
|
|
44
41
|
`src/pytest_given/` is seven library subpackages plus two entry points, with a
|
|
45
|
-
strict dependency direction (
|
|
42
|
+
strict dependency direction (held by `tests/unit/test_architecture.py`):
|
|
46
43
|
|
|
47
44
|
```
|
|
48
|
-
markdown/ the leaf — reading Markdown
|
|
45
|
+
markdown/ the leaf — reading Markdown (blocks, tables, inline
|
|
46
|
+
spans), writing spans back, rendering them as HTML
|
|
49
47
|
model/ schema, serde, errors, shared text rules
|
|
50
48
|
capture/ lint/ report/ each on model/ only, never on each other
|
|
51
49
|
grouping/ on model/ + capture/
|
|
@@ -64,9 +62,10 @@ What no filename tells you:
|
|
|
64
62
|
a bare `pytest` failing on one is the point, not a side effect.
|
|
65
63
|
- `capture/` imports pytest nowhere, so all of it is unit-testable without a
|
|
66
64
|
session; a stray step warns with `model.PytestGivenWarning`, not pytest's.
|
|
67
|
-
- `citations/` reads and edits the user's Markdown documents
|
|
68
|
-
should say
|
|
69
|
-
the same lines
|
|
65
|
+
- `citations/` reads and edits the user's Markdown documents. What a citation
|
|
66
|
+
should say comes from `report`: its glyph, link text and summary from
|
|
67
|
+
`CitationIndex`, since the HTML's copy buttons write the same lines, and a
|
|
68
|
+
`<details>` citation's body from `citation_body_md`.
|
|
70
69
|
- Each package exposes the *whole* job, not its parts: `report.emit_sinks`
|
|
71
70
|
(render → write → discard-on-failure, so a failure leaves no half-written
|
|
72
71
|
report), `lint.run_lint` and `citations.check_citations` (every document
|
|
@@ -107,19 +106,20 @@ Before merging changes to narrated tests, run the `pytest-given-reviewing` skill
|
|
|
107
106
|
|
|
108
107
|
What is specific to this repo's self-report:
|
|
109
108
|
|
|
110
|
-
- The glossary handle is `pg` — `GLOSSARY.md` loaded as a `
|
|
109
|
+
- The glossary handle is `pg` — `GLOSSARY.md` loaded as a `TableGlossary` in `tests/ubiquitous_language.py`. Term-rename mechanics live under [Conventions](#conventions); regeneration and lint gating under [Quality gates](#quality-gates).
|
|
111
110
|
- **New or changed user-facing behavior needs a scenario, not just a test** — otherwise the behavior is invisible in the report. Decorate the test that best *states* the rule, one per rule, not per branch; the edge cases around it stay plain. Two gaps to check for: a rule the [CHANGELOG](CHANGELOG.md) announces that no scenario names, and a [GLOSSARY.md](GLOSSARY.md) row *asserting* behavior (`Templatize`, `Parameter table`) that no scenario demonstrates.
|
|
112
111
|
|
|
113
112
|
## Conventions
|
|
114
113
|
|
|
115
114
|
- Use the canonical vocabulary from [GLOSSARY.md](GLOSSARY.md) in prose as well as code — docs, skill references, and specs say the official term (`term ref`, not a paraphrase like "narrated term"). Naming and rename mechanics live in the skill's [references/glossaries.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md); here, a rename lands in one commit (glossary row, `pg\[` references, implementation naming) plus a regenerated `uv run nox -s self_report`. Adding a term is safe, but still regenerate.
|
|
116
115
|
- **Docstrings only for what the code cannot say** — a non-obvious invariant, a constraint that makes the shape necessary, a trap for the next reader — and a line or two at most. No signature restatement, no implementation narration, no `X is the only caller of Y` cross-references (they rot fastest; the reader can grep). Prefer a precise name to a sentence explaining a vague one. When you change a module, delete the sentences that have stopped being true rather than repairing them.
|
|
117
|
-
- Internal code annotates a glossary as the base `model.Glossary`, never `pytest_given.Glossary` (the `capture` subclass users register terms on): a report rebuilt from JSON and a
|
|
116
|
+
- Internal code annotates a glossary as the base `model.Glossary`, never `pytest_given.Glossary` (the `capture` subclass users register terms on): a report rebuilt from JSON and a Markdown glossary both carry no such subclass.
|
|
118
117
|
- Avoid `Any` — use precise types, generics, `TYPE_CHECKING` imports, or `ContextVar[T]` over untyped `threading.local`.
|
|
119
118
|
- Use `NewType` for domain-specific IDs (e.g., `NodeId`) and PEP 695 `type` statements for aliases. Avoid raw complex types like `dict[str, tuple[list[str], list[Any]]]` — introduce named types instead.
|
|
120
119
|
- Every package `src/` imports is a declared dependency in `pyproject.toml`, even one another dependency already brings in.
|
|
121
120
|
- Only module-level imports — no inline/function-level imports. A third-party package only some sessions or commands use goes in the importing module's `__lazy_modules__` (Python 3.15 defers it to first use; `tests/integration/test_lazy_imports.py` holds the entry points to it).
|
|
122
121
|
- **pytest config lives in `[tool.pytest]`** — native TOML mode since pytest 8.4/9.0, where lists are real arrays rather than newline-separated strings. `[tool.pytest.ini_options]` is the legacy INI-compat table; **never add it alongside** — pytest raises `UsageError` if both are present. New `addini` options take native types (a `type='linelist'` ini takes a TOML array).
|
|
122
|
+
- Every `pytest-given` subcommand exits 0 when it is done with nothing to report, 1 when it found something to act on, and 2 when it could not do its job.
|
|
123
123
|
- Cross-platform: plugin and tests must pass on native Windows, macOS, Linux, and WSL (Linux interpreter over a `/mnt/<drive>` Windows checkout). Never hardcode a path separator or assume POSIX semantics — go through `pathlib`, `as_posix()` for stored/serialized paths, resolve before comparing. Path-form folding is confined to `capture/source.py` (mechanics in its docstrings; the why, and how to run one checkout from both Windows and WSL without the venvs colliding, in [docs/wsl-development.md](docs/wsl-development.md)). Only tests asserting WSL `/mnt`-absolute behavior may `skipif(sys.platform == 'win32', …)` — native-Windows pathlib reads `/mnt/<drive>` as drive-relative, not absolute — everything else passes on all four targets.
|
|
124
124
|
- Relative imports inside the package throughout — `from .schema import Scenario` for siblings, `from ..model import Scenario` across subpackages (always through the subpackage root, never into its submodules). Tests use absolute imports and may reach into any internal path. The dependency direction those imports must respect is under [Architecture](#architecture).
|
|
125
125
|
- Prefer `assert` over `# pragma: no cover` for invariant guards. Asserts document the invariant and fail loudly if violated; pragmas hide the line and silently bail. Reserve `# pragma: no cover` for code that genuinely cannot be exercised by a test (e.g. `if __name__ == '__main__':` script entry).
|
|
@@ -11,6 +11,51 @@ form `## [x.y.z] - YYYY-MM-DD`.
|
|
|
11
11
|
|
|
12
12
|
<!-- --8<-- [start:site] -->
|
|
13
13
|
|
|
14
|
+
## [0.6.0] - 2026-11-21
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- A format spec `{flag:true phrase|false phrase}` words a Boolean in a step while the parameter table keeps the Boolean.
|
|
19
|
+
- Glossary sections: `Glossary.section(name)` and a Markdown glossary's headings group terms, and the Glossary tab groups and filters by them.
|
|
20
|
+
- `ParagraphGlossary` loads a `GLOSSARY.md` written as `**Term**:` paragraphs with optional `_Avoid_:` lines.
|
|
21
|
+
- Avoided words: `avoid=` on a term declaration, a `TableGlossary`'s `avoid_column` and a `ParagraphGlossary`'s `_Avoid_:` line list a term's rejected synonyms, which the term's card shows and the `avoided-word` lint rule, `warn` by default, flags in a step, a scenario title or a story sentence.
|
|
22
|
+
- Term citations: `citations check` and `update` read `#view=glossary&term=<id>` or `#term=<id>` as a citation of a term, with a tag's glyph and summary, a `<details markdown="1">` one carrying the term's definition, and a Glossary term row in the HTML report gets the copy button with **Copy citation** and **Copy defining citation**.
|
|
23
|
+
- A bold term name in a glossary definition is a definition ref, which the HTML report's Glossary tab renders as a term ref that opens the named term, and the `unresolved-definition-ref` lint rule, `warn` by default, flags a bold span that names no term.
|
|
24
|
+
- `pytest-given report --glossary-only` renders an HTML report with only the Glossary tab.
|
|
25
|
+
- A pytest-xdist run (`-n`) writes reports and runs the narration lint, choosing `--dist loadfile` when no `--dist` is given; any other `--dist` still stops with a usage error.
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
|
|
29
|
+
- **Breaking.** A format spec with one `|` and text on both sides now only accepts a `bool`, so `{when:%H|%M}` on a `datetime` raises `PytestGivenError`. Assign the text to a local variable and interpolate that instead.
|
|
30
|
+
- **Breaking.** `FileGlossary` is renamed `TableGlossary`, and a term repeated under two headings of a Markdown glossary now raises, identical rows included. Rename the import and the constructor call, and keep one row of a repeated term.
|
|
31
|
+
- **Breaking.** `pytest-given report` and `pytest-given skills install` now exit 2, not 1, when they cannot do their job, such as an unreadable JSON file or an unwritable destination. A script that tests for exit code 1 on such a failure must test for 2.
|
|
32
|
+
- **Breaking.** A glossary term's `definition` in the JSON report is now an object, which holds the string it used to be in `text` and its definition refs in `parts`. A script reading `.definition` must read `.definition.text`.
|
|
33
|
+
- A plain report link to a glossary term is now checked, so a dead one fails `citations check`.
|
|
34
|
+
- The report lists scenarios by file and then by line, whatever order the tests ran in.
|
|
35
|
+
- The HTML report leaves out the Scenarios tab when the report has no scenarios, and opens on its first remaining view.
|
|
36
|
+
- **Breaking.** pytest-given finds a glossary wherever the suite's modules construct it, not only through a story or a `conftest.py`, and raises `PytestGivenError` when they construct two. Construct the glossary once and import it wherever it is used.
|
|
37
|
+
|
|
38
|
+
### Fixed
|
|
39
|
+
|
|
40
|
+
- Following a term ref to the HTML report's Glossary tab scrolls to the term, clearing the tab's search and filters when they hide it.
|
|
41
|
+
- A report link whose `#status=` names only statuses the report doesn't know now shows every scenario instead of none.
|
|
42
|
+
- A failure raised while rendering a step's interpolation, such as a bad format spec, no longer shows a pytest-given frame in the report's traceback.
|
|
43
|
+
- A narrated citation of a scenario with no steps now has an empty body instead of blank lines, which `citations update` rewrites.
|
|
44
|
+
|
|
45
|
+
## [0.5.2] - 2026-11-07
|
|
46
|
+
|
|
47
|
+
### Changed
|
|
48
|
+
|
|
49
|
+
- 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.
|
|
50
|
+
- 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.
|
|
51
|
+
- The bundled `pytest-given-authoring` and `pytest-given-reviewing` skills hold glossary terms and definitions to concepts instead of implementation details.
|
|
52
|
+
- 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.
|
|
53
|
+
|
|
54
|
+
### Fixed
|
|
55
|
+
|
|
56
|
+
- 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.
|
|
57
|
+
- 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.
|
|
58
|
+
|
|
14
59
|
## [0.5.1] - 2026-10-24
|
|
15
60
|
|
|
16
61
|
### Added
|
|
@@ -465,7 +510,9 @@ First public release.
|
|
|
465
510
|
- Bundled authoring, navigating, and reviewing skills for AI agents, shipped in
|
|
466
511
|
the wheel and version-matched to the plugin.
|
|
467
512
|
|
|
468
|
-
[Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.
|
|
513
|
+
[Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.6.0...HEAD
|
|
514
|
+
[0.6.0]: https://github.com/nwilbert/pytest-given/compare/v0.5.2...v0.6.0
|
|
515
|
+
[0.5.2]: https://github.com/nwilbert/pytest-given/compare/v0.5.1...v0.5.2
|
|
469
516
|
[0.5.1]: https://github.com/nwilbert/pytest-given/compare/v0.5.0...v0.5.1
|
|
470
517
|
[0.5.0]: https://github.com/nwilbert/pytest-given/compare/v0.4.1...v0.5.0
|
|
471
518
|
[0.4.1]: https://github.com/nwilbert/pytest-given/compare/v0.4.0...v0.4.1
|
|
@@ -0,0 +1,122 @@
|
|
|
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
|
+
| Boolean phrase | Either of the two texts that word a Boolean in a step. Written as a phrase spec, a format spec holding the true phrase, a `\|` and the false phrase: `{pinned:pins it\|does not pin it}`. The step shows both phrases, and the **Parameter table** keeps the Boolean. |
|
|
31
|
+
| 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. |
|
|
32
|
+
| 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. |
|
|
33
|
+
|
|
34
|
+
## Fixtures and recording
|
|
35
|
+
|
|
36
|
+
| Term | Meaning |
|
|
37
|
+
|---|---|
|
|
38
|
+
| Step fixture | A pytest fixture that narrates its setup as a `given` **Step**. A fixture cannot narrate `when` or `then`. |
|
|
39
|
+
| 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. |
|
|
40
|
+
| 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. |
|
|
41
|
+
| Fixture recording | The steps and attachments a **step fixture** narrates during setup. A generator fixture's teardown records nothing — it refuses steps and attachments. |
|
|
42
|
+
| Graft | Attaching a **fixture recording** into the **active scenario**'s step tree at the moment its host test starts. |
|
|
43
|
+
|
|
44
|
+
## Collector state
|
|
45
|
+
|
|
46
|
+
| Term | Meaning |
|
|
47
|
+
|---|---|
|
|
48
|
+
| Collector | What gathers a session's scenarios, **fixture recordings** and parameter info. |
|
|
49
|
+
| Active scenario | The scenario currently being recorded into. |
|
|
50
|
+
| Node ID | A pytest test identifier (e.g., `tests/test_x.py::test_y[a-b]`). |
|
|
51
|
+
| Step stack | The chain of currently-open steps. Opening a step adds it, and leaving its block removes it. |
|
|
52
|
+
|
|
53
|
+
## Report
|
|
54
|
+
|
|
55
|
+
| Term | Meaning |
|
|
56
|
+
|---|---|
|
|
57
|
+
| 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. |
|
|
58
|
+
| Renderer | Converts a JSON report into a rendering — a self-contained HTML page or a Markdown document. |
|
|
59
|
+
| 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. |
|
|
60
|
+
| 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. |
|
|
61
|
+
| Source link | A link to a file and line: a scenario's test function, or the declaration of a **Story** or **Term**. |
|
|
62
|
+
| Report link | A Markdown link to a scenario, tag, story or term in the HTML **Report**. Without a glyph it is a plain one, which claims only that its target exists. |
|
|
63
|
+
| Citation | A **Report link** led by its target's status glyph, citing a scenario, tag, story or term from a Markdown document: `✅ [title](<report URL>#scenario=…)`. A tag, story or term citation adds a summary after it, `(5 ✅ · 2 🔵)`. A target the **Report** lacks reads `❓`. |
|
|
64
|
+
| 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. |
|
|
65
|
+
| Defining citation | A **Citation** of a term written as a collapsible block, the citation as its summary and the term's definition as its body. |
|
|
66
|
+
| 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. |
|
|
67
|
+
| Theme | The HTML report's colour scheme — `light`, `dark`, or `auto` (follow the viewer's system). |
|
|
68
|
+
|
|
69
|
+
## Narration lint
|
|
70
|
+
|
|
71
|
+
| Term | Meaning |
|
|
72
|
+
|---|---|
|
|
73
|
+
| 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. |
|
|
74
|
+
| 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. |
|
|
75
|
+
| 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. |
|
|
76
|
+
| 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. |
|
|
77
|
+
|
|
78
|
+
## Domain Storytelling
|
|
79
|
+
|
|
80
|
+
The Domain-Driven Design layer atop the core surface. All terms here are optional features: a test suite can use none, some, or all.
|
|
81
|
+
|
|
82
|
+
Terms follow [Domain Storytelling](https://domainstorytelling.org/quick-start-guide)'s own, where actors and work objects connected by activities form sentences.
|
|
83
|
+
|
|
84
|
+
| Term | Meaning |
|
|
85
|
+
|---|---|
|
|
86
|
+
| Glossary | The shared vocabulary a domain speaks in: its Ubiquitous Language. |
|
|
87
|
+
| Markdown glossary | A glossary loaded from a Markdown file: a `TableGlossary` from GFM pipe tables, or a `ParagraphGlossary` from **term paragraphs**. |
|
|
88
|
+
| Term paragraph | A term in a `ParagraphGlossary`, written as one paragraph: `**Term**:`, its definition, and an optional `_Avoid_:` line, the format of Matt Pocock's skills. |
|
|
89
|
+
| Glossary section | A named group of terms: the heading a **Markdown glossary** term sits under, or the `g.section(...)` a code glossary declares it through. The Glossary tab groups and filters by it. |
|
|
90
|
+
| Avoided word | A rejected synonym a **term** lists, which the `avoided-word` lint rule flags in narration. An avoid entry may add a parenthesized note, which the report shows and the lint ignores. |
|
|
91
|
+
| Deferred term | A term handed over before its kind is settled: what `g('foo')` and `g['foo']` on a code glossary return, and a **Markdown glossary** lookup of a row with no declared kind. **Kind inference** settles it later. |
|
|
92
|
+
| Term | A glossary entry: an **Actor**, **Work Object**, **Activity**, or **kindless** term. Each carries an id (slug), a canonical name, a kind unless kindless, an optional definition, an optional **glossary section** and any **avoided words**. |
|
|
93
|
+
| 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. |
|
|
94
|
+
| 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**. |
|
|
95
|
+
| Actor | A glossary term for a participant in the domain (e.g., *Guest*). |
|
|
96
|
+
| Work Object | A glossary term for a thing acted on (e.g., *Room*, *Booking*). |
|
|
97
|
+
| 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*. |
|
|
98
|
+
| Term ref | An occurrence of a term inside narration, a clause or a definition. |
|
|
99
|
+
| Definition ref | A bold span in a glossary definition that names a term of the same glossary, by its canonical name or **S-form** in any case. The report renders it as a **term ref**. |
|
|
100
|
+
| Instance | A named refinement of an **Actor** or **Work Object** (e.g., `guest('Alice')` is an instance of the *Guest* actor). |
|
|
101
|
+
| 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*). |
|
|
102
|
+
| Story | A named flow modeled as a sequence of **sentences**. Stories are the unit of **coverage**. |
|
|
103
|
+
| 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. |
|
|
104
|
+
| 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. |
|
|
105
|
+
| 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. |
|
|
106
|
+
| 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. |
|
|
107
|
+
| 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. |
|
|
108
|
+
| Pin | What a sentence's **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. |
|
|
109
|
+
| 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. |
|
|
110
|
+
| 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**. |
|
|
111
|
+
| 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). |
|
|
112
|
+
| Undefined | A term with no definition. Orthogonal to **kindless**. |
|
|
113
|
+
|
|
114
|
+
## Collaboration
|
|
115
|
+
|
|
116
|
+
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`).
|
|
117
|
+
|
|
118
|
+
| Term | Meaning |
|
|
119
|
+
|---|---|
|
|
120
|
+
| Developer | Person who writes the application code and — together with the **Agent** — the scenarios; curates the glossary with the **Domain Expert**. |
|
|
121
|
+
| 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. |
|
|
122
|
+
| 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.
|
|
3
|
+
Version: 0.6.0
|
|
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,10 +43,20 @@ 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.
|
|
49
|
-
- **[
|
|
58
|
+
- **[Table glossary](https://nwilbert.github.io/pytest-given/latest/examples/table-glossary.html)**: the same, with the glossary kept in a Markdown table.
|
|
59
|
+
- **[Paragraph glossary](https://nwilbert.github.io/pytest-given/latest/examples/paragraph-glossary.html)**: the glossary kept as `**Term**:` paragraphs, with sections and avoided words.
|
|
50
60
|
- **[Self-report](https://nwilbert.github.io/pytest-given/latest/examples/self-report.html)**: pytest-given's own test suite.
|
|
51
61
|
|
|
52
62
|
## Quick start
|
|
@@ -114,7 +124,10 @@ pytest-given works the other way round: **engineers or their agents write normal
|
|
|
114
124
|
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.
|
|
115
125
|
|
|
116
126
|
<p align="center">
|
|
117
|
-
<
|
|
127
|
+
<picture>
|
|
128
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram-dark.svg">
|
|
129
|
+
<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">
|
|
130
|
+
</picture>
|
|
118
131
|
</p>
|
|
119
132
|
|
|
120
133
|
### Glossary and Domain Storytelling
|
|
@@ -123,7 +136,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
|
|
|
123
136
|
|
|
124
137
|
### Documents that stay true
|
|
125
138
|
|
|
126
|
-
A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and
|
|
139
|
+
A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags, stories and glossary terms 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.
|
|
127
140
|
|
|
128
141
|
## Features
|
|
129
142
|
|
|
@@ -134,7 +147,7 @@ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/lat
|
|
|
134
147
|
- **[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
148
|
- **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.
|
|
136
149
|
- **[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.
|
|
137
|
-
- **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags and
|
|
150
|
+
- **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags, stories and glossary terms, led by their status and checked against the latest run.
|
|
138
151
|
- **[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.
|
|
139
152
|
|
|
140
153
|
The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).
|
|
@@ -12,10 +12,20 @@ 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.
|
|
18
|
-
- **[
|
|
27
|
+
- **[Table glossary](https://nwilbert.github.io/pytest-given/latest/examples/table-glossary.html)**: the same, with the glossary kept in a Markdown table.
|
|
28
|
+
- **[Paragraph glossary](https://nwilbert.github.io/pytest-given/latest/examples/paragraph-glossary.html)**: the glossary kept as `**Term**:` paragraphs, with sections and avoided words.
|
|
19
29
|
- **[Self-report](https://nwilbert.github.io/pytest-given/latest/examples/self-report.html)**: pytest-given's own test suite.
|
|
20
30
|
|
|
21
31
|
## Quick start
|
|
@@ -83,7 +93,10 @@ pytest-given works the other way round: **engineers or their agents write normal
|
|
|
83
93
|
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.
|
|
84
94
|
|
|
85
95
|
<p align="center">
|
|
86
|
-
<
|
|
96
|
+
<picture>
|
|
97
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram-dark.svg">
|
|
98
|
+
<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">
|
|
99
|
+
</picture>
|
|
87
100
|
</p>
|
|
88
101
|
|
|
89
102
|
### Glossary and Domain Storytelling
|
|
@@ -92,7 +105,7 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
|
|
|
92
105
|
|
|
93
106
|
### Documents that stay true
|
|
94
107
|
|
|
95
|
-
A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and
|
|
108
|
+
A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags, stories and glossary terms 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.
|
|
96
109
|
|
|
97
110
|
## Features
|
|
98
111
|
|
|
@@ -103,7 +116,7 @@ A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/lat
|
|
|
103
116
|
- **[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
117
|
- **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.
|
|
105
118
|
- **[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.
|
|
106
|
-
- **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags and
|
|
119
|
+
- **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags, stories and glossary terms, led by their status and checked against the latest run.
|
|
107
120
|
- **[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.
|
|
108
121
|
|
|
109
122
|
The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).
|
|
@@ -19,6 +19,8 @@ Each rule has a default severity. A `warn` lint finding is printed in the termin
|
|
|
19
19
|
| `unused-interpolation` | `warn` | A `with` step whose text contains a `{name}` (a t-string value or a parameter-table placeholder) that the step's body doesn't use. |
|
|
20
20
|
| `tag-shadows-term` | `warn` | A scenario tag that matches a glossary term, so the same concept has two names. |
|
|
21
21
|
| `dead-term` | `off` | A glossary term that no step, scenario title, or story sentence uses. Turn this on if every glossary term should be used. |
|
|
22
|
+
| `unresolved-definition-ref` | `warn` | A bold span in a glossary definition that names no term of the glossary, often left behind when a term is renamed. Fix the name, or use italics for emphasis. An entry for this rule names the term's id instead of a test: `unresolved-definition-ref: handle`. |
|
|
23
|
+
| `avoided-word` | `warn` | An [avoided word](../guide/glossary.md#avoided-words) of a glossary term, or its S-form, as a whole word in any case, with a hyphen or a space between its words, in the plain text of a scenario title, a step or a story sentence. Term refs, values, code spans and glossary definitions are not checked, but both phrases of a [Boolean phrase](../guide/step-text.md#boolean-phrases) are. Each scenario or story gets one lint finding per avoided word. Use a term ref to the preferred term, the fitting one when the message names several, or reword. If the word is right after all, remove it from the term's avoided words. An entry for this rule names the scenario's node ID or the story's id: `avoided-word: *::test_booking`. |
|
|
22
24
|
|
|
23
25
|
## Configuration
|
|
24
26
|
|
|
@@ -36,7 +36,6 @@ nox.options.sessions = [
|
|
|
36
36
|
'format',
|
|
37
37
|
'lint',
|
|
38
38
|
'mypy',
|
|
39
|
-
'test',
|
|
40
39
|
'coverage',
|
|
41
40
|
'citations',
|
|
42
41
|
'audit',
|
|
@@ -136,8 +135,6 @@ def coverage(session: nox.Session) -> None:
|
|
|
136
135
|
'pytest_given',
|
|
137
136
|
'-m',
|
|
138
137
|
'pytest',
|
|
139
|
-
'tests/unit',
|
|
140
|
-
'tests/integration',
|
|
141
138
|
)
|
|
142
139
|
try:
|
|
143
140
|
session.run('coverage', 'report', '--fail-under', '100', '--show-missing')
|
|
@@ -402,9 +399,14 @@ _EXAMPLES = (
|
|
|
402
399
|
'Hotel Booking Example',
|
|
403
400
|
),
|
|
404
401
|
_Example(
|
|
405
|
-
'examples/
|
|
406
|
-
'
|
|
407
|
-
'
|
|
402
|
+
'examples/table-glossary/test_table_glossary.py',
|
|
403
|
+
'table-glossary',
|
|
404
|
+
'Table Glossary Example',
|
|
405
|
+
),
|
|
406
|
+
_Example(
|
|
407
|
+
'examples/paragraph-glossary/test_paragraph_glossary.py',
|
|
408
|
+
'paragraph-glossary',
|
|
409
|
+
'Paragraph Glossary Example',
|
|
408
410
|
),
|
|
409
411
|
)
|
|
410
412
|
_EXAMPLE_REPORTS = (*(example.slug for example in _EXAMPLES), 'self-report')
|
|
@@ -470,7 +472,7 @@ def reports_current(session: nox.Session) -> None:
|
|
|
470
472
|
|
|
471
473
|
@nox.session
|
|
472
474
|
def examples(session: nox.Session) -> None:
|
|
473
|
-
"""Regenerate
|
|
475
|
+
"""Regenerate the example reports."""
|
|
474
476
|
_sync(session, include_project=True)
|
|
475
477
|
_regenerate_examples(session)
|
|
476
478
|
|
|
@@ -511,7 +513,7 @@ def _regenerate_examples(session: nox.Session) -> None:
|
|
|
511
513
|
'rendering (coffeeshop: test_failing; hotel-booking: gift-card decline case). '
|
|
512
514
|
'coffeeshop uses --given-all-frames to demonstrate the internal-frames '
|
|
513
515
|
'toggle; hotel-booking uses the default filter. '
|
|
514
|
-
'
|
|
516
|
+
'table-glossary has no intentional failures.'
|
|
515
517
|
)
|
|
516
518
|
|
|
517
519
|
|
|
@@ -539,7 +541,7 @@ def _build_docs(session: nox.Session, docs_version: str) -> None:
|
|
|
539
541
|
"""Stage the files the site embeds, then build it strictly.
|
|
540
542
|
|
|
541
543
|
The staged files are single-sourced elsewhere in the repo: the full-size
|
|
542
|
-
diagram the Home page links to (the README
|
|
544
|
+
diagram the Home page links to (derived like the README's, see `diagram`), every
|
|
543
545
|
example's report — rendered from its JSON, so its copy buttons link the
|
|
544
546
|
`docs_version` being built rather than the committed HTML's `/dev/` —
|
|
545
547
|
the two upright font faces the report package embeds (the site's italic
|
|
@@ -551,7 +553,6 @@ def _build_docs(session: nox.Session, docs_version: str) -> None:
|
|
|
551
553
|
"""
|
|
552
554
|
_sync(session, 'docs', include_project=True)
|
|
553
555
|
staged = [
|
|
554
|
-
(_DIAGRAM_README_COPY, _DOCS_SITE / 'assets' / 'pytest-given-diagram-full.svg'),
|
|
555
556
|
*(
|
|
556
557
|
(font, _DOCS_SITE / 'assets' / 'fonts' / font.name)
|
|
557
558
|
for font in sorted(_REPORT_FONTS.glob('*.woff2'))
|
|
@@ -562,6 +563,13 @@ def _build_docs(session: nox.Session, docs_version: str) -> None:
|
|
|
562
563
|
target.parent.mkdir(parents=True, exist_ok=True)
|
|
563
564
|
shutil.copyfile(source, target)
|
|
564
565
|
session.log(f'staged {source} -> {target}')
|
|
566
|
+
# The site has a theme switch, so its full-size view follows the colour scheme.
|
|
567
|
+
_DIAGRAM_FULL_SIZE.write_text(
|
|
568
|
+
_standalone_diagram(_DIAGRAM_TOKENS_LIGHT, _DIAGRAM_TOKENS_DARK),
|
|
569
|
+
encoding='utf-8',
|
|
570
|
+
newline='\n',
|
|
571
|
+
)
|
|
572
|
+
session.log(f'wrote {_DIAGRAM_FULL_SIZE}')
|
|
565
573
|
for slug in _EXAMPLE_REPORTS:
|
|
566
574
|
session.run(
|
|
567
575
|
'pytest-given',
|
|
@@ -585,11 +593,16 @@ def docs_build(session: nox.Session) -> None:
|
|
|
585
593
|
|
|
586
594
|
_DIAGRAM_SOURCE = _DOCS_SITE / 'assets' / 'pytest-given-diagram.svg'
|
|
587
595
|
_DIAGRAM_FONT = _REPORT_FONTS / 'source-sans-3-latin-wght-normal.woff2'
|
|
588
|
-
|
|
596
|
+
# The README shows the light copy (the path the released READMEs on PyPI link)
|
|
597
|
+
# and, through a <picture> <source>, the dark one. PyPI strips <source>, and its
|
|
598
|
+
# page stays light whatever the reader's colour scheme.
|
|
599
|
+
_DIAGRAM_README_LIGHT = Path('docs/pytest-given-diagram.svg')
|
|
600
|
+
_DIAGRAM_README_DARK = Path('docs/pytest-given-diagram-dark.svg')
|
|
601
|
+
_DIAGRAM_FULL_SIZE = _DOCS_SITE / 'assets' / 'pytest-given-diagram-full.svg'
|
|
589
602
|
|
|
590
603
|
# The site defines these tokens from the theme's variables (stylesheets/extra.css);
|
|
591
|
-
# the
|
|
592
|
-
#
|
|
604
|
+
# the standalone copies have no theme, so they carry the resolved values. Keep in
|
|
605
|
+
# step with extra.css.
|
|
593
606
|
_DIAGRAM_TOKENS_LIGHT = {
|
|
594
607
|
'bg': '#fff',
|
|
595
608
|
'line': 'rgba(0, 0, 0, 0.55)',
|
|
@@ -612,24 +625,40 @@ _DIAGRAM_TOKENS_DARK = {
|
|
|
612
625
|
}
|
|
613
626
|
|
|
614
627
|
|
|
615
|
-
def _token_block(tokens: dict[str, str], indent: str) -> str:
|
|
616
|
-
return ''.join(
|
|
617
|
-
f'{indent} --pg-diagram-{name}: {value};\n' for name, value in tokens.items()
|
|
618
|
-
)
|
|
619
|
-
|
|
620
|
-
|
|
621
628
|
@nox.session(venv_backend='none')
|
|
622
629
|
def diagram(session: nox.Session) -> None:
|
|
623
|
-
"""Derive the README's
|
|
630
|
+
"""Derive the README's light and dark diagrams from the site's inline SVG.
|
|
631
|
+
|
|
632
|
+
Rerun after editing the source SVG or the token lists above, and commit the
|
|
633
|
+
result.
|
|
634
|
+
"""
|
|
635
|
+
for path, tokens in (
|
|
636
|
+
(_DIAGRAM_README_LIGHT, _DIAGRAM_TOKENS_LIGHT),
|
|
637
|
+
(_DIAGRAM_README_DARK, _DIAGRAM_TOKENS_DARK),
|
|
638
|
+
):
|
|
639
|
+
path.write_text(_standalone_diagram(tokens), encoding='utf-8', newline='\n')
|
|
640
|
+
session.log(f'wrote {path}')
|
|
641
|
+
|
|
642
|
+
|
|
643
|
+
def _standalone_diagram(
|
|
644
|
+
tokens: dict[str, str], dark_tokens: dict[str, str] | None = None
|
|
645
|
+
) -> str:
|
|
646
|
+
"""The site's SVG made standalone, with `dark_tokens` under prefers-color-scheme.
|
|
624
647
|
|
|
625
648
|
On the site the SVG is inlined, so page CSS supplies the font and the colour
|
|
626
|
-
tokens;
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
or the token lists above, and commit the result.
|
|
649
|
+
tokens; an SVG shown as an image gets neither, so this embeds the Source Sans 3
|
|
650
|
+
subset the site already ships and resolves the tokens. A pure text transform:
|
|
651
|
+
same inputs, same bytes.
|
|
630
652
|
"""
|
|
631
653
|
source = _DIAGRAM_SOURCE.read_text(encoding='utf-8')
|
|
632
654
|
font = base64.b64encode(_DIAGRAM_FONT.read_bytes()).decode('ascii')
|
|
655
|
+
dark_query = (
|
|
656
|
+
''
|
|
657
|
+
if dark_tokens is None
|
|
658
|
+
else ' @media (prefers-color-scheme: dark) {\n'
|
|
659
|
+
' svg {\n' + _token_block(dark_tokens, ' ') + ' }\n'
|
|
660
|
+
' }\n'
|
|
661
|
+
)
|
|
633
662
|
standalone_style = (
|
|
634
663
|
' <style>\n'
|
|
635
664
|
' @font-face {\n'
|
|
@@ -639,12 +668,10 @@ def diagram(session: nox.Session) -> None:
|
|
|
639
668
|
' }\n'
|
|
640
669
|
' svg {\n'
|
|
641
670
|
' font-family: "Source Sans 3", system-ui, sans-serif;\n'
|
|
642
|
-
+ _token_block(
|
|
671
|
+
+ _token_block(tokens, ' ')
|
|
643
672
|
+ ' }\n'
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
' }\n'
|
|
647
|
-
' </style>\n'
|
|
673
|
+
+ dark_query
|
|
674
|
+
+ ' </style>\n'
|
|
648
675
|
)
|
|
649
676
|
header = (
|
|
650
677
|
'<!-- Generated by `nox -s diagram` from '
|
|
@@ -653,7 +680,7 @@ def diagram(session: nox.Session) -> None:
|
|
|
653
680
|
open_tag_end = source.index('>\n') + 2
|
|
654
681
|
artwork_style_end = ' </style>\n'
|
|
655
682
|
assert source.count(artwork_style_end) == 1
|
|
656
|
-
|
|
683
|
+
return (
|
|
657
684
|
header
|
|
658
685
|
+ source[:open_tag_end].replace(
|
|
659
686
|
'<svg ', '<svg xmlns="http://www.w3.org/2000/svg" ', 1
|
|
@@ -666,8 +693,12 @@ def diagram(session: nox.Session) -> None:
|
|
|
666
693
|
+ ' <rect width="1000" height="1000" fill="var(--pg-diagram-bg)"/>\n',
|
|
667
694
|
)
|
|
668
695
|
)
|
|
669
|
-
|
|
670
|
-
|
|
696
|
+
|
|
697
|
+
|
|
698
|
+
def _token_block(tokens: dict[str, str], indent: str) -> str:
|
|
699
|
+
return ''.join(
|
|
700
|
+
f'{indent} --pg-diagram-{name}: {value};\n' for name, value in tokens.items()
|
|
701
|
+
)
|
|
671
702
|
|
|
672
703
|
|
|
673
704
|
@nox.session
|
|
@@ -697,7 +728,8 @@ def docs_deploy(session: nox.Session) -> None:
|
|
|
697
728
|
def self_report(session: nox.Session) -> None:
|
|
698
729
|
"""Regenerate the self-documentation report from pytest-given's own backend
|
|
699
730
|
tests. The @scenario-decorated unit tests narrate the plugin's behavior in
|
|
700
|
-
the vocabulary of GLOSSARY.md
|
|
731
|
+
the vocabulary of GLOSSARY.md, loaded as a TableGlossary in
|
|
732
|
+
tests/ubiquitous_language.py.
|
|
701
733
|
"""
|
|
702
734
|
_sync(session, 'test', include_project=True)
|
|
703
735
|
_regenerate_self_report(session)
|