Type-safe YAML-based example specification driven development framework for python.
Project description
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:
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, 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 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 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
- 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
- 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?
- 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 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:
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.17.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d22de2392addc0f9658267ebcb978a922b41f0a6931a8d27fc0453e5e65333b5 |
|
MD5 | 2a0bf80da68451a82c2095fc8da3c734 |
|
BLAKE2b-256 | 0e9371776b3ea6f2e998528d77b373d941400fc14349f93be26ab73cbd723243 |