QA-MCP-Learning-Lab

Project Overview

QA-MCP-Learning-Lab is a showcase repository for principal-level quality engineering architecture using Model Context Protocol (MCP) tools and Playwright-based UI validation. The project demonstrates how modern QA systems can validate security, business workflows, contract safety, and cross-layer consistency in a single, extensible test harness.

QA Pillars

• Security / Session Integrity
  • Validate authentication, authorization, and protected endpoint behavior.
• Business Workflows
  • Exercise end-to-end business logic for create/read/update/delete flows.
• Contract / Data Safety
  • Enforce request and response schemas with Zod to prevent malformed payloads.
• Cross-Layer Sync
  • Verify that backend behavior and frontend/UI expectations remain aligned.

Architectural View

🏗️ QA & System Architecture Overview

This section outlines how our test suites, core infrastructure, and quality pillars connect to deliver reliable software outputs.

---

🗺️ Architecture Blueprint

Layer	Component Group	Included Elements & Responsibilities
Layer 1	🛠️ Test Harness	MCP Tools • Node Unit Tests • Playwright UI Tests<br>The entry point where all automated tests run.
Layer 2	💻 System Components	Server & Tool Registry • API / Business Logic • Frontend Browser • Zod Schemas<br>The actual application code and infrastructure being tested.
Layer 3	🛡️ QA Pillars	Security & Session Integrity • Contract & Data Safety • Cross-Layer Sync<br>The core criteria ensuring safety, data contract validation, and system sync.
Layer 4	📊 Outputs	QA Reports & Artifacts<br>The final test results, logs, and compliance documentation generated.

---

🔄 How Data Flows

1. Test Execution: The Test Harness (Layer 1) fires automated tests.
2. System Evaluation: These tests hit the System Components (Layer 2) to verify the UI, API, and schemas.
3. Core Validation: The system behaviors are filtered against our strict QA Pillars (Layer 3).
4. Final Delivery: The pipeline outputs clean, client-ready QA Reports (Layer 4) showing exactly what passed or failed.

Directory Structure

• src/tools
  • MCP tool implementations and tool registration logic.
• src/tests
  • Node-based unit tests and Playwright smoke/e2e tests.
• src/utils/schema.ts
  • Shared Zod schemas for request/response contract validation.
• src/playwright
  • Playwright configuration and browser-based test setup.
• src/server.ts
  • Application entry point for local execution and tool exposure.

MCP Tool Registration

MCP tools are implemented under the src/tools area and registered with the server entry point so they can be exposed to clients in a structured, discoverable way. The server acts as the orchestration layer for tool execution and test interaction.

Zod Schemas and Contract Enforcement

Zod schemas provide runtime validation for payload structures and API contracts. They help ensure the system fails fast when requests or responses drift from the expected shape, improving diagnostics and preventing downstream compatibility issues.

Test Portfolio

The project is organized as a showcase test portfolio with 10 milestone tests across four phases.

• Phase 1: Session & Security (2 tests)
  • Authentication/session handling
  • Protected endpoint security
• Phase 2: CRUD & Business Logic (4 tests)
  • Create, read, update, and delete workflow coverage
• Phase 3: Contract & Diagnostics (2 tests)
  • Schema validation and contract-safe behavior
• Phase 4: Cross-Layer UI (2 tests)
  • Frontend/browser-level verification against the same product behavior
  • One test is optional and runs only when a valid BASE_URL is configured

Total showcase tests: 10

Note: this repository does not include a hosted frontend application by default. To enable the optional UI smoke check, set BASE_URL to a running frontend URL such as http://localhost:3000 or your deployed app URL.

CI/CD

The project includes a GitHub Actions workflow at .github/workflows/ci.yml that runs the build and test pipeline automatically.

CI Workflow Expectations

• Install dependencies with npm ci
• Build the TypeScript project with npm run build
• Execute the test harness with npm test
• Publish Playwright report artifacts for inspection

Available npm Scripts

• npm run build
• npm test

Test Reports

Playwright reports are generated into the test-results directory, including an HTML report for browser-based validation.

How to Run

npm ci
npm run build
npm test
npx playwright show-report

Environment Variables

• BASE_URL — Optional frontend URL used by the Playwright frontend smoke test.
• Example: BASE_URL=http://localhost:3000 or BASE_URL=https://demo.realworld.show

If BASE_URL is not set, the optional frontend verification test will be skipped, but the remaining workflow and contract tests will still run.

Test inventory (what runs today)

Primary showcase tests (10):

• src/tests/conduit.phase1.test.ts — 2 tests (Session & Security)
• src/tests/phase2-crud.test.ts — 4 tests (CRUD & Business Logic)
• src/tests/phase3-contract.test.ts — 2 tests (Contract & Diagnostics)
• src/tests/phase4-ui.test.ts — 2 tests (Cross-Layer UI)

Additional tests included in the repository (not part of the primary 10):

• src/tests/playwright.smoke.test.ts — 2 Playwright checks (engine availability + optional frontend smoke check)
• src/tests/run-all-tests.report.test.ts — 1 internal regression/test helper (parses Playwright JSON)

When the harness runs all files in src/tests, these extras will increase the total test count reported (e.g. 13 total in some runs). To restrict reports to the 10 showcase tests, exclude the helper files or adjust the harness filter.

Future Enhancements

• Add custom reporters for phase-by-phase test results and trend tracking
• Integrate with a dashboard for richer QA visibility and historical reporting