Use behave to document acceptance tests for clinical review

Author: Themitchell

behave.ini

@@ -0,0 +1,5 @@
+[behave]
+paths = tests/features
+format = pretty
+tags = ~@skip
+

lung_cancer_screening/settings_test.py

@@ -13,4 +13,6 @@
     "whitenoise.middleware.WhiteNoiseMiddleware",
 )
 
+INSTALLED_APPS += ["behave_django"]
+
 logging.disable(logging.CRITICAL)

poetry.lock

@@ -5,7 +5,7 @@ description = ""
 authors = [{name = "Your Name",email = "[email protected]"}]
 license = { text = "MIT" }
 readme = "README.md"
-requires-python = ">=3.13"
+requires-python = ">=3.13, <4.0"
 dependencies = [
     "azure-identity (>=1.23.0,<2.0.0)",
     "django (>=5.2.4,<6.0.0)",
@@ -22,7 +22,13 @@ package-mode = false
 [tool.poetry.group.dev.dependencies]
 ruff = "^0.14.5"
 playwright = "^1.56.0"
+behave-django = "^1.8.0"
 
 [build-system]
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"
+
+[tool.behave]
+junit = true
+junit_directory = "tests"
+paths = ["tests"]

pyproject.toml

@@ -0,0 +1 @@
+docker compose run --rm web poetry run python manage.py behave --settings=lung_cancer_screening.settings_test

scripts/tests/ui.sh

@@ -0,0 +1,8 @@
+Feature: Participants with submitted responses
+  Scenario: Cannot change responses once submitted
+    Given a participant abc123 exists
+    And the participant abc123 has submitted their responses
+    And the participant is on the "/start" path
+    When the participant abc123 submits their participant id
+    Then the participant should be on the "/start" path
+    And the participant should see en error summary "Responses have already been submitted for this participant"

tests/features/cannot_change_answers_after_submission.feature

@@ -0,0 +1,65 @@
+"""
+Behave environment setup for Django tests.
+behave-django handles test database setup automatically.
+We just need to add live server and Playwright setup.
+"""
+import os
+from django.contrib.staticfiles.testing import StaticLiveServerTestCase  # noqa: E402
+from playwright.sync_api import sync_playwright  # noqa: E402
+
+# behave-django automatically handles:
+# - Django setup
+# - Test database creation
+# - Database transactions per scenario
+
+
+class LiveServer(StaticLiveServerTestCase):
+    """Live server for Behave tests - extends Django's StaticLiveServerTestCase."""
+
+    @classmethod
+    def setUpClass(cls):
+        """Set up live server - called once for all scenarios."""
+        super().setUpClass()
+        os.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"
+
+
+def before_all(context):
+    """Set up before all tests run."""
+    # Set up live server (behave-django handles test database)
+    LiveServer.setUpClass()
+    context.live_server_url = LiveServer.live_server_url
+    context.live_server_class = LiveServer
+
+    # Set up Playwright browser
+    os.environ["DJANGO_ALLOW_ASYNC_UNSAFE"] = "true"
+    context.playwright = sync_playwright().start()
+    context.browser = context.playwright.chromium.launch(headless=True)
+
+
+def after_all(context):
+    """Clean up after all tests run."""
+    # Clean up Playwright
+    if hasattr(context, 'browser'):
+        context.browser.close()
+    if hasattr(context, 'playwright'):
+        context.playwright.stop()
+
+    # Tear down live server (behave-django handles test database teardown)
+    if hasattr(context, 'live_server_class'):
+        LiveServer.tearDownClass()
+
+
+def before_scenario(_context, _scenario):
+    """Set up before each scenario."""
+    # behave-django automatically handles database transactions per scenario
+    pass
+
+
+def after_scenario(context, _scenario):
+    """Clean up after each scenario."""
+    # Close the page if it exists
+    if hasattr(context, 'page'):
+        context.page.close()
+        del context.page
+
+    # behave-django automatically rolls back database transactions

tests/features/environment.py

@@ -0,0 +1,7 @@
+from behave import then
+from playwright.sync_api import expect
+
+
+@then(u'the participant should see en error summary "{error_summary}"')
+def then_the_participant_should_see_an_error_summary(context, error_summary):
+    expect(context.page.locator('#maincontent')).to_contain_text(error_summary)

tests/features/steps/error_steps.py

@@ -0,0 +1,7 @@
+from behave import when
+
+
+@when('the participant {participant_id} submits their participant id')
+def when_the_participant_submits_their_participant_id(context, participant_id):
+    context.page.fill('input[name="participant_id"]', participant_id)
+    context.page.click('button[type="submit"]')

tests/features/steps/form_steps.py

@@ -0,0 +1,12 @@
+from behave import given, then
+from playwright.sync_api import expect
+
+
+@given('the participant is on the "{path}" path')
+def given_the_participant_is_on_the_path(context, path):
+    context.page = context.browser.new_page()
+    context.page.goto(f"{context.live_server_url}{path}")
+
+@then('the participant should be on the "{path}" path')
+def then_the_participant_should_be_on_the_path(context, path):
+    expect(context.page).to_have_url(f"{context.live_server_url}{path}")