pytest-given 0.4.1__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.
Files changed (216) hide show
  1. {pytest_given-0.4.1 → pytest_given-0.5.1}/AGENTS.md +29 -27
  2. {pytest_given-0.4.1 → pytest_given-0.5.1}/CHANGELOG.md +74 -1
  3. {pytest_given-0.4.1 → pytest_given-0.5.1}/GLOSSARY.md +39 -31
  4. {pytest_given-0.4.1 → pytest_given-0.5.1}/PKG-INFO +21 -9
  5. {pytest_given-0.4.1 → pytest_given-0.5.1}/README.md +18 -8
  6. {pytest_given-0.4.1 → pytest_given-0.5.1}/docs/site/configuration/narration-lint.md +10 -5
  7. {pytest_given-0.4.1 → pytest_given-0.5.1}/noxfile.py +173 -45
  8. {pytest_given-0.4.1 → pytest_given-0.5.1}/pyproject.toml +14 -3
  9. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md +54 -0
  10. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md +57 -0
  11. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md +85 -0
  12. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/lint.md +21 -0
  13. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/parameter-tables.md +12 -0
  14. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md +86 -0
  15. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/stories.md +75 -0
  16. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-citing/SKILL.md +59 -0
  17. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-citing/references/repair.md +11 -0
  18. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md +46 -0
  19. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-navigating/references/report-json.md +116 -0
  20. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-reviewing/SKILL.md +99 -0
  21. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-reviewing/references/completeness.md +22 -0
  22. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-reviewing/references/hygiene.md +9 -0
  23. pytest_given-0.5.1/src/pytest_given/.agents/skills/pytest-given-reviewing/references/story-coverage.md +36 -0
  24. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/collector.py +11 -11
  25. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/file_glossary.py +2 -2
  26. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/glossary.py +44 -6
  27. pytest_given-0.5.1/src/pytest_given/capture/markdown_glossary.py +121 -0
  28. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/process_state.py +5 -4
  29. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/scenario.py +14 -14
  30. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/steps.py +10 -5
  31. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/story.py +5 -5
  32. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/template.py +70 -24
  33. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/traceback.py +1 -0
  34. pytest_given-0.5.1/src/pytest_given/citations/__init__.py +14 -0
  35. pytest_given-0.5.1/src/pytest_given/citations/check.py +702 -0
  36. pytest_given-0.5.1/src/pytest_given/citations/markdown_links.py +283 -0
  37. pytest_given-0.5.1/src/pytest_given/citations/narrated.py +342 -0
  38. pytest_given-0.5.1/src/pytest_given/citations/targets.py +148 -0
  39. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/cli/__init__.py +4 -0
  40. pytest_given-0.5.1/src/pytest_given/cli/citations.py +142 -0
  41. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/cli/report.py +46 -28
  42. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/cli/skills.py +21 -7
  43. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/grouping/checks.py +52 -21
  44. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/grouping/columns.py +6 -2
  45. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/grouping/context.py +4 -5
  46. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/grouping/group.py +24 -26
  47. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/grouping/percase.py +17 -10
  48. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/grouping/templatize.py +14 -12
  49. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/lint/__init__.py +2 -2
  50. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/lint/ast_rules.py +145 -40
  51. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/lint/base.py +8 -6
  52. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/lint/config.py +20 -10
  53. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/lint/runner.py +2 -2
  54. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/lint/runtime_rules.py +14 -14
  55. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/lint/summary.py +8 -10
  56. pytest_given-0.5.1/src/pytest_given/markdown/__init__.py +62 -0
  57. pytest_given-0.5.1/src/pytest_given/markdown/blocks.py +355 -0
  58. pytest_given-0.5.1/src/pytest_given/markdown/plain_text.py +68 -0
  59. pytest_given-0.5.1/src/pytest_given/markdown/spans.py +119 -0
  60. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/model/__init__.py +33 -6
  61. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/model/narration.py +68 -3
  62. pytest_given-0.5.1/src/pytest_given/model/report_url.py +43 -0
  63. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/model/runtime.py +3 -1
  64. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/model/schema.py +62 -11
  65. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/model/serde.py +55 -3
  66. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/model/text.py +22 -15
  67. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/plugin/__init__.py +2 -1
  68. pytest_given-0.5.1/src/pytest_given/plugin/case_ids.py +99 -0
  69. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/plugin/collection.py +23 -4
  70. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/plugin/fixtures.py +16 -15
  71. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/plugin/options.py +92 -16
  72. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/plugin/runtest.py +34 -6
  73. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/plugin/session.py +89 -20
  74. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/plugin/state.py +20 -6
  75. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/__init__.py +26 -0
  76. pytest_given-0.5.1/src/pytest_given/report/citation_index.py +237 -0
  77. pytest_given-0.5.1/src/pytest_given/report/console.py +12 -0
  78. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/coverage.py +1 -1
  79. pytest_given-0.5.1/src/pytest_given/report/function_source.py +90 -0
  80. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/glossary_view.py +38 -25
  81. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/html_renderer.py +104 -27
  82. pytest_given-0.5.1/src/pytest_given/report/inline_markdown.py +54 -0
  83. pytest_given-0.5.1/src/pytest_given/report/link_text.py +38 -0
  84. pytest_given-0.5.1/src/pytest_given/report/markdown_writer.py +105 -0
  85. pytest_given-0.5.1/src/pytest_given/report/md_renderer.py +379 -0
  86. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/sinks.py +40 -18
  87. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/slugs.py +34 -17
  88. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/source_link.py +20 -1
  89. pytest_given-0.5.1/src/pytest_given/report/staged_write.py +41 -0
  90. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/story_view.py +16 -8
  91. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/templates/_macros.html.j2 +64 -21
  92. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/templates/app.js +248 -50
  93. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/templates/report.html.j2 +70 -14
  94. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/templates/styles.css +172 -11
  95. pytest_given-0.5.1/src/pytest_given/report/text.py +33 -0
  96. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/integration/test_cli.py +113 -3
  97. pytest_given-0.5.1/tests/integration/test_cli_citations.py +460 -0
  98. pytest_given-0.5.1/tests/integration/test_lazy_imports.py +25 -0
  99. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/integration/test_plugin.py +817 -190
  100. pytest_given-0.5.1/tests/integration/test_plugin_file_glossary.py +60 -0
  101. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/integration/test_plugin_lint.py +75 -56
  102. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/integration/test_skills_cli.py +75 -0
  103. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/ubiquitous_language.py +8 -5
  104. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_collector.py +80 -88
  105. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_file_glossary.py +53 -51
  106. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_glossary.py +93 -70
  107. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_kind_inference.py +35 -36
  108. pytest_given-0.5.1/tests/unit/capture/test_markdown_glossary.py +265 -0
  109. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_step_descriptor.py +62 -38
  110. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_story.py +76 -82
  111. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_template.py +85 -26
  112. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_traceback_parser.py +1 -0
  113. pytest_given-0.5.1/tests/unit/citation_reports.py +78 -0
  114. pytest_given-0.5.1/tests/unit/citations/fixtures/citation-forms.md +32 -0
  115. pytest_given-0.5.1/tests/unit/citations/test_check.py +1611 -0
  116. pytest_given-0.5.1/tests/unit/citations/test_markdown_links.py +316 -0
  117. pytest_given-0.5.1/tests/unit/citations/test_markdown_links_oracle.py +100 -0
  118. pytest_given-0.5.1/tests/unit/citations/test_narrated.py +290 -0
  119. pytest_given-0.5.1/tests/unit/citations/test_targets.py +130 -0
  120. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/lint/test_ast_rules.py +261 -31
  121. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/lint/test_config.py +34 -7
  122. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/lint/test_runtime_rules.py +26 -27
  123. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/lint/test_summary.py +7 -3
  124. pytest_given-0.5.1/tests/unit/markdown/test_blocks.py +189 -0
  125. pytest_given-0.5.1/tests/unit/markdown/test_plain_text.py +29 -0
  126. pytest_given-0.5.1/tests/unit/markdown/test_spans.py +134 -0
  127. pytest_given-0.5.1/tests/unit/model/__init__.py +0 -0
  128. pytest_given-0.5.1/tests/unit/model/test_narration.py +120 -0
  129. pytest_given-0.5.1/tests/unit/model/test_report_url.py +38 -0
  130. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/model/test_schema.py +47 -4
  131. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/model/test_serde.py +117 -3
  132. pytest_given-0.5.1/tests/unit/model/test_text.py +60 -0
  133. pytest_given-0.5.1/tests/unit/report/__init__.py +0 -0
  134. pytest_given-0.5.1/tests/unit/report/app_data.py +23 -0
  135. pytest_given-0.5.1/tests/unit/report/test_citation_index.py +288 -0
  136. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_coverage.py +104 -97
  137. pytest_given-0.5.1/tests/unit/report/test_function_source.py +124 -0
  138. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_glossary_view.py +111 -38
  139. pytest_given-0.5.1/tests/unit/report/test_html_renderer.py +2089 -0
  140. pytest_given-0.5.1/tests/unit/report/test_inline_markdown.py +130 -0
  141. pytest_given-0.5.1/tests/unit/report/test_link_text.py +83 -0
  142. pytest_given-0.5.1/tests/unit/report/test_markdown_writer.py +210 -0
  143. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_md_renderer.py +633 -116
  144. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_sinks.py +87 -23
  145. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_slugs.py +31 -2
  146. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_source_link.py +33 -6
  147. pytest_given-0.5.1/tests/unit/report/test_staged_write.py +22 -0
  148. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_story_view.py +14 -20
  149. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/test_grouping.py +364 -171
  150. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/test_percase.py +55 -21
  151. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/test_plugin.py +223 -3
  152. pytest_given-0.5.1/tests/unit/test_project_glossary.py +38 -0
  153. pytest_given-0.5.1/tests/unit/test_quickstart.py +35 -0
  154. pytest_given-0.5.1/tests/unit/test_skills_data.py +115 -0
  155. pytest_given-0.5.1/uv.lock +1400 -0
  156. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md +0 -52
  157. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md +0 -59
  158. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/domain-storytelling.md +0 -35
  159. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/glossaries.md +0 -82
  160. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md +0 -105
  161. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-authoring/references/stories.md +0 -76
  162. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-navigating/SKILL.md +0 -41
  163. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-navigating/references/report-json.md +0 -117
  164. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-reviewing/SKILL.md +0 -71
  165. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-reviewing/references/pairs.md +0 -65
  166. pytest_given-0.4.1/src/pytest_given/.agents/skills/pytest-given-reviewing/references/story-coverage.md +0 -29
  167. pytest_given-0.4.1/src/pytest_given/capture/markdown_glossary.py +0 -175
  168. pytest_given-0.4.1/src/pytest_given/report/inline_markdown.py +0 -51
  169. pytest_given-0.4.1/src/pytest_given/report/md_renderer.py +0 -289
  170. pytest_given-0.4.1/src/pytest_given/report/text.py +0 -24
  171. pytest_given-0.4.1/tests/integration/test_plugin_file_glossary.py +0 -42
  172. pytest_given-0.4.1/tests/unit/capture/test_markdown_glossary.py +0 -297
  173. pytest_given-0.4.1/tests/unit/model/test_narration.py +0 -15
  174. pytest_given-0.4.1/tests/unit/model/test_text.py +0 -22
  175. pytest_given-0.4.1/tests/unit/report/test_html_renderer.py +0 -2371
  176. pytest_given-0.4.1/tests/unit/report/test_inline_markdown.py +0 -39
  177. pytest_given-0.4.1/tests/unit/test_skills_data.py +0 -67
  178. pytest_given-0.4.1/tests/unit/test_skills_scripts.py +0 -100
  179. pytest_given-0.4.1/uv.lock +0 -1206
  180. {pytest_given-0.4.1 → pytest_given-0.5.1}/.gitignore +0 -0
  181. {pytest_given-0.4.1 → pytest_given-0.5.1}/LICENSE.md +0 -0
  182. {pytest_given-0.4.1 → pytest_given-0.5.1}/THIRD-PARTY-LICENSES +0 -0
  183. {pytest_given-0.4.1 → pytest_given-0.5.1}/conftest.py +0 -0
  184. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/__init__.py +0 -0
  185. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/__init__.py +0 -0
  186. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/discovery.py +0 -0
  187. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/kind_inference.py +0 -0
  188. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/capture/source.py +0 -0
  189. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/grouping/__init__.py +0 -0
  190. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/grouping/attachments.py +0 -0
  191. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/model/errors.py +0 -0
  192. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/model/steps.py +0 -0
  193. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/py.typed +0 -0
  194. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/palette.py +0 -0
  195. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/templates/alpine.min.js +0 -0
  196. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/templates/fonts/source-code-pro-latin-wght-normal.woff2 +0 -0
  197. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/templates/fonts/source-sans-3-latin-wght-normal.woff2 +0 -0
  198. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/templates/logo.svg +0 -0
  199. {pytest_given-0.4.1 → pytest_given-0.5.1}/src/pytest_given/report/theme.py +0 -0
  200. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/__init__.py +0 -0
  201. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/conftest.py +0 -0
  202. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/integration/__init__.py +0 -0
  203. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/integration/test_plugin_session_isolation.py +0 -0
  204. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/__init__.py +0 -0
  205. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/__init__.py +0 -0
  206. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_discovery.py +0 -0
  207. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_rootdir_isolation.py +0 -0
  208. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/capture/test_source.py +0 -0
  209. {pytest_given-0.4.1/tests/unit/lint → pytest_given-0.5.1/tests/unit/citations}/__init__.py +0 -0
  210. {pytest_given-0.4.1/tests/unit/model → pytest_given-0.5.1/tests/unit/lint}/__init__.py +0 -0
  211. {pytest_given-0.4.1/tests/unit/report → pytest_given-0.5.1/tests/unit/markdown}/__init__.py +0 -0
  212. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/model/test_errors.py +0 -0
  213. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/model/test_steps.py +0 -0
  214. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_palette.py +0 -0
  215. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/report/test_theme.py +0 -0
  216. {pytest_given-0.4.1 → pytest_given-0.5.1}/tests/unit/test_plugin_traceback.py +0 -0
@@ -16,21 +16,23 @@ uv sync --group dev
16
16
 
17
17
  ## Quality gates
18
18
 
19
- `uv run nox` runs the default gate — `format`, `lint`, `mypy`, `test`, `coverage` (a 100% target), `audit` (a `pip-audit` of the locked dependencies). **Run it (or at minimum `uv run nox -s format lint mypy test`) before every commit.** The sessions below are on-demand; list them all with `uv run nox -l`.
19
+ `uv run nox` runs the default gate — `format`, `lint`, `mypy`, `test`, `coverage` (a 100% target), `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 test`) before every commit.** The sessions below are on-demand; list them all with `uv run nox -l`.
20
20
 
21
- - `uv run nox -s examples` regenerates the JSON, HTML, and Markdown files under `examples/coffeeshop/`, `examples/hotel-booking/`, and `examples/file-glossary-booking/`. Run after changes to the renderer, templates, plugin output schema, or any example test file, and commit the updated outputs.
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.
23
23
  - **Only commit a regenerated report when its *content* actually changed.**
24
24
  - Every regeneration rewrites `commit_sha` (to current HEAD, including the SHA-pinned source-link URLs), `timestamp`, and `duration_ms` in the JSON and HTML, so a report your change didn't really touch still shows a diff — `git checkout` those files rather than committing the noise.
25
- - **Read the `.md` diff first**: the Markdown carries none of those fields, so it is the behavioral delta of your change in prose. An unchanged `.md` doesn't by itself prove the JSON/HTML are noise-only (glossary and story data never surface in the Markdown); a shifted source line does show up, in the `relpath:line::test_name` anchor under every heading.
26
- - Regenerate only the reports a change can affect — `examples` narrates `examples/**`, `self_report` narrates `tests/**`, and a renderer or template change affects all of them. A shifted line number in a decorated backend test is therefore a real self-report change worth committing, even when no example changed.
27
- - Both regeneration sessions run the narration lint (`--given-lint`; see [Narration lint](docs/site/configuration/narration-lint.md) and the [design spec](docs/specs/2026-07-05-narration-lint-design.md)). `self_report` fails on any lint error — a real gate, keep the backend suite lint-clean. `examples` tolerates exit 1 for its intentional failures, which masks the lint exit code, so read the printed "narration lint" summary there. A step the lint mis-flags goes on the `given_lint_ignore` list (stale entries fail the run); the rule catalog and ignore mechanics are in the [authoring skill](src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md) under "Mechanical counterparts", and the honest-two-phase test an ignored `missing-phase` has to pass under "Phase structure".
25
+ - **Read the `.md` diff first**: the Markdown carries none of those fields, so it is the behavioral delta of your change in prose. An unchanged `.md` doesn't by itself prove the JSON/HTML are noise-only (glossary and story data never surface in the Markdown, nor do anchor lines: `given_md_lines = false`). A test that only moved is noise; its SHA-pinned source link still points right.
26
+ - Regenerate only the reports a change can affect — `examples` narrates `examples/**`, `self_report` narrates `tests/**`, and a renderer or template change affects all of them.
27
+ - `uv run nox -s reports_current` is CI's check that a change regenerated what it should: it runs both regeneration sessions and fails if any tracked `.md` changed — a report's Markdown or a document whose citations moved. Locally it leaves the regenerated files behind, to commit or `git checkout`.
28
+ - Both regeneration sessions also run `pytest-given citations update` — `self_report` over `docs/specs/`, both over `docs/site/` — so commit the documents they change with the report.
29
+ - Both regeneration sessions run the narration lint (`--given-lint`; see [Narration lint](docs/site/configuration/narration-lint.md) and the [design spec](docs/specs/2026-07-05-narration-lint-design.md)). `self_report` fails on any lint error — a real gate, keep the backend suite lint-clean. `examples` tolerates exit 1 for its intentional failures, which masks the lint exit code, so read the printed "narration lint" summary there. A step the lint mis-flags goes on the `given_lint_ignore` list (stale entries fail the run); the rule catalog, ignore mechanics, and when an ignored `missing-phase` is justified are in the authoring skill's [lint.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/lint.md).
28
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.
29
- - `uv run nox -s compat` runs the suite on Python 3.14 and 3.15, each against pytest 9.0.x (the dependency floor) and the newest pytest. The default gate tests only the locked pytest on 3.14, so this is the only check of the floor and of 3.15. The manually dispatched [Compat workflow](.github/workflows/compat.yml) runs it on Linux and Windows before every release (see [docs/releasing.md](docs/releasing.md)).
30
- - `uv run nox -s build` builds the wheel + sdist and verifies them as a consumer would — `py.typed`, templates and bundled skills present, a real scenario run from a throwaway install, and [library-skills](https://library-skills.io) discovery of every bundled skill. 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.
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
+ - `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.
31
33
  - `uv run nox -s docs_build` builds the documentation site under `site/` with `zensical build --strict`; run it after changing anything under `docs/site/` (a broken cross-page link fails it) and preview with `uv run --group docs zensical serve`. `docs_deploy` is the CI-only counterpart that publishes with mike — see [docs/releasing.md](docs/releasing.md#documentation-site).
32
- - Zensical builds every file in `docs/site/` and cannot exclude any, so single-sourced files get in by copy or include: the build copies the four example reports, the full-size diagram, and the report package's upright fonts and logo into gitignored spots there; `CHANGELOG.md` (between its `site` markers) and the Home-page diagram (`docs/site/assets/pytest-given-diagram.svg`, inlined so page CSS can theme it) are `pymdownx.snippets` includes.
33
- - `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 or its tokens, run `uv run nox -s diagram` and commit the result.
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.
34
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`.
35
37
 
36
38
  ## Releasing
@@ -39,37 +41,36 @@ Releases go to PyPI via a manually dispatched [Release workflow](.github/workflo
39
41
 
40
42
  ## Architecture
41
43
 
42
- `src/pytest_given/` is five library subpackages plus two entry points, with a
44
+ `src/pytest_given/` is seven library subpackages plus two entry points, with a
43
45
  strict dependency direction (convention, not lint-enforced):
44
46
 
45
47
  ```
46
- model/ the leaf — schema, serde, errors, shared text rules
48
+ markdown/ the leaf — reading Markdown: blocks, tables, inline spans
49
+ model/ schema, serde, errors, shared text rules
47
50
  capture/ lint/ report/ each on model/ only, never on each other
48
51
  grouping/ on model/ + capture/
49
- plugin/ cli/ the entry points; may import all five, and hold
50
- nothing the five could
52
+ citations/ on model/ + report/
53
+ plugin/ cli/ the entry points; may import all seven, and hold
54
+ nothing the seven could
51
55
  ```
52
56
 
57
+ Every package may import `markdown/`, which imports none of them.
58
+
53
59
  What no filename tells you:
54
60
 
55
61
  - `grouping/` — the parametrize pass: a scenario's cases collapsed into one
56
62
  narrated tree plus a parameter table, refusing the authoring forms that would
57
63
  make that tree lie. Runs at session finish *before* the sinks are written, so
58
64
  a bare `pytest` failing on one is the point, not a side effect.
59
- - `plugin/__init__.py` is the hook surface pluggy registers — the `pytest11`
60
- entry point is the package, and pluggy scans a module's attributes for
61
- `pytest_*` names, so the re-exports there *are* the registration.
62
65
  - `capture/` imports pytest nowhere, so all of it is unit-testable without a
63
66
  session; a stray step warns with `model.PytestGivenWarning`, not pytest's.
64
- - `Glossary` exists twice on purpose: `model/schema.py` holds the storage the
65
- report carries and serde rebuilds, and `capture/glossary.py` subclasses it
66
- with the registration API, which needs a caller source location that the leaf
67
- may not reach for. `pytest_given.Glossary` is the subclass; everything
68
- internal annotates the base. `LookupGlossary` sits between them and owns the
69
- `g['Guest']` read-back both user-facing glossaries share.
67
+ - `citations/` reads and edits the user's Markdown documents; what a citation
68
+ should say is `report`'s `CitationIndex`, since the HTML's copy buttons write
69
+ the same lines.
70
70
  - Each package exposes the *whole* job, not its parts: `report.emit_sinks`
71
71
  (render → write → discard-on-failure, so a failure leaves no half-written
72
- report) and `lint.run_lint`. Both entry points reach the sinks through
72
+ report), `lint.run_lint` and `citations.check_citations` (every document
73
+ read before any is written). Both entry points reach the sinks through
73
74
  `emit_sinks`, which is what keeps `pytest-given report` behaving like the
74
75
  plugin; the lint is the plugin's alone, since the CLI re-renders a report
75
76
  rather than running a suite.
@@ -90,7 +91,6 @@ Any change to `report/templates/` (Jinja, CSS, `app.js`) or the `narration` filt
90
91
  - **No TDD for frontend changes**: apply the change, regenerate `examples/`, drive it in Playwright, capture the result.
91
92
  - Open e.g. `examples/coffeeshop/coffeeshop.html` (regenerate via `uv run nox -s examples`) with the Playwright MCP server, check `browser_console_messages` for errors after init, then drive the changed surface (hover, click, URL hash). Use `browser_snapshot` (not screenshots) to read page content and interact with elements.
92
93
  - Desktop only — assume a minimum viewport width of ~900px.
93
- - Traceback display and header metadata formatting are known limitations, not current priorities.
94
94
  - Never save Playwright screenshots into the project directory — use the session scratchpad or omit the `filename` parameter.
95
95
 
96
96
  **Setup and known traps** (`.mcp.json`, the `file://` page cache, browser installs) live in [docs/playwright-setup.md](docs/playwright-setup.md). `.mcp.json` is read at **session start**, so check that the `browser_*` tools exist before planning a task that ends in Playwright verification.
@@ -99,7 +99,7 @@ Any change to `report/templates/` (Jinja, CSS, `app.js`) or the `narration` filt
99
99
 
100
100
  The narration rules live in the **`pytest-given-authoring` skill**, whose canonical source is [src/pytest_given/.agents/skills/](src/pytest_given/.agents/skills/pytest-given-authoring/SKILL.md) — every link in this document points there. The copy under `.claude/skills/` is a mirror: after editing the canonical copy, regenerate it with `uv run pytest-given skills install` and commit both (a sync test fails otherwise).
101
101
 
102
- **The skill is documentation with the same sync duty as the site** — downstream agents read it instead of the site, version-matched from the wheel. A change to the public API surface or its rules updates the site page under `docs/site/` *and* [references/api.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md); a change to narration/lint semantics updates [references/scenarios.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md) and friends. No check catches prose drift between the site and the skill, so ask "does the skill need this too?" on every user-facing change; only the `python` blocks are covered — `tests/unit/test_skills_scripts.py` runs each against a report built from the model. The reviewing skill restates authoring rules as rubrics, so they share the same duty: its layer 2 mirrors `scenarios.md` ("Keeping it truthful", "Expected raises", "Vocabulary and tags"), and its layer 4 mirrors `glossaries.md` ("Keeping the glossary honest") and `stories.md` — change one, change both.
102
+ **The skill is documentation with the same sync duty as the site** — downstream agents read it instead of the site, version-matched from the wheel. A change to the public API surface or its rules updates the site page under `docs/site/` *and* [references/api.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/api.md); a change to narration/lint semantics updates [references/scenarios.md](src/pytest_given/.agents/skills/pytest-given-authoring/references/scenarios.md) and friends. No check catches prose drift between the site and the skill, so ask "does the skill need this too?" on every user-facing change. The reviewing skill restates the authoring skill's rules as rubrics, so they share the same duty — change one, change both.
103
103
 
104
104
  Narration drifts like any other prose — the lint catches several ways step text and body can part company, not all of them — which is why [Quality gates](#quality-gates) has you read the regenerated `.md` rather than trust the text.
105
105
 
@@ -114,9 +114,11 @@ What is specific to this repo's self-report:
114
114
 
115
115
  - 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
116
  - **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 `FileGlossary` both carry no such subclass.
117
118
  - Avoid `Any` — use precise types, generics, `TYPE_CHECKING` imports, or `ContextVar[T]` over untyped `threading.local`.
118
119
  - 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.
119
- - Only module-level imports — no inline/function-level imports.
120
+ - Every package `src/` imports is a declared dependency in `pyproject.toml`, even one another dependency already brings in.
121
+ - 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).
120
122
  - **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).
121
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.
122
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).
@@ -129,4 +131,4 @@ What is specific to this repo's self-report:
129
131
  - **A user-facing change adds its `CHANGELOG.md` entry in the same commit**, under `## [Unreleased]`, in the fitting Keep a Changelog category (each category appears at most once per version — extend the existing heading rather than adding a second one). User-facing = public API, CLI flags, report output, lint rules, bundled skills; internal work (refactors, tests, CI, contributor docs) gets no entry.
130
132
  - **One sentence per entry**, written for someone upgrading: name the symbol, flag, or surface and say what changed — no rationale, measurements, or before/after detail. Only a breaking change earns more: the migration it needs. Visual and interaction polish gets one collective bullet per release ("the sidebar and its chips are visually tidied"), never a bullet per restyled element; accessibility fixes stay on their own line. When in doubt, the shorter entry is the right one.
131
133
  - Plan files under `docs/superpowers/plans/` are gitignored scratch; spec files under `docs/specs/` are committed.
132
- - New specs land under `docs/specs/proposed/`. When a spec's implementation lands, `git mv` it up one level into `docs/specs/` in the same commit, and fix its relative links in the same edit — a `../`-prefixed link to a sibling spec resolves into `docs/` once the file moves. `ls docs/specs/proposed` is the canonical list of outstanding design work.
134
+ - New specs land under `docs/specs/proposed/`. When a spec's implementation lands — its citations all read ✅ — `git mv` it up one level into `docs/specs/` in the same commit, and fix its relative links in the same edit — a `../`-prefixed link to a sibling spec resolves into `docs/` once the file moves. `ls docs/specs/proposed` is the canonical list of outstanding design work.
@@ -11,6 +11,77 @@ 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
+
46
+ ## [0.5.0] - 2026-10-18
47
+
48
+ ### Added
49
+
50
+ - Markdown documents, such as design specs, can [cite](https://nwilbert.github.io/pytest-given/0.5/guide/citations/) scenarios, tags and stories as links into the published HTML report: `--given-report-url` or the `given_report_url` setting sets the report's URL and gives it buttons that copy a citation, `pytest-given citations check` and `pytest-given citations update` keep a document's citations in line with a JSON report, a scenario's narration in a `<details markdown="1">` block included, `citations check --list` prints every report link with its findings, narrowed by `--covering` to the links that [cite a scenario](https://nwilbert.github.io/pytest-given/0.5/guide/citations/#finding-the-citations-of-a-scenario), and the bundled `pytest-given-citing` skill writes citations and repairs the ones `citations update` cannot.
51
+ - When a link into the HTML report points at a scenario, tag or other filter the report no longer has, the report warns that the link is out of date, names what is missing, and ignores it.
52
+ - A [term ref](https://nwilbert.github.io/pytest-given/0.5/guide/glossary/#term-refs) can show a noun's plural or a verb's -s form with `.s`: `room.s` reads *Rooms*, `room.l.s` reads *rooms*, and `room('suite').s` reads *suites*.
53
+ - Every `@scenario` test carries the registered `pytest_given` marker, so `pytest -m pytest_given` [runs the scenarios alone](https://nwilbert.github.io/pytest-given/0.5/configuration/pytest-options/#selecting-scenarios), for example to measure their code coverage.
54
+ - `pytest-given report --report-url` re-renders a saved report for a URL other than the one stored in it.
55
+ - The `given_md_lines = false` setting, or `--no-given-md-lines` (`--no-lines` on `pytest-given report`), leaves the line number out of each Markdown scenario anchor.
56
+ - `--given-md-source` ends each scenario in the Markdown report with its test function, under its line numbers.
57
+ - The [narration lint](https://nwilbert.github.io/pytest-given/0.5/configuration/narration-lint/#rules)'s `conditional-check` rule (default `warn`) flags a `then` whose checks all sit under an `if`, a loop, a `match` or an `except`.
58
+ - Scenario titles and step text render `**bold**`, `*italic*` and `` `code` `` in the HTML report.
59
+ - A [parameter table](https://nwilbert.github.io/pytest-given/0.5/guide/parametrized/#grouping) starts with a `case ID` column when any case ID is custom, and each case in the JSON report's `parameters.cases[]` carries its node ID as `id` and a `custom_id` flag.
60
+ - A Tags sidebar row in the HTML report has a copy button for the tag's link and citation.
61
+
62
+ ### Changed
63
+
64
+ - The Markdown report indents nested steps and attachments by four spaces.
65
+ - **Breaking.** `@scenario`'s first parameter is now `title`: replace `@scenario(name=...)` with `@scenario(title=...)`; a positional title is unaffected.
66
+ - **Breaking.** `FileGlossary`'s `description_column` is now `definition_column`, the word the rest of the glossary API uses: rename the keyword.
67
+ - **Breaking.** A handle's `.low` form is now `.l`, and lowercases only capitalized words, so an acronym keeps its case (`LLM Call` reads *LLM call*): replace `.low` with `.l`.
68
+ - **Breaking.** Glossary definitions render emphasis as CommonMark does, so `__bold__` no longer renders and `FileGlossary` no longer unwraps it in term and kind cells: write `**bold**`.
69
+ - **Breaking.** A title or step whose code span, bold or italics holds a value, placeholder or term ref raises `PytestGivenError`, and so do asterisks meant literally around one, as in `t'**/{d}/**'`: keep the span within the text beside it, and put a literal `*` in a code span of its own.
70
+ - The Glossary tab lists a term's instances and other wordings under one "Other forms" label, leaving out a term ref that reads as its S-form.
71
+ - The Markdown report and citations escape Markdown in all text except a title's or step's own formatting, and show a newline in a title or step as a space.
72
+ - A per-case scenario title highlights its case ID as a value, and the JSON report records it as a value part.
73
+ - The HTML report's top bar, term ref underlines, copy buttons and sidebar are visually tidied.
74
+ - The bundled skills are reworded in plainer language and load their lint catalog, parameter-table guidance and audits from reference files only when a task needs them.
75
+ - The bundled `pytest-given-authoring` skill covers scenario titles, parameter-table outcomes, custom case IDs and glossary definitions, and `pytest-given-reviewing` checks for each of them and starts its completeness audit from what the project promises.
76
+ - A `--given-lint` run that finds nothing prints `pytest-given: narration lint (no findings)`.
77
+ - pytest-given now depends on markdown-it-py.
78
+ - `FileGlossary` reads the tables a GFM renderer shows, so it reads a table in a blockquote or list, skips one in an indented code or HTML block, and reads a cell missing from a row as empty instead of raising.
79
+
80
+ ### Fixed
81
+
82
+ - Notes below a parameter table in the Markdown report that would share a key add their row number.
83
+ - The narration lint checks a test file with an encoding declaration, such as `# -*- coding: latin-1 -*-`, instead of skipping it.
84
+
14
85
  ## [0.4.1] - 2026-10-04
15
86
 
16
87
  ### Fixed
@@ -394,7 +465,9 @@ First public release.
394
465
  - Bundled authoring, navigating, and reviewing skills for AI agents, shipped in
395
466
  the wheel and version-matched to the plugin.
396
467
 
397
- [Unreleased]: https://github.com/nwilbert/pytest-given/compare/v0.4.1...HEAD
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
470
+ [0.5.0]: https://github.com/nwilbert/pytest-given/compare/v0.4.1...v0.5.0
398
471
  [0.4.1]: https://github.com/nwilbert/pytest-given/compare/v0.4.0...v0.4.1
399
472
  [0.4.0]: https://github.com/nwilbert/pytest-given/compare/v0.3.0...v0.4.0
400
473
  [0.3.0]: https://github.com/nwilbert/pytest-given/compare/v0.2.0...v0.3.0
@@ -11,11 +11,12 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
11
11
  | Term | Meaning |
12
12
  |---|---|
13
13
  | **Scenario** | A test function decorated with `@scenario(...)`. Not every pytest test is a scenario — undecorated tests are tolerated but not collected. |
14
- | **Step** | A unit of narration: a `with given(...)` / `when(...)` / `then(...)` block, or the root recording from a step fixture. Steps nest, and each carries a phase, narration, attachments and children — but no status or error of its own: a failure is recorded on the *Scenario*, and per *Case* on the *Parameter table*, which is where both renderers read it. |
15
- | **Narration** | The human-readable text on a step or scenario name. A `Narration` bundles the flat rendered `text` with `parts` — empty for plain-string authoring, and for a t-string or `pytest_given.Template` a list of `NarrationLiteral` / `NarrationValue` / `NarrationPlaceholder` / `NarrationTermRef` pieces. The structured form lets the templatizer and renderer treat parametrize-bound values specially without regex tricks. |
14
+ | **Scenario title** | The text `@scenario` takes first: the statement of the rule a *Scenario* demonstrates, shown as its heading in the report. A plain string, a t-string of glossary handles, or a `Template` filled per *Case*; recorded as the scenario's *Narration*. Not the test function's name, which the node ID carries. |
15
+ | **Step** | A unit of narration: a `with given(...)` / `when(...)` / `then(...)` block, or the root recording from a step fixture. Steps nest, and each carries a phase, narration, attachments and children — but no status or error of its own: a failure is recorded on the *Scenario*, and per *Case* on the *Parameter table*. |
16
+ | **Narration** | The human-readable text on a step or scenario title. A `Narration` bundles the flat rendered `text` with `parts` — empty for plain-string authoring, and for a t-string or `pytest_given.Template` a list of `NarrationLiteral` / `NarrationValue` / `NarrationPlaceholder` / `NarrationTermRef` pieces. |
16
17
  | **Phase** | The category of a step: `given`, `when`, or `then`. A step has exactly one phase. |
17
18
  | **when_then** | A step-authoring helper that emits a `when` action and its `then` outcome as two sibling steps from a single `with` block. Used mainly to narrate an expected raise (`with when_then('the action', 'the error is raised'), pytest.raises(...)`), so the action and its outcome stay distinct steps. |
18
- | **Tag** | Free-form string label attached via `@scenario(name, tags=[...])`. Used by the report's filter UI, where a `/` nests it (`ticket/ABC-123` under `ticket`) and selecting a prefix filters to every tag beneath it. |
19
+ | **Tag** | Free-form string label attached via `@scenario(title, tags=[...])`. A `/` nests it: `ticket/ABC-123` sits under `ticket`. |
19
20
  | **Attachment** | A labeled blob (text or JSON) bound to the currently-active step via `attach(label, content)`. |
20
21
 
21
22
  ## Parametrization
@@ -23,28 +24,30 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
23
24
  | Term | Meaning |
24
25
  |---|---|
25
26
  | **Parametrized scenario** | A `@scenario`-decorated test that also carries `@pytest.mark.parametrize(...)`. Produces multiple scenario records during a run; pytest-given groups them. |
26
- | **Case** | One row of a parametrized scenario — a single tuple of parameter values, its status, and any error. |
27
- | **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). Appears in the report below the grouped-template steps. |
27
+ | **Case** | One row of a parametrized scenario — its node ID, a single tuple of 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 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). |
28
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. |
29
- | **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. |
30
32
 
31
33
  ## Fixtures and recording
32
34
 
33
35
  | Term | Meaning |
34
36
  |---|---|
35
37
  | **Step fixture** | A pytest fixture whose function is wrapped with `@given(text)`. Only `@given` is allowed on fixtures; `@when` / `@then` are rejected. |
36
- | **Plain fixture** | A pytest fixture without a pytest-given decorator. It produces no step in the report unless an `Annotated[..., given(...)]` label on the test's parameter narrates it. |
37
- | **Fixture recording** | A captured subtree of steps + attachments produced while a step fixture is being set up. Stored keyed by fixture-instance identity. A generator fixture's teardown records nothing — it refuses steps and attachments. |
38
+ | **Plain fixture** | A pytest fixture without a pytest-given decorator. It produces no step in the report unless a *Given annotation* on the test's parameter narrates it. |
39
+ | **Given annotation** | A `given(...)` in a test parameter's `Annotated[...]` type: `def test(room: Annotated[int, given('a room')])`. On a parametrize value or a *Plain fixture* it adds a childless `given` step; on a *Step fixture* it replaces the fixture's root label and its pins. Only `given` is allowed, and a `Template` in it may only hold a bare parametrize column. |
40
+ | **Fixture recording** | A captured subtree of steps + attachments produced while a step fixture is being set up. A generator fixture's teardown records nothing — it refuses steps and attachments. |
38
41
  | **Graft** | Attaching a fixture recording into the active scenario's step tree at the moment its host test starts. |
39
42
 
40
43
  ## Collector state
41
44
 
42
45
  | Term | Meaning |
43
46
  |---|---|
44
- | **Collector** | The per-session object accumulating scenarios, fixture recordings, and parameter info, published through a `ContextVar` so a nested run can displace and restore it. |
45
- | **Active scenario** | The scenario currently being recorded into; tracked by node ID. |
46
- | **Node ID** | A pytest test identifier (e.g., `tests/test_x.py::test_y[a-b]`). Used as a key throughout the collector. |
47
- | **Step stack** | The chain of currently-open steps; entered by `with given(...)`, popped on exit. Mirrored inside a fixture recording while a fixture body is running. |
47
+ | **Collector** | The per-session object accumulating scenarios, fixture recordings, and parameter info. |
48
+ | **Active scenario** | The scenario currently being recorded into. |
49
+ | **Node ID** | A pytest test identifier (e.g., `tests/test_x.py::test_y[a-b]`). |
50
+ | **Step stack** | The chain of currently-open steps. A `with given(...)` pushes one, and leaving the block pops it. |
48
51
 
49
52
  ## Report
50
53
 
@@ -54,17 +57,21 @@ This glossary covers pytest-given's own bounded context. The terminology a *user
54
57
  | **Renderer** | Converts a JSON report into a rendering — a self-contained HTML page or a Markdown document. |
55
58
  | **Parameter coloring** | Each parametrize column gets a stable highlight color; placeholders and matching values share that color wherever they appear in step text and the parameter table. |
56
59
  | **Value highlight** | A neutral highlight applied to t-string interpolation values that don't correspond to a parametrize column and are constant across every case (e.g., a computed expression like `price * 1.2`). One that varies becomes a `derived` column instead. |
57
- | **Source link** | A clickable file:line anchor on a scenario card, a story panel, or an expanded glossary term card, resolved from the `given_source_link` config — a preset name like `vscode` / `github`, or a raw URL template. Captured as a `SourceLocation` (POSIX relpath + 1-indexed line) from `pytest.Item.location` for a scenario, from the declaration site for a *Story* or *Term*. Disabled by default. |
58
- | **Theme** | The HTML report's colour scheme — `light`, `dark`, or `auto` (follow the viewer's system). The `given_theme` config sets the default a report opens in; a viewer's own choice from the report's theme control, once made, wins over it in that browser. |
60
+ | **Source link** | A clickable file:line anchor on a scenario card, a story panel, or an expanded glossary term card. It points at a scenario's test function, or at the declaration of a *Story* or *Term*. |
61
+ | **Report link** | A Markdown link to a scenario, tag or story in the HTML *Report*: the report's URL with a `#scenario=<node ID>`, `#tag=<tag>` or `#view=stories&story=<story id>` fragment. Without a glyph it is a plain one, which claims only that its target exists. |
62
+ | **Citation** | A *Report link* led by its target's status glyph, citing a scenario, tag or story from a Markdown document: `✅ [title](<report URL>#scenario=…)`. A tag or story citation adds a summary after it, `(5 ✅ · 2 🔵)`. A target the *Report* lacks reads `❓`. |
63
+ | **Narrated citation** | A *Citation* of a scenario written as a `<details markdown="1">` block, the citation in its `<summary>` and the scenario's Markdown narration in its body. |
64
+ | **Citation finding** | One problem `pytest-given citations check` reports on one *Report link*: its kind (`stale`, `missing`, `failed`, `mistyped`, …), the document location and a message. |
65
+ | **Theme** | The HTML report's colour scheme — `light`, `dark`, or `auto` (follow the viewer's system). |
59
66
 
60
67
  ## Narration lint
61
68
 
62
69
  | Term | Meaning |
63
70
  |---|---|
64
- | **Narration lint** | The `--given-lint` pass that checks recorded scenarios against the *Lint rule* catalog once the *Report* model is built. It enforces the structural subset of the narration conventions — it cannot check whether a *Step*'s text is semantically true. |
65
- | **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. The catalog in `lint/base.py` is data, so severities, config validation and docs stay in sync with one table. |
66
- | **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. |
67
- | **Severity** | A *Lint rule*'s level — `off`, `warn` or `error` — defaulted by the catalog and overridable per rule via `given_lint_rules`. Only `error` fails the run; `warn` reports in the terminal summary; an `off` rule is not evaluated at all. |
71
+ | **Narration lint** | The `--given-lint` pass that checks recorded scenarios against the *Lint rule* catalog. It enforces the structural subset of the narration conventions — it cannot check whether a *Step*'s text is semantically true. |
72
+ | **Lint rule** | One named check, carrying a surface and a default *Severity*. A `runtime` rule reads the recorded scenarios; an `ast` rule parses the step bodies' source. |
73
+ | **Lint finding** | One *Lint rule* firing on one subject: the rule id, the *Severity* it fired at, the subject, a *Source link* location and a message naming the offender. |
74
+ | **Severity** | A *Lint rule*'s level — `off`, `warn` or `error`. Only `error` fails the run, `warn` reports in the terminal summary, and an `off` rule is not evaluated at all. |
68
75
 
69
76
  ## Domain Storytelling
70
77
 
@@ -74,28 +81,29 @@ Terms follow [Domain Storytelling](https://domainstorytelling.org/quick-start-gu
74
81
 
75
82
  | Term | Meaning |
76
83
  |---|---|
77
- | **Glossary** | The Ubiquitous-Language concept — the shared vocabulary a domain speaks in — and the class that realizes it: `Glossary()`, with `.actor(...)`, `.work_object(...)`, `.activity(...)` registration methods and `g('foo')` (declare-or-get a kindless term, optional `definition=`) / `g['foo']` (get-only, raises on unknown) accessor forms. |
78
- | **File glossary** | A glossary loaded from a Markdown file, via the `FileGlossary(path)` class. It parses all GFM pipe tables in the file into the same inner `Glossary` model; terms are accessed by name (`g['Guest']`, case-insensitive). *Kind inference* fills in term kinds post-collection from clause *slot* positions when no explicit `kind_column` is configured. |
84
+ | **Glossary** | The Ubiquitous-Language concept — the shared vocabulary a domain speaks in — and the class that realizes it in code: `Glossary()`, on which terms are registered. |
85
+ | **File glossary** | A glossary loaded from the GFM pipe tables of a Markdown file, via the `FileGlossary(path)` class. |
79
86
  | **Deferred term** | A term handed over before its kind is settled — what `g('foo')` and `g['foo']` on a code glossary return, and every *file glossary* lookup. The handle is the same `TermHandle` the typed registrations (`g.actor(...)` and friends) hand back; `declared_kind is None` is what marks the deferral. The deferral is in the handing over, not the term: a row with an explicit `kind_column` arrives through the same handle already kinded, while the rest stay `None` until *kind inference* runs. |
80
- | **Term** | A registered glossary entry: an Actor, Work Object, Activity, or kindless term. Each carries an id (slug), a canonical name, a kind (`None` when kindless), and an optional definition (`str | None`, `None` when undefined). |
81
- | **Handle** | The Python object a glossary hands back for a *term* — `TermHandle`, the same type from every accessor (`g.actor(...)`, `g('foo')`, `g['Guest']`, a captured `guest = ...`). It is what steps, scenario titles and sentences interpolate, in one of three surface forms: **bare** (`room` — the canonical display), **`.low`** (`room.low` — lowercased), or **called** (`room('Deluxe Suite')` — an *instance* on an Actor or Work Object, an inflection on an *Activity*). 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. |
82
- | **Actor** | A glossary term for a participant in the domain (e.g., *Guest*). Carries the actor kind color in the report. |
83
- | **Work Object** | A glossary term for a thing acted on (e.g., *Room*, *Booking*). Carries the work-object kind color in the report. |
84
- | **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 `book('books')` records *books* as a surface form of the canonical *book*. |
87
+ | **Term** | A registered glossary entry: an Actor, Work Object, Activity, or kindless term. Each carries an id (slug), a canonical name, a kind (`None` when kindless), and an optional definition. |
88
+ | **Handle** | The Python object a glossary hands back for a *term* — `TermHandle`, the same type from every accessor (`g.actor(...)`, `g('foo')`, `g['Guest']`, a captured `guest = ...`). It is what steps, scenario titles and sentences interpolate, in one of four surface forms: **bare** (`room` — the canonical display), **`.l`** (`room.l` — capitalized words lowercased, acronyms kept), **`.s`** (`room.s` — the *S-form*), or **called** (`room('Deluxe Suite')` — an *instance* on an Actor or Work Object, an inflection on an *Activity*). `.l` and `.s` also apply to a called form and chain (`room.l.s` reads *rooms*). Each form renders as a *term ref*. A story hands out a **sentence handle** the same way: `book_a_room['cancel']` by name or `book_a_room[3]` by number, which `pins=` takes. |
89
+ | **S-form** | A term's name with the regular English -s ending, from the `.s` handle form: the plural of an Actor or Work Object (*rooms*), the third person singular of an Activity (*books*). It adds -s to the last word, -es after s, x, z, ch or sh, and turns a consonant + y into -ies, but an acronym takes a plain -s (*APIs*); anything else, such as *people* or *checks in*, needs the called form. An S-form reference, in any case, is a reference to the term itself — not an *instance* or an *inflection*. |
90
+ | **Actor** | A glossary term for a participant in the domain (e.g., *Guest*). |
91
+ | **Work Object** | A glossary term for a thing acted on (e.g., *Room*, *Booking*). |
92
+ | **Activity** | A glossary term for what an actor does (e.g., *book*, *confirm*), which Domain Storytelling draws as an arrow labelled with a verb. Activities accept inflections: calling `search('searches for')` records *searches for* as a surface form of the canonical *search*. |
85
93
  | **Term ref** | An occurrence of a term inside narration. Modeled as `NarrationTermRef` in step text and as `ClauseTermRef` inside a clause. |
86
- | **Instance** | A named refinement of an Actor or Work Object (e.g., `guest('Alice')` is an instance of the *Guest* actor). Instances aggregate in the Glossary tab's refs block. |
87
- | **Inflection** | A surface form of an Activity term other than its canonical name (e.g., *searches for* as an inflection of *search*). Reported under "Also used as:" in the Glossary. |
88
- | **Story** | A named flow modeled as a sequence of sentences. Constructed by `story('Title', [sentence(...), ...])`. Stories are first-class report tabs and the unit of coverage. |
94
+ | **Instance** | A named refinement of an Actor or Work Object (e.g., `guest('Alice')` is an instance of the *Guest* actor). |
95
+ | **Inflection** | A surface form of an Activity term other than its canonical name or *S-form* (e.g., *searches for* as an inflection of *search*). |
96
+ | **Story** | A named flow modeled as a sequence of sentences. Constructed by `story('Title', [sentence(...), ...])`. Stories are the unit of coverage. |
89
97
  | **Sentence** | What Domain Storytelling calls a sentence: an actor, an activity and its work objects, plus connective words. One row in a story, numbered by its position (1..N, never set by hand) and optionally named with `sentence(..., name='cancel')`, a name that stays put when rows are inserted. Constructed by `sentence(...)`. Usually one clause, built implicitly; several when the sentence has several arrows under one number. |
90
98
  | **Clause part** | The two-variant union making up a clause's prose (`ClausePart` = `ClauseTermRef` or `ClauseWord`): a reference to a glossary term, whose kind resolves via the glossary, or a bare clause word — a node label or edge connective that 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. |
91
99
  | **Clause** | One linear walk through a sentence's arrows, a node/edge alternation starting actor → verb → noun, constructed by `clause(...)`. 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. |
92
- | **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. Slots drive both clause validation and *kind inference*. |
100
+ | **Slot** | A position role in a clause, from its node/edge alternation: position 0 is the actor slot, odd positions are verb slots, and even positions ≥ 2 are noun slots. |
93
101
  | **Scenario↔sentence binding** | The link between a scenario (or step) and story sentences. `@scenario(stories=...)` names the stories a scenario is narration-matched against; a *pin* (`pins=` on `@scenario` or on `given`/`when`/`then`) binds sentences explicitly, in any story, whether `stories=` names it or not. |
94
102
  | **Pin** | What a *sentence handle* passed to `pins=` is recorded as, the way a term handle in narration is recorded as a *term ref*: a `Pin` naming 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. |
95
103
  | **Coverage** | The "did this scenario touch that sentence" relation. Computed by the *A_refs ⊆ S* rule: 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. |
96
104
  | **Kind inference** | The post-collection pass (`infer_glossary_kinds`) 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*. |
97
- | **Kindless** | A term with `kind=None` — left unset when *kind inference* finds no story *slot* to infer from (a term used only in t-string steps, never in a sentence). Shown in the report's *Uncategorized* bucket. |
98
- | **Undefined** | A term with `definition is None`; surfaced by a badge and filter in the Glossary view. Orthogonal to *kindless*. |
105
+ | **Kindless** | A term with `kind=None` — left unset when *kind inference* finds no story *slot* to infer from (a term used only in t-string steps, never in a sentence). |
106
+ | **Undefined** | A term with `definition is None`. Orthogonal to *kindless*. |
99
107
 
100
108
  ## Collaboration
101
109
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pytest-given
3
- Version: 0.4.1
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
@@ -24,6 +24,8 @@ Classifier: Topic :: Software Development :: Testing
24
24
  Classifier: Typing :: Typed
25
25
  Requires-Python: >=3.14
26
26
  Requires-Dist: jinja2>=3.1
27
+ Requires-Dist: markdown-it-py>=3.0
28
+ Requires-Dist: markupsafe>=2.0
27
29
  Requires-Dist: pytest>=9.0
28
30
  Description-Content-Type: text/markdown
29
31
 
@@ -71,16 +73,16 @@ from pytest_given import attach, given, scenario, then, when
71
73
 
72
74
 
73
75
  @pytest.fixture
74
- @given('a coffee machine')
76
+ @given('a coffee machine with 10 coffees')
75
77
  def machine():
76
78
  return {'coffees': 10, 'price': 2}
77
79
 
78
80
 
79
- @scenario('Buy coffee', tags=['billing'])
81
+ @scenario('Buying a coffee takes one from the machine', tags=['checkout'])
80
82
  def test_buy_coffee(machine):
81
- with when('I insert $2'):
83
+ with when('I buy a coffee'):
82
84
  machine['coffees'] -= 1
83
- with then('I get a coffee'):
85
+ with then('the machine has 9 coffees left'):
84
86
  assert machine['coffees'] == 9
85
87
  attach('Machine state', machine)
86
88
  ```
@@ -93,9 +95,13 @@ pytest --given-html
93
95
 
94
96
  This produces `given-report/report.html` — one file you can open directly in a browser.
95
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
+
96
102
  ## Why pytest-given?
97
103
 
98
- 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.
99
105
 
100
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.
101
107
 
@@ -105,16 +111,20 @@ pytest-given works the other way round: **engineers or their agents write normal
105
111
 
106
112
  ### Written by agents, reviewed by people
107
113
 
108
- More and more tests aren't written by hand. A person describes a scenario, an AI agent writes the test along with the code, and people review the narrated report instead of the test code. 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.
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.
109
115
 
110
116
  <p align="center">
111
- <img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers and domain experts instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report that domain experts validate and developers review, feeding back to the agents." width="640">
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">
112
118
  </p>
113
119
 
114
120
  ### Glossary and Domain Storytelling
115
121
 
116
122
  pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/) defines the terms your team uses, and the report highlights them wherever a test mentions them. [Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/) adds the big picture: stories of how the domain works, with the report showing which scenarios cover each sentence of a story.
117
123
 
124
+ ### Documents that stay true
125
+
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.
127
+
118
128
  ## Features
119
129
 
120
130
  - **[Step context managers](https://nwilbert.github.io/pytest-given/latest/guide/scenarios/)**: `with given(...)`, `when(...)`, `then(...)` blocks in plain pytest tests, nesting within a phase.
@@ -122,11 +132,13 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
122
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.
123
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.
124
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.
125
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.
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.
126
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.
127
139
 
128
140
  The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).
129
141
 
130
142
  ## License
131
143
 
132
- [MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT; its notice is in [THIRD-PARTY-LICENSES](https://github.com/nwilbert/pytest-given/blob/main/THIRD-PARTY-LICENSES).
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('Buy coffee', tags=['billing'])
50
+ @scenario('Buying a coffee takes one from the machine', tags=['checkout'])
51
51
  def test_buy_coffee(machine):
52
- with when('I insert $2'):
52
+ with when('I buy a coffee'):
53
53
  machine['coffees'] -= 1
54
- with then('I get a coffee'):
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,16 +80,20 @@ 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
- More and more tests aren't written by hand. A person describes a scenario, an AI agent writes the test along with the code, and people review the narrated report instead of the test code. 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.
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 and domain experts instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report that domain experts validate and developers review, feeding back to the agents." width="640">
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
86
90
 
87
91
  pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/) defines the terms your team uses, and the report highlights them wherever a test mentions them. [Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/) adds the big picture: stories of how the domain works, with the report showing which scenarios cover each sentence of a story.
88
92
 
93
+ ### Documents that stay true
94
+
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.
96
+
89
97
  ## Features
90
98
 
91
99
  - **[Step context managers](https://nwilbert.github.io/pytest-given/latest/guide/scenarios/)**: `with given(...)`, `when(...)`, `then(...)` blocks in plain pytest tests, nesting within a phase.
@@ -93,11 +101,13 @@ pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary
93
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.
94
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.
95
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.
96
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.
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.
97
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.
98
108
 
99
109
  The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).
100
110
 
101
111
  ## License
102
112
 
103
- [MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT; its notice is in [THIRD-PARTY-LICENSES](https://github.com/nwilbert/pytest-given/blob/main/THIRD-PARTY-LICENSES).
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).