Hacker News Reader

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.

View on HN

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

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.

Gotcha! will take a deeper look. thanks :)

Reply on news.ycombinator.com