HitchStory Examples

The following are four rudimentary to do apps each tested with HitchStory, a StrictYAML based FOSS python integration testing framework that autogenerates documentation.

Project	Stories	Cool Features	Story Engine
Website	add todo, correct spelling	Autogenerated add todo and correct my spelling docs with playwright generated video and screenshots.	engine.py
REST API	add todo, correct spelling	Autogenerated docs, Self rewriting stories	engine.py
Interactive command line app	add todo, correct spelling	Autogenerated docs, Self rewriting stories	engine.py
Python API	add todo, correct spelling	Autogenerated docs, Self rewriting stories	engine.py

All of the above tests are also running on Github Actions with no tweaks:

If you'd like help with introducing capabilities like these to your project, contact me now for a free consultation.

Getting started

Podman must be installed on your system first.

All other functionality is automated and can be run via one of the four key.sh scripts.

$ git clone https://github.com/hitchdev/examples.git
$ cd examples/commandlib -OR- restapi -OR- website -OR- pythonapi
$ ./key.sh make

Run all tests

Try this first to see that everything runs:

$ ./key.sh regression

Run singular test

This command can be used to acceptance test driven development.

$ ./key.sh atdd correct

"correct" is a unique keyword used in the name of one of the stories.

Run singular test in rewrite mode

You can try changing the code to output something different and run this to see the story rewrite itself:

$ ./key.sh ratdd correct

(Note: you will have to run ./key.sh build first)

Generate documentation from stories

Running this command in any of the above project folders will regenerate the docs for that project from the stories.

$ ./key.sh docgen

For the website project, the screenshots and video artefacts used by the docs are retaken by running:

$ ./key.sh recordings

Clean everything

This will delete everything created to run these tests (container/volume):

$ ./key.sh clean all

Note that it must be run in each project folder you ran make in.

About the projects

The four folders contain four versions of the same project - this great little to do app built by Oleg Vinokurov which was built with a command line, REST and web interface.

The ./key.sh scripts runs the app in a container inside the hitch container.

This is done to segregate the test code from the application code.

The website also runs a separate playwright container inside the hitch container.

The hitch container is run with a "gen" volume. This is a podman volume that contains all builds necessary to run the app.

Future work on examples

• Generate website images and videos with playwright for use in documentation.
• Mount code folder with podman so changes reflect instantaneously.
• Use postgres with to do apps, and demonstrate given preconditions to fill database.
• Mock the passage of time - to do app with reminder.
• Show off inheritance (e.g. with a logging in story for website).