Enhance the Playwright test suite with comprehensive documentation, i… (#504)

* Enhance the Playwright test suite with comprehensive documentation, implementing proper page object naming conventions, and working tests cases

Signed-off-by: Manav Gupta <[email protected]>

* fix: resolve flake8 DAR203 error and pre-commit hook issues

- Fix docstring return type mismatch in forward_request method
- Update pre-commit config to exclude page objects from test naming
- Add UTF-8 encoding pragma and fix file formatting

These changes ensure code quality standards are met and resolve
linting issues discovered during Playwright test development.

* Update pytest.ini to include all test directories in testpaths

Signed-off-by: Manav Gupta <[email protected]>

* Updated pytest.ini to exclude playwright tests from make test and CI/CD

Signed-off-by: Manav Gupta <[email protected]>

* Resolve merge conflicts in .pre-commit-config.yaml and forward.py

---------

Signed-off-by: Manav Gupta <[email protected]>

Author: manavgup

Makefile

@@ -2715,18 +2715,32 @@ playwright-install-all:
 ## --- UI Test Execution ------------------------------------------------------
 test-ui: playwright-install
 	@echo "🎭 Running UI tests with visible browser..."
+	@echo "💡 Make sure the dev server is running: make dev"
 	@test -d "$(VENV_DIR)" || $(MAKE) venv
 	@mkdir -p $(PLAYWRIGHT_SCREENSHOTS) $(PLAYWRIGHT_REPORTS)
+	@if ! curl -s http://localhost:8000/health >/dev/null 2>&1; then \
+		echo "❌ Dev server not running on http://localhost:8000"; \
+		echo "💡 Start it with: make dev"; \
+		exit 1; \
+	fi
 	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
-		pytest $(PLAYWRIGHT_DIR)/ -v --headed --screenshot=only-on-failure \
+		export TEST_BASE_URL=http://localhost:8000 && \
+		python -m pytest tests/playwright/ -v --headed --screenshot=only-on-failure \
 		--browser chromium || { echo '❌ UI tests failed!'; exit 1; }"
 	@echo "✅ UI tests completed!"
 
 test-ui-headless: playwright-install
 	@echo "🎭 Running UI tests in headless mode..."
+	@echo "💡 Make sure the dev server is running: make dev"
 	@test -d "$(VENV_DIR)" || $(MAKE) venv
 	@mkdir -p $(PLAYWRIGHT_SCREENSHOTS) $(PLAYWRIGHT_REPORTS)
+	@if ! curl -s http://localhost:8000/health >/dev/null 2>&1; then \
+		echo "❌ Dev server not running on http://localhost:8000"; \
+		echo "💡 Start it with: make dev"; \
+		exit 1; \
+	fi
 	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
+		export TEST_BASE_URL=http://localhost:8000 && \
 		pytest $(PLAYWRIGHT_DIR)/ -v --screenshot=only-on-failure \
 		--browser chromium || { echo '❌ UI tests failed!'; exit 1; }"
 	@echo "✅ UI tests completed!"

mcpgateway/templates/admin.html

@@ -49,11 +49,11 @@ <h1 class="text-3xl font-bold text-gray-800 dark:text-gray-200">
     <div class="mb-8">
       <div class="border-b border-gray-200">
         <nav class="-mb-px flex space-x-8">
-          <a href="#catalog" id="tab-catalog"
+          <a href="#catalog" id="tab-catalog" data-testid="servers-tab"
             class="tab-link border-indigo-500 text-indigo-600 dark:text-indigo-500 whitespace-nowrap py-4 px-1 border-b-2 font-medium text-sm">
             Virtual Servers Catalog
           </a>
-          <a href="#tools" id="tab-tools"
+          <a href="#tools" id="tab-tools" data-testid="tools-tab"
             class="tab-link border-transparent text-gray-500 dark:text-gray-300 hover:text-gray-700 hover:border-gray-300 whitespace-nowrap py-4 px-1 border-b-2 font-medium text-sm">
             Global Tools
           </a>
@@ -65,7 +65,7 @@ <h1 class="text-3xl font-bold text-gray-800 dark:text-gray-200">
             class="tab-link border-transparent text-gray-500 dark:text-gray-300 hover:text-gray-700 hover:border-gray-300 whitespace-nowrap py-4 px-1 border-b-2 font-medium text-sm">
             Global Prompts
           </a>
-          <a href="#gateways" id="tab-gateways"
+          <a href="#gateways" id="tab-gateways" data-testid="gateways-tab"
             class="tab-link border-transparent text-gray-500 dark:text-gray-300 hover:text-gray-700 hover:border-gray-300 whitespace-nowrap py-4 px-1 border-b-2 font-medium text-sm">
             Gateways/MCP Servers
           </a>
@@ -95,14 +95,20 @@ <h1 class="text-3xl font-bold text-gray-800 dark:text-gray-200">
     <!-- Catalog Panel -->
     <div id="catalog-panel" class="tab-panel">
       <div class="flex justify-between items-center mb-4">
-        <h2 class="text-2xl font-bold dark:text-gray-200">MCP Servers Catalog</h2>
-        <p class="text-sm text-gray-600 dark:text-gray-400 mt-1">Virtual Servers let you combine Tools, Resources, and
-          Prompts from the global Tools catalog into a reusable configuration.</p>
+        <div>
+          <h2 class="text-2xl font-bold dark:text-gray-200">MCP Servers Catalog</h2>
+          <p class="text-sm text-gray-600 dark:text-gray-400 mt-1">Virtual Servers let you combine Tools, Resources, and
+            Prompts from the global Tools catalog into a reusable configuration.</p>
+        </div>
 
-        <div class="flex items-center">
-          <input type="checkbox" id="show-inactive-servers" class="mr-2" onchange="toggleInactiveItems('servers')" />
-          <label for="show-inactive-servers" class="text-sm font-medium text-gray-700 dark:text-gray-300">Show
-            Inactive</label>
+        <div class="flex items-center space-x-4">
+          <input type="text" data-testid="search-input" placeholder="Search servers..."
+            class="mt-1 block w-full rounded-md border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500 dark:bg-gray-900 dark:placeholder-gray-300 dark:text-gray-300" />
+          <div class="flex items-center">
+            <input type="checkbox" id="show-inactive-servers" class="mr-2" onchange="toggleInactiveItems('servers')" />
+            <label for="show-inactive-servers" class="text-sm font-medium text-gray-700 dark:text-gray-300">Show
+              Inactive</label>
+          </div>
         </div>
       </div>
       <div class="bg-white shadow rounded-lg p-6 mb-8 dark:bg-gray-800">
@@ -148,9 +154,9 @@ <h2 class="text-2xl font-bold dark:text-gray-200">MCP Servers Catalog</h2>
                 </th>
               </tr>
             </thead>
-            <tbody class="bg-white divide-y divide-gray-200 dark:bg-gray-900 dark:divide-gray-700">
+            <tbody data-testid="server-list" class="bg-white divide-y divide-gray-200 dark:bg-gray-900 dark:divide-gray-700">
               {% for server in servers %}
-              <tr>
+              <tr data-testid="server-item">
                 <td class="px-6 py-4 whitespace-nowrap">
                   {% if server.icon %}
                   <img src="{{ server.icon }}" alt="{{ server.name }} Icon" class="h-8 w-8" />
@@ -284,7 +290,7 @@ <h3 class="text-lg font-bold mb-4 dark:text-gray-200">Add New Server</h3>
             </div>
           </div>
           <div class="mt-6">
-            <button type="submit"
+            <button type="submit" data-testid="add-server-btn"
               x-tooltip="'💡Creates a new Virtual Server by combining Tools, Resources & Prompts from global catalogs.'"
               class="inline-flex justify-center py-2 px-4 border border-transparent shadow-sm text-sm font-medium rounded-md text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500">
               Add Server

playwright.config.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+import os
+from playwright.sync_api import Playwright
+
+def pytest_configure(config):
+    """Configure Playwright for pytest runs."""
+    os.environ.setdefault("PLAYWRIGHT_BROWSERS_PATH", os.path.expanduser("~/.cache/ms-playwright"))
+
+def pytest_playwright_setup(playwright: Playwright):
+    """Setup Playwright browsers and configuration for pytest runs."""
+    return {
+        "base_url": os.getenv("TEST_BASE_URL", "http://localhost:8000"),
+        "screenshot": "only-on-failure",
+        "video": "retain-on-failure",
+        "trace": "retain-on-failure",
+    }

pytest.ini

@@ -0,0 +1,10 @@
+[pytest]
+addopts = --tb=short --strict-markers --disable-warnings --color=yes
+testpaths = tests tests/unit tests/integration
+
+markers =
+    smoke: marks tests as smoke tests
+    slow: marks tests as slow
+    auth: marks tests as authentication related
+    htmx: marks tests as HTMX related
+    api: marks tests as API related

tests/playwright/README.md

@@ -7,16 +7,24 @@ This directory contains end-to-end UI tests for the MCP Context Forge admin inte
 ```
 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
+├── test_api_integration.py # API protocol tests
+├── test_auth.py           # Authentication tests
+├── test_htmx_interactions.py # HTMX interaction tests
+├── test_realtime_features.py # Real-time feature tests
+├── entities/              # CRUD tests for admin entities
+│   ├── .gitkeep
+│   └── test_tools.py      # Tools CRUD operations
+├── api/                   # API protocol and REST endpoint tests
+│   └── .gitkeep
+├── fixtures/              # Shared fixtures, test data factories
+│   └── .gitkeep
 ├── 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)
+├── screenshots/           # Visual regression baseline images
 ├── reports/              # Test reports (auto-created)
 └── videos/               # Test recordings (auto-created)
 ```
@@ -248,6 +256,13 @@ Tests run automatically on GitHub Actions for:
 6. **Error Messages** - Include context in assertion messages
 7. **Cleanup** - Tests should clean up created resources
 
+## 📂 Adding Tests
+
+- Place CRUD tests in `entities/` directory
+- Place protocol/REST/error tests in `api/` directory
+- Add shared fixtures/page objects in `fixtures/` directory
+- Visual regression baselines go in `screenshots/` directory
+
 ## 🔍 Common Issues
 
 ### Server Not Running
@@ -299,3 +314,5 @@ page.click("button", timeout=10000)  # 10 seconds for this action
 4. Include docstrings explaining test purpose
 5. Run `make test-ui` locally before submitting PR
 6. Ensure all smoke tests pass
+
+See the main project README for more details.

tests/playwright/api/.gitkeep

@@ -12,9 +12,11 @@
 # Third-Party
 from playwright.sync_api import APIRequestContext, Page, Playwright
 import pytest
+import re
+from playwright.sync_api import Page, Browser, BrowserContext
 
 # Get configuration from environment
-BASE_URL = os.getenv("TEST_BASE_URL", "http://localhost:4444")
+BASE_URL = os.getenv("TEST_BASE_URL", "http://localhost:8000")
 API_TOKEN = os.getenv("MCP_AUTH_TOKEN", "test-token")
 
 # Basic Auth credentials - these MUST be set in environment
@@ -58,6 +60,7 @@ def api_request_context(
 def page(browser) -> Generator[Page, None, None]:
     """Create page with Basic Auth credentials."""
     context = browser.new_context(
+        base_url=BASE_URL,
         http_credentials={
             "username": BASIC_AUTH_USER,
             "password": BASIC_AUTH_PASSWORD,
@@ -74,3 +77,34 @@ def page(browser) -> Generator[Page, None, None]:
 def authenticated_page(page: Page) -> Page:
     """Alias for page fixture."""
     return page
+
+@pytest.fixture
+def admin_page(page: Page):
+    """Provide a logged-in admin page for UI tests."""
+    # Go directly to admin - HTTP Basic Auth is handled by the page fixture
+    page.goto("/admin")
+    # Verify we're on the admin page
+    page.wait_for_url(re.compile(r".*admin"))
+    return page
+
+@pytest.fixture
+def test_tool_data():
+    """Provide test data for tool creation."""
+    import uuid
+    unique_id = uuid.uuid4()
+    return {
+        "name": f"test-api-tool-{unique_id}",
+        "description": "Test API tool for automation",
+        "url": "https://api.example.com/test",
+        "integrationType": "REST",
+        "requestType": "GET",
+        "headers": '{"Authorization": "Bearer test-token"}',
+        "input_schema": '{"type": "object", "properties": {"query": {"type": "string"}}}'
+    }
+
+@pytest.fixture(autouse=True)
+def setup_test_environment(page: Page):
+    """Set viewport and default timeout for consistent UI tests."""
+    page.set_viewport_size({"width": 1280, "height": 720})
+    page.set_default_timeout(30000)
+    # Optionally, add request logging or interception here

tests/playwright/conftest.py

@@ -0,0 +1,70 @@
+# -*- coding: utf-8 -*-
+import pytest
+from playwright.sync_api import Page, expect
+
+class TestToolsCRUD:
+    """CRUD tests for Tools entity in MCP Gateway Admin UI.
+
+    Examples:
+        pytest tests/playwright/entities/test_tools.py
+    """
+    def test_create_new_tool(self, page: Page, test_tool_data, admin_page):
+        """Test creating a new tool with debug screenshots and waits."""
+        # Go to the Global Tools tab (if not already there)
+        page.click('[data-testid="tools-tab"]')
+
+        # Wait for the tools panel to be visible
+        page.wait_for_selector('#tools-panel:not(.hidden)')
+
+        # Add a small delay to ensure the UI has time to update
+        page.wait_for_timeout(500)
+
+        # Fill the always-visible form
+        page.locator('#add-tool-form [name="name"]').fill(test_tool_data["name"])
+        page.wait_for_timeout(300)
+        page.locator('#add-tool-form [name="url"]').fill(test_tool_data["url"])
+        page.wait_for_timeout(300)
+        page.locator('#add-tool-form [name="description"]').fill(test_tool_data["description"])
+        page.wait_for_timeout(300)
+        page.locator('#add-tool-form [name="integrationType"]').select_option(test_tool_data["integrationType"])
+        page.wait_for_timeout(300)
+
+        # Submit the form
+        page.click('#add-tool-form button[type="submit"]')
+
+        # Assert the tool appears in the table
+        expect(page.locator("#tools-panel table")).to_contain_text(test_tool_data["name"])
+
+    def test_delete_tool(self, page: Page, test_tool_data, admin_page):
+        """Test deleting a tool."""
+        # Go to the Global Tools tab (if not already there)
+        page.click('[data-testid="tools-tab"]')
+
+        # Wait for the tools panel to be visible
+        page.wait_for_selector('#tools-panel:not(.hidden)')
+
+        # Create tool first
+        page.locator('#add-tool-form [name="name"]').fill(test_tool_data["name"])
+        page.wait_for_timeout(300)
+        page.locator('#add-tool-form [name="url"]').fill(test_tool_data["url"])
+        page.wait_for_timeout(300)
+        page.locator('#add-tool-form [name="description"]').fill(test_tool_data["description"])
+        page.wait_for_timeout(300)
+        page.locator('#add-tool-form [name="integrationType"]').select_option(test_tool_data["integrationType"])
+        page.wait_for_timeout(300)
+        page.click('#add-tool-form button[type="submit"]')
+        expect(page.locator("#tools-panel table")).to_contain_text(test_tool_data["name"])
+
+        # Delete tool
+        tool_row = page.locator(f'#tools-panel tbody tr:has-text("{test_tool_data["name"]}")')
+
+        # Set up dialog handler before clicking delete
+        page.on("dialog", lambda dialog: dialog.accept())
+
+        tool_row.locator('button:has-text("Delete")').click()
+
+        # Wait a moment for the deletion to process
+        page.wait_for_timeout(1000)
+
+        # Assert the tool is no longer in the table
+        expect(page.locator(f'#tools-panel tbody tr:has-text("{test_tool_data["name"]}")')).not_to_be_visible()

tests/playwright/entities/test_tools.py

@@ -12,13 +12,15 @@ class AdminPage(BasePage):
     """Admin panel page object."""
 
     # Selectors
-    SERVERS_TAB = '[data-tab="servers"]'
-    TOOLS_TAB = '[data-tab="tools"]'
-    GATEWAYS_TAB = '[data-tab="gateways"]'
-    ADD_SERVER_BTN = 'button:has-text("Add Server")'
-    SERVER_LIST = ".server-list"
-    SERVER_ITEM = ".server-item"
-    SEARCH_INPUT = 'input[placeholder*="Search"]'
+    SERVERS_TAB = '[data-testid="servers-tab"]'
+    TOOLS_TAB = '[data-testid="tools-tab"]'
+    GATEWAYS_TAB = '[data-testid="gateways-tab"]'
+    ADD_SERVER_BTN = '[data-testid="add-server-btn"]'
+    SERVER_LIST = '[data-testid="server-list"]'
+    SERVER_ITEM = '[data-testid="server-item"]'
+    SEARCH_INPUT = '[data-testid="search-input"]'
+    SERVER_NAME_INPUT = 'input[name="name"]'
+    SERVER_ICON_INPUT = 'input[name="icon"]'
 
     def __init__(self, page: Page, base_url: str):
         super().__init__(page)
@@ -42,14 +44,11 @@ def click_gateways_tab(self) -> None:
         """Click on gateways tab."""
         self.click_element(self.GATEWAYS_TAB)
 
-    def add_server(self, name: str, url: str) -> None:
+    def add_server(self, name: str, icon_url: str) -> None:
         """Add a new server."""
+        self.fill_input(self.SERVER_NAME_INPUT, name)
+        self.fill_input(self.SERVER_ICON_INPUT, icon_url)
         self.click_element(self.ADD_SERVER_BTN)
-        # Wait for modal
-        self.wait_for_element('input[name="name"]')
-        self.fill_input('input[name="name"]', name)
-        self.fill_input('input[name="url"]', url)
-        self.click_element('button:has-text("Save")')
 
     def search_servers(self, query: str) -> None:
         """Search for servers."""