What does HackerNews think of hitchstory?

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/hitchdev/hitchstory/blob/master/examples/... for your users rather than more test-like documents like https://github.com/diaspora/diaspora/blob/develop/features/m...

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.

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 wrote a specification-test framework that does this:

https://github.com/hitchdev/hitchstory

Project with README that is partially generated from the code samples in the tests:

https://github.com/crdoconnor/strictyaml

with the README template:

https://github.com/crdoconnor/strictyaml/blob/master/docs/in...

that grabs code snippets and their expected outputs from the story:

https://github.com/crdoconnor/strictyaml/blob/master/hitch/s...

This is more or less the structure I followed with this testing framework: https://github.com/hitchdev/hitchstory

The whole idea being that you don't want the story to be turing complete (there are no loops or conditionals with a story), but the code that executes it needs to be turing complete.

This is kind of what I have been doing with this testing framework: https://github.com/hitchdev/hitchstory

It's designed so that you can write tests that are the basis of the "how to" documentation - with a small script and some jinja2 you can generate readable documentation in the form of markdown from the test:

Original test (behavioral example) : https://github.com/crdoconnor/strictyaml/blob/master/hitch/s...

Example docs generated from that test : https://hitchdev.com/strictyaml/using/alpha/scalar/email-and...

It's also designed so that the testing framework can be programmed to rewrite the test automatically for simple code changes (e.g. changing the wording of that exception).

This makes building tests much quicker and much, much less tedious and perfectly in sync docs almost becomes a side effect.

Essentially "how to" documentation and example driven behavioral tests are the same thing for all projects. It's just that most people don't realize and don't treat them as such.