Type-safe YAML-based example specification driven development framework for python.
Project description
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 my other project StrictYAML.
Fully fleshed out example projects (website, interactive command line, REST API and Python API) tested and documented with HitchStory executable specifications can be seen here in the examples project.
In these sample projects the website is tested with playwright, the REST API tested using requests, the interactive command line with icommandlib the python API tested with hitchrunpy.
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: Cthon98@aol.com
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 Cthon98@aol.com 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
- 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
- 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 "the business" write stories while you just write the code?
- Recommended Environment
- 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
- What is a testing and living documentation framework?
- 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 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:
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for hitchstory-0.16.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d316dc67b5bdccd88ebf995dbce4c84ea77611177b43cf54a3dd8c51e577643a |
|
MD5 | bc5a885ea73fcaaabf998ed307bbe499 |
|
BLAKE2b-256 | 8c48b59ae3265aaf4c271f4d12908b9b70f7a4e008001c35c0ec672a4d8f8fd2 |