Skip to main content

Type-safe YAML-based example specification driven development framework for python.

Project description


Main branch status

HitchStory is a python testing and living documentation framework for building strictly typed executable specifications which can auto-generate your howto documentation.

The executable specifications can be written to specify, test and document applications at every level - replacing xUnit equivalents of unit tests, integration tests and end to end tests with appropriate tooling.

The specifications are written using StrictYAML.



Logged in:
    website: /login  # preconditions
  - Form filled:
      username: AzureDiamond
      password: hunter2
  - Clicked: login

Email sent:
  about: |
    The most basic email with no subject, cc or bcc
  based on: logged in             # inherits from and continues from test above
  following steps:
  - Clicked: new email
  - Form filled:
      contents: |                # long form text
        Hey guys,

        I think I got hacked!
  - Clicked: send email
  - Email was sent

from hitchstory import BaseEngine, GivenDefinition, GivenProperty
from mockemailchecker import email_was_sent
from mockselenium import Webdriver
from strictyaml import Str

class Engine(BaseEngine):
    given_definition = GivenDefinition(

    def set_up(self):
        self.driver = Webdriver()

    def form_filled(self, **textboxes):
        for name, contents in sorted(textboxes.items()):
            self.driver.fill_form(name, contents)

    def clicked(self, name):

    def email_was_sent(self):
>>> from hitchstory import StoryCollection
>>> from pathlib import Path
>>> from engine import Engine
>>> StoryCollection(Path(".").glob("*.story"), Engine()).named("Email sent").play()
RUNNING Email sent in /path/to/working/example.story ...
Visiting http://localhost:5000/login
Entering text hunter2 in password
Entering text AzureDiamond in username
Clicking on login
Clicking on new email
In contents entering text:
Hey guys,

I think I got hacked!

Entering text in to
Clicking on send email
Email was sent
SUCCESS in 0.1 seconds.


$ pip install hitchstory

Using HitchStory

Approach to using HitchStory

Best practices, how the tool was meant to be used, etc.

Design decisions and principles

Design decisions are justified here:

Why not X instead?

There are several tools you can use instead, this is why you should use this one instead:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hitchstory-0.15.3.tar.gz (25.3 kB view hashes)

Uploaded source

Built Distribution

hitchstory-0.15.3-py3-none-any.whl (24.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page