hitchstory

Executable documentation: Hitchstory is a type-safe StrictYAML python integration testing framework exploring some interesting ideas around this. https://hitchdev.com/hitchstory/ Example: https://hitchdev.com/hitchstory/using/behavior/run-single-na... Source: https://github.com/hitchdev/hitchstory/blob/master/hitch/sto... See also the explanation of self-rewriting tests: https://hitchdev.com/hitchstory/why/rewrite/

The skeleton test-generating-docs example I built to exhibit the framework actually does this. Here's an example: https://github.com/hitchdev/hitchstory/blob/master/examples/... It records a video while running the test and then at the end runs it through FFMPEG to make a smaller, slowed down GIF that can be embedded in the autogenerated docs. It's quite rudimentary though. I've been meaning to try making something more sophisticated and even potentially do additional automated video editing to inject text from the steps or something.

I built a Python/YAML framework around the ability to build these tests and then generate documentation from them. E.g. https://github.com/hitchdev/hitchstory/blob/master/examples%... which generates https://github.com/hitchdev/hitchstory/blob/master/examples%... When you show this stuff to other people and gather feedback - that's essentially what BDD is, too.

I built something like this too: https://github.com/hitchdev/hitchstory/blob/master/examples%...

I took the same "docs are tests and tests are docs" approach with integration testing when I created this library: https://github.com/hitchdev/hitchstory I realized at some point that a test and a how-to guide can and probably should actually be the same thing - not just for doctests (https://docs.python.org/3/library/doctest.html), but for every kind of test. It's not only 2x quicker to combine writing a test with writing docs, the test part and the docs part reinforce the quality of each other: * Tests are more easily understandable when you attach written context - the kind that is used when generating a readable how-to guide. * How to docs are better if they come attached to a guarantee that they're tested, not out of date and not missing crucial details. * Integration test driven development where how-to docs are created as a side ef

I have created a project for easily writing this type of test with YAML: https://github.com/hitchdev/hitchstory I dont think that this type of task is really appropriate for an LLM though. It is better to use hard, prewritten abstractions for the truly deterministic stuff (e.g. click). For other situations where you may need to do subtle trade offs (e.g. choosing an HTML selector for the search bar) an LLM will generally do a bad job.

>Docs should be tested - because you may be sure that everything is right, but without real users, like with any other product, you won't know for certain. Test it and test it again. If you want to automate this, see: https://github.com/hitchdev/hitchstory It is not a common approach, but generating how-to docs from tests can be almost unreasonably effective.

For those interested in the concept of having guaranteed/permanently up-to-date documentation (with or without screenshots) I built this testing framework based upon autogenerating good how-to or reference docs from tests: https://github.com/hitchdev/hitchstory (the website example has screenshots generated by playwright, the REST API example has real tested JSON snippets, the command line example has command outputs, etc.)

I don't like gherkin. I think that it has awkward syntax, it lacks type safety, it's very verbose and doesn't have enough ability to abstract scenarios. Rather than being a source for generating the documentation it tries to be the documentation. Nonetheless, there is a small number of projects where they either work around these constraints or it doesn't matter as much, so it can work. I find that most people that apply gherkin to their projects run into a brick wall though - usually for one of the above reasons. I built https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity and the ability to abstract scenarios. It is explicitly designed as a source for generating markdown documentation so that you can create richer docs like https://github.com

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.

I built this because I had the same idea: https://github.com/hitchdev/hitchstory If your specification is self rewriting, can be tested and can be used to generate docs then maintenance costs plummet.

-c fsync=off -c synchronous_commit=off -c full_page_writes=off I asked Karen Jex this question at her Djangocon 2023 talk on obscure postgres switches. I used this among other things to build some model integration tests which exhibit best practices: https://github.com/hitchdev/hitchstory/tree/master/examples/... I considered using tmpfs but since I wanted to cache the entire database volume after it had been built according to the fixtures and couldnt figure out how to do that with podman and tmpfs.

While I'm glad the idea of tying documentation to tests is catching on, I think markdown documentation -> create tests is the wrong way around. I built this tool to let people generate evergreen markdown documentation from annotated type-safe YAML integration tests: https://github.com/hitchdev/hitchstory

Like this https://github.com/hitchdev/hitchstory ?