hitchstory 0.15.3

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

HitchStory

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.

Example

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
  following steps:
  - Clicked: new email
  - Form filled:
      to: [e-mail]
      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 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 [e-mail] in to
Clicking on send email
Email was sent
SUCCESS in 0.1 seconds.

Install

$ pip install hitchstory

Using HitchStory

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

Approach to using HitchStory

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

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

Design decisions and principles

Design decisions are justified here:

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

Why not X instead?

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

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