1 files changed, 127 insertions, 0 deletions
diff --git a/tests/integration/README.md b/tests/integration/README.md
new file mode 100644
index 0000000..99f74a6
--- /dev/null
+++ b/tests/integration/README.md
@@ -0,0 +1,127 @@
+# Integration Tests with Selenium
+
+This directory contains Selenium-based integration tests for the web application.
+
+## Setup
+
+1. Install Python dependencies:
+```bash
+pip install -r requirements-test.txt
+```
+
+2. Chrome browser must be installed (ChromeDriver will be downloaded automatically)
+
+## Running Tests
+
+### Run all tests:
+```bash
+pytest
+```
+
+### Run specific test categories:
+```bash
+# Smoke tests only
+pytest -m smoke
+
+# UI interaction tests
+pytest -m ui
+
+# Network tests
+pytest -m network
+```
+
+### Run in headless mode:
+```bash
+$env:HEADLESS="1"; pytest
+```
+
+### Run with verbose output:
+```bash
+pytest -v
+```
+
+### Run specific test file:
+```bash
+pytest tests/integration/test_smoke.py
+```
+
+### Run specific test function:
+```bash
+pytest tests/integration/test_smoke.py::test_page_loads
+```
+
+## How It Works
+
+The test suite automatically:
+1. Starts a local HTTP server on a free port
+2. Serves the application from the `ggj26/` directory
+3. Runs tests against the local server
+4. Shuts down the server when tests complete
+
+This ensures JavaScript features requiring a web server (like CORS, modules, etc.) work correctly.
+
+## Environment Variables
+
+- `APP_URL`: Override the automatic HTTP server to test against an external URL
+  ```bash
+  $env:APP_URL="http://localhost:8080"; pytest
+  ```
+
+- `HEADLESS`: Set to "1" to run tests in headless mode (no visible browser)
+  ```bash
+  $env:HEADLESS="1"; pytest
+  ```
+
+## Test Structure
+
+- `conftest.py`: Pytest fixtures and configuration
+  - `http_server`: Starts local HTTP server (session-scoped)
+  - `base_url`: URL for the application
+  - `driver`: Selenium WebDriver instance
+  - `app`: Loads the application
+  - `ready_app`: Loads app and waits for it to be ready
+  - `wait`: WebDriverWait helper
+
+- `test_smoke.py`: Basic smoke tests to verify core functionality
+- `test_ui.py`: UI interaction tests (clicks, keyboard, mouse)
+
+## Writing New Tests
+
+Example test:
+```python
+import pytest
+from selenium.webdriver.common.by import By
+
+@pytest.mark.smoke
+def test_my_feature(app):
+    """Test description."""
+    element = app.find_element(By.ID, "my-element")
+    assert element.is_displayed()
+```
+
+## Debugging
+
+### View browser during test execution:
+Don't set `HEADLESS=1` - tests will run with visible browser.
+
+### Add breakpoints:
+```python
+import pdb; pdb.set_trace()
+```
+
+### Take screenshots on failure:
+```python
+def test_something(app):
+    try:
+        # test code
+        pass
+    except:
+        app.save_screenshot("failure.png")
+        raise
+```
+
+### Check console logs:
+```python
+logs = app.get_log("browser")
+print(logs)
+```