hitchstory 0.19.0

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

HitchStory

HitchStory is a literate python testing framework where the tests can rewrite themselves and write your docs.

The executable specifications are written, using StrictYAML and can test and document applications of any kind.

Fully fleshed out examples (a website, an interactive CLI, a REST API and Python API) with self rewriting tests and generated docs can be seen in the examples folder and run.

The library is 100% pure python. The tests can be run:

• Inside pytest or similar
• Or via a basic CLI runner

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, Failure
from mockemailchecker import email_was_sent
from mockselenium import Webdriver
from strictyaml import Str

class Engine(BaseEngine):
    given_definition = GivenDefinition(
        website=GivenProperty(Str()),
    )
    
    def __init__(self, rewrite=False):
        self._rewrite = rewrite

    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 failing_step(self):
        raise Failure("This was not supposed to happen")
    
    def error_message_displayed(self, message):
        pass

    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
• Creating a basic command line test runner
• Upgrade breaking changes between v0.14 and v0.15
• 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
• Story inheritance - given mapping preconditions overridden
• Story inheritance - override given scalar preconditions
• Story inheritance - parameters
• Story inheritance - steps
• Inherit one story from another simply
• Match two strings
• Extra story metadata - e.g. adding JIRA ticket numbers to stories
• Story with parameters
• Play multiple stories in sequence
• Using hitchstory with pytest
• 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 "the business" write stories while you just write the code?
• Separation of Test Concerns
• Test Artefact Environment Isolation
• Test concern leakage
• Tests as an investment
• What is the difference betweeen a test and a story?
• The importance of test realism
• Testing non-deterministic code
• Specification Documentation Test 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 does HitchStory have no CLI runner - only a pure python API?
• 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 use Hitchstory instead of Behave, Lettuce or Cucumber (Gherkin)?
• Why not use the Robot Framework?
• Why use hitchstory instead of a unit testing framework?