HitchStory is a python 3 testing and living documentation framework for building easily maintained example driven executable specifications (sometimes dubbed acceptance tests).

It was designed initially to make realistic testing of code less of a goddamn chore so the tests would actually get written and run.

The executable specifications can be written to specify and test applications at any level and have been used successfully to replace traditional low level unit tests, integration tests and end to end tests with easier to maintain tests.

The specifications are written using StrictYAML and the code to execute them is written by you, in python.

example.story:

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


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

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

engine.py:

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(
        website=GivenProperty(Str()),
    )

    def set_up(self):
        self.driver = Webdriver()
        self.driver.visit(
            "http://localhost:5000{0}".format(self.given['website'])
        )

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

    def clicked(self, name):
        self.driver.click(name)

    def email_was_sent(self):
        email_was_sent()

from hitchstory import StoryCollection
from pathquery import pathquery
from engine import Engine

StoryCollection(pathquery(".").ext("story"), Engine()).named("Email sent").play()

Will output:

RUNNING Email sent in /path/to/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 [email protected] in to
Clicking on send email
Email was sent
SUCCESS in 0.1 seconds.

You can install hitchstory through pypi in any python 3 virtualenv:

$ pip install hitchstory

However, it's recommended to install and set up hitchstory with hitchkey, which will take care of automatically setting up a up the recommended hitchstory environment.

Either install hitchkey with pipsi:

pipsi install hitchkey

Or, if you'd prefer, you can safely install with "sudo pip":

sudo pip install hitchkey

Once hitchkey is installed:

Example demo of hitchstory basics:

cd temp
hk --demo hitchstory ; hk bdd email

Example python API test demo (uses game of life):

cd temp
hk --demo pythonapi ; cd pythonapi ; hk bdd

• Special exception named failure
• Inherit one story from another
• Flaky story detection
• Generate documentation from stories
• Abort a story with ctrl-C
• Extra story metadata - e.g. adding JIRA ticket numbers to stories
• Given preconditions
• Gradual typing of story steps
• Play multiple stories in sequence
• Arguments to steps
• Story that rewrites itself
• Shortcut lookup for story names
• Continue on failure when playing multiple stories
• Variations
• Running a single named story successfully
• Hiding stacktraces for expected exceptions
• Handling failing tests
• Strong typing
• Story with parameters

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

• Triality
• Testing non-deterministic code
• Executable specifications
• Recommended complementary tools
• Does hitchstory let your BA or Product Manager write stories while you just write the code?
• Screenplay Principle
• What is a testing and living documentation framework?
• Recommended Environment
• Can I do BDD with hitchstory? How do I do BDD with hitchstory?
• The importance of test realism
• What is the difference betweeen a test and a story?
• Flaky Tests
• Tests are an investment
• How can executable specifications and living documentation be used for stakeholder collaboration?

Somewhat controversial design decisions are justified here.

• Why does HitchStory use StrictYAML?
• Why is inheritance a feature of hitchstory stories?
• Why does hitchstory mandate the use of given but not when and then?
• Two Unit Tests, Zero Integration Tests
• Why does hitchstory not have a command line interface?
• Why does hitchstory not have an opinion on what counts as interesting to "the business"?
• Principles
• Why programatically rewrite stories?
• Declarative User Stories

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

• Why not use the Robot Framework?
• Why use hitchstory instead of a unit testing framework?
• Why not use Behave, Lettuce or Cucumber (Gherkin)?