Cursor rule

1---
2description: Pytest Integration Tests
3globs: tests/integration/**/*.py
4alwaysApply: false
5---
6## Pytest Integration Tests
7 
8 
9- Look to `app/factories/` to generate any required database state
10  - Here's an example of how to create + persist a factory `DistributionFactory.save(domain=PYTHON_TEST_SERVER_HOST)`
11- Add the `server` factory to each test
12- Use the `faker` factory to generate emails, etc.
13- Don't add obvious `assert` descriptions
14- Do not use the `db_session` fixture here. Instead, use `with test_session():` if you need to setup complex database state
15- if a UI timeout is occuring, it could be because it cannot find a element because the rendering has changed. Check the failure screenshot and see if you can correct the test assertion.
16- The integration tests can take a very long time to run. Do not abort them if they are taking a long time.
17- Use `expect(page.get_by_text("Screening is fully booked")).to_be_visible()` instead of `expect(page.get_by_role("heading")).to_contain_text("Screening is fully booked")`. It's less brittle.
18- Do not use `client` fixtures in an integration test. Integration tests should only use the frontend of the website to interact with the application, not the API.
19- Use `with page.expect_response("https://example.com/resource") as response_info:` to assert against network activity.
20- Do not `next_button.evaluate("el => el.click()")` instead, just `locator.click()`. If this doesn't work, stop your work and let me know.
21- Only use `wait_for_loading(page)` if a `LONG_INTEGRATION_TEST_TIMEOUT` on an expectation does not work: `expect(page.get_by_text("Your Matched Doctors")).to_be_visible(timeout=LONG_INTEGRATION_TEST_TIMEOUT)`
22  - `LONG_INTEGRATION_TEST_TIMEOUT` should only be used as a last resort. If you have many of these in a test, let me know and I will debug it.
23- Prefer fewer integration tests that cover more functionality. Unlike unit tests, where each test is designed to test a very particular piece of functionality, I want integration tests to cover entire workflows. It's preferred to add more steps to an integration test to test an entire workflow.
24- Prefer simple locators. If a `filter`, `or_`, etc is required to capture a button in multiple states it indicates something is wrong in the code.
25- Use `react_router_url` to generate the frontend url path and do not set `base_url`.
26- End all Playwright tests with `from pytest_playwright_artifacts import assert_no_console_errors` and `assert_no_console_errors(request)` (capture is the plugin's `playwright_console_logging` fixture).
27  - Test-Specific Ignores: Pass `ignore=[...]` to `assert_no_console_errors` per `pytest-playwright-artifacts` (regex strings, compiled patterns, or `{"file": "...", "message": "..."}` dicts); add a comment explaining why.
28  - Global Ignores: Use `playwright_console_ignore` under `[tool.pytest.ini_options]` in `pyproject.toml` (see `pytest-playwright-artifacts` README).
29 
30### Example Integration Test
31 
32Below is an example test. Notice the following:
33 
34- Code comments are used to describe the key user steps that are being tested
35- We avoid long timeouts or wait commands
36- Fixtures and factories are generated at the beginning of the test
37- We assert against database state after each major user action
38- Some of the comments (i.e. comments on included fixtures) are included for instructional purposes only and should not be included in the tests you write
39 
40```python
41from pytest_playwright_artifacts import assert_no_console_errors
42 
43 
44def test_streaming_checkout_creates_user_and_links_order(
45    # this fixture ensures that the underlying python server is started
46    server,
47    faker,
48    page: Page,
49    # if you need to create objects (like factories) tied to a common session, include this fixture
50    db_truncate_session,
51    # for asserting against the console logs
52    request: FixtureRequest,
53) -> None:
54    distribution = DistributionWithWebhooksFactory.save()
55    test_email = clerk_test_email()
56 
57    # 1) Run through streaming checkout
58    page.goto(react_router_url("/streaming"))
59 
60    page.get_by_placeholder("your@email.com").first.fill(test_email)
61    page.get_by_placeholder("your@email.com").last.fill(test_email)
62 
63    # Check TOS
64    page.get_by_role("checkbox").last.check()
65 
66    fill_stripe_checkout(page)
67 
68    # 2) Complete checkout
69    # the stripe checkout form will expand and cause the purchase button to move below the screen
70    safely_scroll_then_click(page.get_by_role("button", name="Complete Purchase"))
71 
72    expect(page.get_by_role("heading", name="You're ready to watch!")).to_be_visible()
73    page.get_by_role("link", name="Login & Start Watching").click()
74 
75    # 3) Assert against database and Clerk state
76 
77    # One StreamingOrder should be created for this distribution and email
78    assert StreamingOrder.count() == 1
79    streaming_order = StreamingOrder.get(email=test_email)
80    assert streaming_order
81 
82    assert streaming_order.status.value == "completed"
83    assert streaming_order.user_id is not None
84 
85    # 4) Login to the app via the Clerk login page
86    clerk_login_and_verify(page, test_email)
87 
88    expect(page.get_by_text("Triumph of the Heart").first).to_be_visible()
89 
90    # 5) Play the video
91    page.get_by_role("button").filter(has_text="Play").click()
92 
93    # wait for the page to completely load
94    wait_for_loading(page)
95 
96    expect(page.get_by_text("Triumph of the Heart").first).to_be_visible()
97    expect(page.get_by_text("Play")).not_to_be_visible()
98 
99    assert_no_console_errors(
100        request,
101        ignore=[
102            {
103              # if there are console errors specific to the project, exclude them here. Match to the specific URL if you can.
104              "file": r"https://iframe.cloudflarestream.com/.*",
105              "message": "the server responded with a status of 403",
106            }
107        ],
108    )
109```
110