[hitchstory]

With annotated, declarative step-based YAML integration tests. They autogenerate how-to markdown documents via a jinja2 template:

https://github.com/hitchdev/hitchstory (there are a few toy examples listed there)

Depending on the app the docs might also embed artefacts generated under test - e.g. screenshots from playwright.

[ardalanpouya]

This is a very interesting idea. but I foresee two challenges here: (1) it sounds like alot of maitnance to keep a set of annotated tests that updates docs. (2) this does not sound like a solution for a company which produces handful of system behavior explaining docs on a daily basis. it looks like it is more so intended with low level documentation

[hitchstory]

The integration tests require maintenance like all tests do. The doc compilation step doesnt require much maintenance.

There are examples there to demonstrate use on any level - e.g. to create unit-test level tests for a library or that generate code docs for programmers or playwright e2e tests that generate user-readable how to docs.

The interaction code requires maintenance but a lot of it very boilerplate. E.g. you need a function to interpret the "click" step to do the proper playwright click or drag-drop but it should function more or less the same for everybody.

[ardalanpouya]

Gotcha! will take a deeper look. thanks :)