streamlit — Cursor Rules

We use playwright with pytest to e2e test Streamlit library. E2E tests verify the complete Streamlit system (frontend, backend, communication, state, visual appearance) from a user's perspective (black-box). They complement Python/JS unit tests, which are faster and focus on internal logic, input/output validation, and specific message sequences. Use E2E tests when testing behavior that requires the full stack or visual verification, especially for new elements or significant changes to existing ones.

• Located in e2e_playwright/ • Each test consists of two files: • *.py: Streamlit app script that's being tested • *_test.py: Playwright pytest file that runs the app and tests it • If the test is specific to a Streamlit element, prefix the filename with st_<element_name> • Tests can use screenshot comparisons for visual verification • All screenshots are stored in e2e_playwright/__snapshots__/<os>/ • Other e2e test results are stored in e2e_playwright/test-results/ which includes: • e2e_playwright/test-results/<test_name>/: Video and traces related to the failed test. • e2e_playwright/test-results/snapshot-tests-failures/<os>/<test_script>/<test_name>/: Expected, actual, and diff screenshots of the failed snapshot test. • e2e_playwright/test-results/snapshot-updates/<os>/<test_script>/<test_name>/: All updated screenshots of the failed test.

Import from conftest.py: • app: Page - Light mode app fixture • themed_app: Page - Light & dark mode app fixture • app_target: AppTarget - App interaction wrapper (supports iframe-hosted external apps) • app_base_url: str - Base URL for app navigation (external or localhost) • build_app_url(...) - URL builder to compose paths/query/fragment from app_base_url • assert_snapshot - Screenshot testing fixture. Ensure element is stable before calling. • wait_for_app_run(app) - Wait for app run to finish • wait_for_app_loaded(app) - Wait for initial app load • rerun_app(app) - Trigger app rerun and wait • wait_until(app, fn) - Run test function until True or timeout

• When writing @pytest.mark.external_test tests, prefer app_target over a bare Page/FrameLocator. It abstracts whether the app DOM is at the top-level (Page) or inside a host page (FrameLocator). • The external_test marker supports a small set of keyword arguments. See e2e_playwright/conftest.py (and pytest --markers) for the canonical list and behavior. • External modes are configured via CLI/env and may affect what fixtures mean: • --external-app-url / STREAMLIT_E2E_EXTERNAL_APP_URL: run against an externally hosted Streamlit app (no local server). • --external-host-url / STREAMLIT_E2E_EXTERNAL_HOST_URL: run against a host page that embeds the app in an iframe (no local server). • --external-iframe-selector / STREAMLIT_E2E_EXTERNAL_IFRAME_SELECTOR: iframe selector inside the host page (defaults to iframe). • Deciding whether a test should be marked external_test is manual for now. Only add the marker when the test is explicitly intended to run against an externally hosted app/host page. • As a rule of thumb, a test is a good candidate for external_test if it: • can run without starting the local app server (it should not depend on the test module's *.py script being launched by the harness), • uses stable selectors and the app_target/app_base_url abstractions (so it works both for top-level and iframe-hosted apps), • avoids relying on local-only infrastructure like request routing/interception (iframed_app) or filesystem-coupled assumptions.