Playright docs

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

tests/playwright/README.md

@@ -0,0 +1,301 @@
+# 🎭 Playwright UI Tests for MCP Context Forge
+
+This directory contains end-to-end UI tests for the MCP Context Forge admin interface and web UI components using [Playwright](https://playwright.dev/).
+
+## 📁 Directory Structure
+
+```
+tests/playwright/
+├── README.md               # This file
+├── __init__.py            # Package marker
+├── conftest.py            # Pytest fixtures and configuration
+├── test_admin_ui.py       # Admin panel UI tests
+├── test_api_endpoints.py  # API integration tests via UI
+├── test_server_management.py  # Server CRUD operations
+├── pages/                 # Page Object Model
+│   ├── __init__.py
+│   ├── base_page.py       # Base page class
+│   └── admin_page.py      # Admin panel page objects
+├── screenshots/           # Test failure screenshots (auto-created)
+├── reports/              # Test reports (auto-created)
+└── videos/               # Test recordings (auto-created)
+```
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install the project with Playwright dependencies
+pip install -e ".[playwright]"
+
+# Install Playwright browsers (only needed once)
+make playwright-install      # Installs Chromium only
+# OR
+make playwright-install-all  # Installs all browsers (Chromium, Firefox, WebKit)
+```
+
+### Running Tests
+
+```bash
+# Start the MCP Gateway server first
+make serve
+
+# In another terminal, run the tests:
+make test-ui              # Run with visible browser
+make test-ui-headless     # Run in headless mode (CI/CD)
+make test-ui-debug        # Run with Playwright Inspector
+make test-ui-smoke        # Run only smoke tests (fast)
+make test-ui-report       # Generate HTML report
+```
+
+## 🧪 Test Categories
+
+Tests are organized by functionality and tagged with pytest markers:
+
+- **`@pytest.mark.smoke`** - Quick validation tests that run in < 30 seconds
+- **`@pytest.mark.ui`** - UI interaction tests
+- **`@pytest.mark.api`** - API endpoint tests through the UI
+- **`@pytest.mark.e2e`** - Full end-to-end workflows
+- **`@pytest.mark.slow`** - Tests that take > 1 minute
+
+### Running Specific Test Categories
+
+```bash
+# Run only smoke tests
+pytest tests/playwright -m smoke
+
+# Run all except slow tests
+pytest tests/playwright -m "not slow"
+
+# Run UI and API tests
+pytest tests/playwright -m "ui or api"
+```
+
+## 📝 Writing Tests
+
+### Basic Test Structure
+
+```python
+import pytest
+from playwright.sync_api import Page, expect
+
+class TestFeatureName:
+    """Test suite for specific feature."""
+    
+    @pytest.mark.smoke
+    def test_basic_functionality(self, page: Page, base_url: str):
+        """Test description."""
+        # Navigate
+        page.goto(f"{base_url}/admin")
+        
+        # Assert page loaded
+        expect(page).to_have_title("MCP Gateway Admin")
+        
+        # Interact with elements
+        page.click('button:has-text("Add Server")')
+        
+        # Verify results
+        modal = page.locator('[role="dialog"]')
+        expect(modal).to_be_visible()
+```
+
+### Using Page Objects
+
+```python
+from tests.playwright.pages.admin_page import AdminPage
+
+def test_with_page_object(page: Page, base_url: str):
+    """Test using page object pattern."""
+    admin = AdminPage(page, base_url)
+    admin.navigate()
+    admin.add_server("Test Server", "http://localhost:9000")
+    assert admin.server_exists("Test Server")
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```bash
+# Base URL for testing (default: http://localhost:4444)
+export TEST_BASE_URL=http://localhost:8000
+
+# Authentication token
+export MCP_AUTH_TOKEN=your-test-token
+
+# Playwright options
+export PWDEBUG=1           # Enable Playwright Inspector
+export HEADED=1            # Force headed mode
+export SLOWMO=100          # Add 100ms delay between actions
+```
+
+### pyproject.toml Configuration
+
+The project's `pyproject.toml` includes Playwright configuration in `[tool.pytest.ini_options]`:
+
+- Default browser: `chromium`
+- Screenshots: `only-on-failure`
+- Videos: `retain-on-failure`
+- Traces: `retain-on-failure`
+
+## 🐛 Debugging Tests
+
+### 1. Playwright Inspector
+
+```bash
+make test-ui-debug
+# OR
+PWDEBUG=1 pytest tests/playwright/test_admin_ui.py -s
+```
+
+This opens the Playwright Inspector with:
+- Step through each action
+- See selector playground
+- Record new tests
+
+### 2. Headed Mode
+
+```bash
+make test-ui
+# OR
+pytest tests/playwright --headed
+```
+
+### 3. Slow Motion
+
+```bash
+pytest tests/playwright --headed --slowmo 1000  # 1 second delay
+```
+
+### 4. Screenshots and Videos
+
+Failed tests automatically capture:
+- Screenshots in `tests/playwright/screenshots/`
+- Videos in `test-results/` (when enabled)
+- Traces for debugging (when enabled)
+
+### 5. VS Code Debugging
+
+Add to `.vscode/launch.json`:
+
+```json
+{
+    "name": "Debug Playwright Test",
+    "type": "python",
+    "request": "launch",
+    "module": "pytest",
+    "args": [
+        "tests/playwright/test_admin_ui.py::TestAdminUI::test_admin_panel_loads",
+        "-v",
+        "--headed"
+    ],
+    "env": {
+        "PWDEBUG": "console"
+    }
+}
+```
+
+## 📊 Test Reports
+
+### HTML Report
+
+```bash
+make test-ui-report
+open tests/playwright/reports/report.html
+```
+
+### Coverage Report
+
+```bash
+make test-ui-coverage
+open tests/playwright/reports/coverage/index.html
+```
+
+### CI/CD Integration
+
+Tests run automatically on GitHub Actions for:
+- Pull requests
+- Pushes to main/develop branches
+- Changes to UI code or test files
+
+## ⚡ Performance Tips
+
+1. **Use `test-ui-parallel` for faster execution**:
+   ```bash
+   make test-ui-parallel  # Runs tests in parallel
+   ```
+
+2. **Run only affected tests**:
+   ```bash
+   pytest tests/playwright -k "server"  # Only server-related tests
+   ```
+
+3. **Skip slow tests during development**:
+   ```bash
+   pytest tests/playwright -m "not slow"
+   ```
+
+4. **Reuse browser context** for related tests (see conftest.py)
+
+## 🏗️ Best Practices
+
+1. **Use Page Object Model** - Encapsulate page interactions in page classes
+2. **Explicit Waits** - Use `page.wait_for_selector()` instead of `time.sleep()`
+3. **Meaningful Assertions** - Use Playwright's `expect()` API for auto-waiting
+4. **Test Isolation** - Each test should be independent
+5. **Descriptive Names** - Test names should explain what they verify
+6. **Error Messages** - Include context in assertion messages
+7. **Cleanup** - Tests should clean up created resources
+
+## 🔍 Common Issues
+
+### Server Not Running
+
+```bash
+# Error: Connection refused to localhost:4444
+# Solution: Start the server first
+make serve
+```
+
+### Browser Not Installed
+
+```bash
+# Error: Executable doesn't exist at...
+# Solution: Install browsers
+make playwright-install
+```
+
+### Flaky Tests
+
+```python
+# Add retries for flaky tests
+@pytest.mark.flaky(reruns=3, reruns_delay=1)
+def test_sometimes_flaky(page):
+    # test code
+```
+
+### Timeout Issues
+
+```python
+# Increase timeout for slow operations
+page.set_default_timeout(30000)  # 30 seconds
+# OR
+page.click("button", timeout=10000)  # 10 seconds for this action
+```
+
+## 📚 Resources
+
+- [Playwright Python Documentation](https://playwright.dev/python/)
+- [Playwright Best Practices](https://playwright.dev/docs/best-practices)
+- [pytest-playwright Plugin](https://github.com/microsoft/playwright-pytest)
+- [MCP Gateway Documentation](https://ibm.github.io/mcp-context-forge/)
+
+## 🤝 Contributing
+
+1. Follow the existing test patterns
+2. Add appropriate test markers
+3. Update page objects for new UI elements
+4. Include docstrings explaining test purpose
+5. Run `make test-ui` locally before submitting PR
+6. Ensure all smoke tests pass