hitchstory

>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 ?

I built a testing library on top of pytest based upon the idea of doing this mapping at an application level instead of a method/function/class level. If you write tests in a strongly typed, non-turing complete markup (in this case, StrictYAML), you can then use it with a template and test artefacts (e.g. app screenshots) to generate readable how-to/tutorial docs which are guaranteed to stay up to date. https://github.com/hitchdev/hitchstory This isn't a new idea, but I find that people are often skeptical because there's a history of people getting their fingers burned by Gherkin's language design or YAML's weak typing (both of which are completely valid).

I like the overall idea a lot but I felt that the Gherkin language itself hamstrings the process - for four main reasons: * Excessive verbosity * Not type safe * It lacks story abstractions (i.e. you can't flexibly create variations on a scenario, extend existing scenarios, etc.). * You need to fiddle with regexes. A side effect of these semantic/syntactic problems is that gherkin stories end up being too vague to be useful - i.e. the meat of the story is often missing. I created a StrictYAML based alternative with python that I think has all of the benefits, fixes those 4 problems and doesnt suffer from traditional "YAML" problems: https://github.com/hitchdev/hitchstory I call this "BDD with meat".

Sounds like we had the same idea: https://github.com/hitchdev/hitchstory Like you I also dont want to go back. Declarative tests are the future.

If you like pytest and BDD I'd encourage you to check out my pytest library: https://github.com/hitchdev/hitchstory With it you can write integration tests with typesafe YAML which double as user friendly documentation. It also has inheritance (which gherkin doesnt) - e.g. a "buy golf clubs" story can inherit from "put golf clubs in shopping basket" story which can inherit from a "log in" story, etc.

Ive had product owners take an interest in docs autogenerated from tests. Especially with artrfacts embedded. They like tuff like this: https://github.com/hitchdev/hitchstory/blob/master/examples/... And can be persuaded to look at the (YAML) source. Gherkin isnt really a suitable language for writing test cases in - it's verbose, lacks inheritance, has clunky syntax and is stringly typed.

Here's an example of it in action to run integration tests: https://github.com/hitchdev/hitchstory/tree/master/examples In e.g. the website example, the parent podman container does everything from running the integration tests to converting a video of the test at the end into a slowed down GIF and combines it with screenshots to put in the docs. It orchestrates the child podman containers - playwright + the webapp. I'm certain that if all this tooling were run on different host machines it would have a myriad of "works on my machine" problems all over the place - whether due to mac, WSL, weird linux distros, github actions idiosyncrasies or whatever. I'm equally certain that if the tooling were bundled in the app container it would needlessly fatten it with unnecessary and potentially conflicting dependencies. I don't want video conversi