hitchstory VS embedded-postgres

I built something like this too:

https://github.com/hitchdev/hitchstory/blob/master/examples%...

I took the same approach to "docs are tests and tests are docs" 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 should actually be the same thing - not just for doctests, 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 each other:

* Tests are more easily understandable when you attach written context intended for human consumption.

* Docs are better if they come attached to a guarantee that they're valid, not out of date and not missing crucial details.

* TDD is better if how-to docs are created as a side effect.

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 abstractions for the truly deterministic stuff and for other stuff where you may need to do subtle trade offs (e.g. choosing a selector for the search bar) an LLM will generally do a bad job.

For those interested in the concept of having permanently up-to-date documentation with screenshots I built this testing framework based upon the idea that good documentation can be a autogenerated artefact of good tests:

https://github.com/hitchdev/hitchstory

I don't like gherkin. It's it has very awkward syntax, it's not type safe, it's very verbose, it has no ability to abstract scenarios and 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 this or it doesn't matter as much. I find that most people that apply gherkin to their projects find it doesn't work - 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 is explicitly designed as a source for generating documentation rather than trying to be the documentation.

I built this because I had the same idea: https://github.com/hitchdev/hitchstory

If the specification can be tested and used to generate docs and can be rewritten based upon program output then the maintenance cost for producing docs like these plunges.

-c fsync=off -c synchronous_commit=off -c full_page_writes=off

I got the answer from Karen Jex at Djangocon 2023.

I used it to build some integration tests which exhibit best practices: https://github.com/hitchdev/hitchstory/tree/master/examples/...

I considered using tmpfs but I wanted to cache the entire database volume and couldnt figure out how to do that with podman.

This is incredible work.

To anyone curious, I highly recommend:

- https://hitchdev.com/hitchstory/approach/

- https://hitchdev.com/hitchstory/why-not/

From the overall RDD/BDD type home page:

- https://hitchdev.com/hitchstory/

The entire product site is a thing of richly informative beauty.

---

My only question was whether the generated 'docs' snippets would add value over just reading the story in your DASL. Any markdown site generator (such as the chosen Material for MKDocs) can just embed the ```yaml anyway. But then I realized what was generating e.g. …

- https://hitchdev.com/hitchstory/using/engine/rewrite-story/

… and how superior that is to typical docs, especially typical docstring or swagger factories.

Little use if you’re not on the JVM but I’ve had great success with Embedded Postgres:

https://github.com/zonkyio/embedded-postgres

Each test just copies a template database so it’s ultra fast and avoids the need for complicated reset logic.

Outside of differences between assertion-based unit tests and property-based tests (both of which are worth doing), I don't think framework makes much difference. But your approach to testing definitely does.

I think every language having its own testing framework is good, even for things like functional tests which can often be externalised. Tests are an essential part of every project and should be well integrated with the rest of the codebase and the team creating it. Often, the tests are the only good place to go and see what an app actually _does_ and so they form an essential part of the documentation.

In my experience it's very rare that you can effectively create and maintain something like Cucumber tests owned by anyone but the team implementing the code so there's little benefit to translating from a text DSL like that. But the language used is definitely useful, so what I like to see is code in the implementation language that matches the Given/When/Then structure of those tests, but instead of reusable text steps you just have reusable functions which take parameters. This means you can easily refactor, and use the full functionality of your IDE to suggest and go to definitions etc. No matter what, you should treat your test code the same way you do everything else - abstractions matter, so functional tests at the top level should rarely just be about clicking on things and asserting other things, they should be in the language of the domain.

Functional tests are worth much more than unit tests. No only do they test the only things of actual business value, they are also more robust in the face of implementation refactorings and so require less rework (unless you're being overly specific with CSS selectors etc). Unit tests are often highly coupled to specific implementations and can be a poor investment, especially early in a project. I believe a good balance is functional and integration tests that explore the various paths through your app and prove everything's hooked up, coupled with property based unit tests for gnarly or repetitive logic that isn't worth endlessly iterating via the UI. All other unit tests are optional and at the discretion of the implementer.

You should be able to mock out every major articulation point in your code, but it's generally preferable if you can mock _real_ dependencies. That is, instead of mocking out a 'repository' abstraction that looks stuff up and returns canned data, have a real test database against which you look up real data (created by steps in your functional tests). This reduces risk and cognitive overhead (you're not having to encode too many assumptions in your test suite) and doesn't have to be as slow as people like to make out - Embedded Postgres is quite fast, for example:

https://github.com/zonkyio/embedded-postgres

Same with network services - it's not slow to chat to localhost and you'll find more issues testing proper round-trips. I have not found "assert that you called X" style testing with mocks useful - you care about outcomes, not implementation details.

Beyond all that, as long as you can make assertions that generate clear error messages, you're fine.

I use an embedded postgres testing library for the JVM that does something along those lines.

Well no actually it just unpacks the tar file in a temp dir and runs the full postgres, but it mostly feels like what you describe (minus the single file part) and starts surprisingly fast. That would totally work for a little proof of concept (https://github.com/zonkyio/embedded-postgres)