diff --git a/.github/workflows/README.md b/.github/workflows/README.md index a320e08..0d32d0c 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -5,6 +5,7 @@ This directory contains GitHub Actions workflow files that automate various task ## Files - [codeql-analysis.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/codeql-analysis.yml): Performs CodeQL security analysis on the codebase to identify potential vulnerabilities. +- [deploy-docker.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-docker.yml): Automatically builds and publishes the lightweight Caddy-based Docker image of the application to GitHub Container Registry (GHCR). - [deploy-everywhere.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-everywhere.yml): A manually triggered workflow that initiates deployment to both GitHub Pages and WikiTree Apps by calling their respective workflow files. - [deploy-gh-pages.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-gh-pages.yml): Handles the deployment of the application to GitHub Pages. - [deploy-wikitree-apps.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-wikitree-apps.yml): Manages the deployment of the application to WikiTree Apps using SFTP. diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md index 83bf181..10a360c 100644 --- a/PROJECT_STRUCTURE.md +++ b/PROJECT_STRUCTURE.md @@ -35,6 +35,7 @@ Here is an enumeration of the files in this directory, categorized by their role ### Documentation & Assets * **[README.md](README.md)**: The main project documentation, covering features, examples, and usage instructions. * **[CHANGELOG.md](CHANGELOG.md)**: Records a log of notable changes made to the project over time. +* **[docs/README.md](docs/README.md)**: Registry for system design files describing containerization, AI protocol interfaces, Playwright integration, and screenshot testing. * **[LICENSE](LICENSE)**: The license file for the project (Apache License 2.0). * **[screenshot.png](screenshot.png)**: An image showing a screenshot of the application, used in the README.md. @@ -42,6 +43,7 @@ Here is an enumeration of the files in this directory, categorized by their role Based on the documentation in the subdirectories, here is a high-level overview of the project's structure: +* **[docs](docs)**: High-level technical and architectural design documents. * **[src](src)**: The core of the application. * **[datasource](src/datasource)**: Handles loading and transforming genealogical data from various sources (files, URLs, WikiTree). * **[menu](src/menu)**: Contains navigation and menu components. diff --git a/docs/README.md b/docs/README.md index f7650e2..72fd6b1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,4 +9,6 @@ While new features *may* follow this methodology to ensure robust design validat ## Design Documents Registry * **[DOCKER_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/DOCKER_DESIGN.md)**: Docker container packaging, lightweight Caddy web server configuration, and GitHub Actions publishing pipelines. +* **[PLAYWRIGHT_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/PLAYWRIGHT_DESIGN.md)**: Playwright E2E testing architecture, Vite development/preview server lifecycle integration, tracking blocker interceptors, and embedded iframe communication. +* **[SCREENSHOT_TESTS_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/SCREENSHOT_TESTS_DESIGN.md)**: Pixel-perfect visual regression testing infrastructure, animation stabilization, sandbox environment/DOM sanitization, and isolated Playwright projects. * **[WEBMCP_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/WEBMCP_DESIGN.md)**: Model Context Protocol (MCP) bridge and TS tool registration for AI agent interaction. diff --git a/src/README.md b/src/README.md index 0b339c3..84e7c15 100644 --- a/src/README.md +++ b/src/README.md @@ -18,6 +18,9 @@ This directory contains the main source code for the Topola Viewer application. * **[donatso-chart.tsx](donatso-chart.tsx)**: An alternative chart view utilizing the `family-chart` library. * **[index.tsx](index.tsx)**: The entry point of the application. It sets up polyfills, internationalization, and renders the app root. * **[intro.tsx](intro.tsx)**: The landing page component shown when no data is loaded. It provides instructions, examples, and privacy information. +* **[webmcp.ts](webmcp.ts)**: Model Context Protocol (MCP) implementation to expose viewer state and action handlers for dynamic AI model interactions and tool definitions. +* **[webmcp_definitions.ts](webmcp_definitions.ts)**: Defines custom schemas and descriptions for various registration tools (such as person search, ancestry detail fetch, navigation triggers, etc.) exposed through the WebMCP protocol. +* **[webmcp_types.ts](webmcp_types.ts)**: Common TypeScript type annotations and structures used within the WebMCP engine layer. ## Assets diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..96dbae9 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,61 @@ +# End-to-End & Visual Testing Suite (`tests`) + +This directory houses all automated test specifications and validation fixtures for validating the **Topola Genealogy Viewer** application. The tests are powered by the modern Playwright framework to offer robust, type-safe end-to-end (E2E) user flows and pixel-perfect visual regression validations. + +## Test Design Reference Documents + +Before writing new or adjusting existing tests, developers should review their corresponding systems design guidelines under the `docs/` directory to align with established conventions and paradigms: +* **[PLAYWRIGHT_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/PLAYWRIGHT_DESIGN.md)**: Explains overall Playwright orchestration, server hooks, mock GEDCOM network intercept routines, tracking blockages, and in-memory iframe environments. +* **[SCREENSHOT_TESTS_DESIGN.md](file:///home/pwiech/personal/github/topola-viewer/docs/SCREENSHOT_TESTS_DESIGN.md)**: Outlines visual testing strategies, viewport locks, dynamic footer/changelog sanitization overrides in virtual DOMs, threshold sensitivities, and local baseline update policies. + +--- + +## Test Specs Registry + +Tests are strategically partitioned into standard functional E2E specs and isolated visual regression specs (which are tagged and grouped into targeted Playwright projects). + +### 1. Functional E2E Specs +Verify functional correctness, route parameters, drawer side-panels, dynamic autocomplete searching, and external/bidirectional event loops. +* **[chart_view.spec.ts](chart_view.spec.ts)**: Asserts core tree rendering from mock network parameters, navigation shifts, transition handling, and card node interaction. +* **[embedded.spec.ts](embedded.spec.ts)**: Tests embedded iframe operations using virtual server postMessage listeners to execute proper parent-child synchronizations. +* **[intro.spec.ts](intro.spec.ts)**: Checks base landing layouts, instructions panels, menu existence, and responsive header navigation buttons. +* **[search.spec.ts](search.spec.ts)**: Targets autocompletion components using robust search locators to verify input debouncing and focus updates. +* **[webmcp.spec.ts](webmcp.spec.ts)**: Evaluates out-of-process browser calls from Model Context Protocol tool registrations and action assertions. + +### 2. Visual Regression / Screenshot Specs +Capture pixel-perfect layout comparisons against preserved snapshots to detect subtle structural overlaps or rendering discrepancies. +* **[charts_visual.spec.ts](charts_visual.spec.ts)**: Loops through multiple layouts (`Hourglass`, `Relatives`, `Donatso`) using a local GEDCOM dataset to ensure aesthetic layout alignments. +* **[config_visual.spec.ts](config_visual.spec.ts)**: Asserts full-window UI synchronization states while settings choices (like colored genders, hidden node IDs, or compact profiles) are toggled. +* **[details_visual.spec.ts](details_visual.spec.ts)**: Checks that intricate information templates (e.g., complex multiline fact headers, embedded picture borders, and source list grids) are structured beautifully under edge cases. +* **[intro_visual.spec.ts](intro_visual.spec.ts)**: Validates static landing layouts. Pre-evaluates dynamic sections (e.g. version/commit logs) to replace them with fixed test markers for baseline durability. + +--- + +## Supporting Infrastructure + +To enable lightweight, reproducible, and offline executions, tests rely on the following configuration, definitions, and test data structures: + +* **[fixtures/embedded_frame.html](fixtures/embedded_frame.html)**: HTML template for serving cross-origin iframe wrapper mockups virtually to the browser container. +* **[global.d.ts](global.d.ts)**: TypeScript declarations defining window overrides (like AI registration pointers `window.__registeredTools`) to bypass compiler warnings. +* **[helpers.ts](helpers.ts)**: Unified routing utilities: + * `blockTracking()`: Intercepts and halts metrics and analytical HTTP queries during spec executions. + * `setupGedcomRoute()`: Re-routes standard genealogy payload network paths directly to load standard local datasets on-the-fly (`src/datasource/testdata/test.ged`). +* **[tsconfig.json](tsconfig.json)**: Typecheck preferences custom to the Playwright runner environment to avoid compilation type collisions. +* **`[spec_name]-snapshots/`**: Directory structure containing expected baseline references and image comparison files. + +--- + +## Running the Tests + +Automated scripts to run and update tests are integrated into standard workspace npm configurations: + +```bash +# Run standard functional E2E tests (fast verification) +npm run test:e2e + +# Run screenshot visual verification tests +npm run test:visual + +# Update screenshot baselines when visual changes are accepted +npm run test:visual:update +```