Use pytest or unittest
Goal
You already test your routes with Drafter's assert_ functions, and
you want to run the same kind of checks with pytest or unittest,
the two tools most Python projects use.
Before you start
Every route is a plain function, so any testing tool can call it and
check the Page it returns. Only one thing is in the way: your site
file ends with start_server(...), and importing the file would
launch the site and never come back to your tests.
Setting the DRAFTER_SKIP environment variable fixes that. While it
is set, start_server(...) does nothing at all, so a test file can
import your routes safely. The line that sets it has to run before
the line that imports your site.
unittest comes with Python. pytest is installed separately, with
pip install pytest.
The site being tested
Both examples below test this small site, saved as cookie_game.py:
# cookie_game.py
from drafter import *
from dataclasses import dataclass
@dataclass
class State:
score: int
@route
def index(state: State) -> Page:
return Page(state, [
Header("Cookie Game"),
"Your score is " + str(state.score) + "\n",
Button("Click me!", "add_point")
])
@route
def add_point(state: State) -> Page:
state.score = state.score + 1
return index(state)
start_server(State(0))
Test it with pytest
Put the tests in a second file in the same folder. pytest looks for
files whose names start with test_ and runs every function in them
whose name starts with test_:
# test_cookie_game.py
import os
os.environ["DRAFTER_SKIP"] = "1"
from drafter import *
from cookie_game import State, index, add_point
def test_index_shows_the_score():
assert index(State(7)) == Page(State(7), [
Header("Cookie Game"),
"Your score is 7\n",
Button("Click me!", "add_point")
])
def test_add_point_adds_one():
page = add_point(State(4))
assert page.state == State(5)
def test_page_mentions_the_score():
assert assert_has(index(State(12)), "Your score is 12")
Run it from that folder:
pytest
A passing run prints one dot per test. When a test fails, pytest
shows the line that failed and what differed. Here the expected page
said 8 where the real page said 7:
E Drill down into differing attribute content:
E content: [Header('Cookie Game'), 'Your score is 7\n', ...] != [Header('Cookie Game'), 'Your score is 8\n', ...]
E At index 1 diff: 'Your score is 7\n' != 'Your score is 8\n'
Test it with unittest
unittest groups tests as methods of a class, and compares values
with self.assertEqual:
# check_cookie_game.py
import os
os.environ["DRAFTER_SKIP"] = "1"
import unittest
from drafter import *
from cookie_game import State, index, add_point
class TestCookieGame(unittest.TestCase):
def test_index_shows_the_score(self):
self.assertEqual(index(State(7)), Page(State(7), [
Header("Cookie Game"),
"Your score is 7\n",
Button("Click me!", "add_point")
]))
def test_add_point_adds_one(self):
page = add_point(State(4))
self.assertEqual(page.state, State(5))
def test_page_mentions_the_score(self):
self.assertTrue(assert_has(index(State(12)), "Your score is 12"))
if __name__ == "__main__":
unittest.main()
Run it like any other Python file:
python check_cookie_game.py
Keep using Drafter's assertions
Plain == is exact: capitalization, spacing, and every decimal place
of a float have to match. Drafter's assert_ functions are
more forgiving by default,
and they can search a page without spelling out all of it.
Each assert_ function returns True when it passes and False
when it fails, so you can use them inside either tool. Wrap the call
in assert for pytest, or in self.assertTrue(...) for unittest,
as the test_page_mentions_the_score tests above do. A failure then
prints Drafter's own explanation of what differed, and the test is
also counted as failed.
Without that wrapper the test still passes when the assertion fails, because a Drafter assertion reports a failure and carries on. It never stops the program by itself.
Common problems
- Running the tests opens your site, or the tests never finish:
the
os.environ["DRAFTER_SKIP"] = "1"line is missing, or it comes after the import of your site file. It has to come first. ModuleNotFoundError: No module named 'cookie_game': run the tests from the folder that holds both files, and check that the name afterfrommatches your site's file name without.py.SUCCESSandFAILURElines appear before the test results: those come fromassert_tests inside your site file. They run when the file is imported, exactly as they do when the site starts.- A test passes even though a Drafter assertion printed
FAILURE: the call is not wrapped inassertorself.assertTrue(...). - Your site no longer starts when you run it:
DRAFTER_SKIPis set in your terminal as well. Set it only inside the test file, as shown above.
Understand it
Routes are functions you can call, and the pages they return can be compared like any other value. See Routes and pages.
See another example
Test a feature covers the same site with Drafter's built-in assertions, which need no second file.
Look it up
Testing functions lists every
assertion and what it returns. The skip setting is described under
start_server.
Fix a problem
Troubleshooting covers a site that will
not start, including a leftover DRAFTER_SKIP.