Create comprehensive UI and API contracts for E2E testing and integration

[Copilot]

Overview

This PR implements the A2 Contracts Author task, creating comprehensive contracts for the Deepline Multi-Agent Data Scientist system without modifying any existing UI code. The contracts provide a single source of truth for UI test automation and API integration.

What's Changed

1. UI Test IDs Contract (contracts/ui-test-ids.json)

Created a JSON Schema-based contract documenting all UI screens and critical elements with designated data-testid attributes:

• 6 screens enumerated: Header, ConsolePanel, DatasetsPanel, WorkflowsPanel, ProcessesPanel, App
• 47 UI elements documented with id, description, selector, and required status
• Enables reliable E2E testing with Playwright, Cypress, or similar tools

{
  "screens": {
    "ConsolePanel": {
      "elements": [
        {
          "id": "console-prompt",
          "description": "Console input field for natural language prompts",
          "selector": "[data-testid='console-prompt']",
          "required": true
        }
      ]
    }
  }
}

2. API Schema Contract (contracts/api-schema.yaml)

Created an OpenAPI 3.0.3 specification documenting all REST API endpoints across the microservices architecture:

• 27 endpoints documented across 4 microservices (Orchestrator, EDA, Refinery, ML)
• 20+ request/response schemas with complete type definitions
• Enables API client generation, validation, and integration testing

Key endpoints covered:

• Master Orchestrator: /workflows/start, /datasets/upload, /runs/{run_id}/status
• EDA Agent: /load_data, /basic_info, /statistical_summary, /create_visualization
• Refinery Agent: /execute with data quality and feature engineering actions
• ML Agent: /class_imbalance, /baseline_sanity, /experiment_tracking

3. Selector Adoption Report (reports/selector-adoption.md)

Created a detailed implementation roadmap showing exactly where to add data-testid attributes:

• 45 TODO comments with code examples for each component
• Complete before/after examples for all 6 UI components
• No actual code modifications (contract-only as required)

Example:

// TODO: Add data-testid to console prompt input
<input
  className="console-prompt"
  placeholder="Ask Deepline to analyze your data..."
  data-testid="console-prompt"
/>

4. Contract Validation Script (scripts/validate-contracts.js)

Created a CI-friendly Node.js validation script that ensures contract integrity:

• 10 validation checks including JSON/YAML syntax, structure validation, duplicate detection
• Clear exit codes: 0 (success), 1 (failure)
• Color-coded terminal output for easy debugging
• Ready for CI/CD integration

$ node scripts/validate-contracts.js
✅ All contract validations PASSED
Passed: 10, Failed: 0, Warnings: 0

5. Comprehensive Documentation (contracts/README.md)

Created detailed documentation with usage examples for all stakeholders:

• Usage guides for frontend developers, QA engineers, and API consumers
• CI/CD integration examples with GitHub Actions
• Versioning guidelines for maintaining contracts
• API client generation examples using OpenAPI tools

Key Features

✅ Contract-only approach - No UI modifications as required
✅ All deliverables provided - ui-test-ids.json, api-schema.yaml, selector-adoption.md, validation script
✅ Validation passing - All 10 checks pass successfully
✅ Well-documented - Comprehensive README with examples
✅ CI-ready - Validation script ready for pipeline integration

Validation Results

============================================================
Validation Summary
============================================================
Passed:   10
Failed:   0
Warnings: 0

✅ All contract validations PASSED

Integration Examples

For QA Engineers (E2E Testing)

// Playwright example using the contract
await page.getByTestId('console-prompt').fill('load iris dataset');
await page.getByTestId('console-submit').click();
await expect(page.getByTestId('workflow-status')).toContainText('COMPLETED');

For Backend Developers (API Clients)

# Generate TypeScript client from OpenAPI schema
openapi-generator-cli generate \
  -i contracts/api-schema.yaml \
  -g typescript-axios \
  -o client/typescript

For CI/CD Integration

# .github/workflows/validate-contracts.yml
name: Validate Contracts
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: node scripts/validate-contracts.js

Next Steps

1. Frontend Team: Implement data-testid attributes following reports/selector-adoption.md
2. QA Team: Create E2E tests using the ui-test-ids.json contract
3. Backend Team: Validate API implementations match api-schema.yaml
4. DevOps Team: Integrate validation script into CI/CD pipeline

Files Added

• contracts/ui-test-ids.json (10 KB)
• contracts/api-schema.yaml (25 KB)
• contracts/README.md (7 KB)
• reports/selector-adoption.md (17 KB)
• scripts/validate-contracts.js (10 KB)

Total: 69 KB of contract documentation

Testing

The validation script has been tested and passes all checks:

cd /path/to/repo
node scripts/validate-contracts.js
# Exit code: 0 (success)

Original prompt

You are A2 Contracts Author.

Tasks:

1. From purpose-map + surface.json, enumerate screens and critical elements.
2. Create contracts/ui-test-ids.json with per-screen arrays of data-testids.
3. Discover API routes/types; create contracts/api-schema.(yaml|ts) using OpenAPI or Zod with request/response types.

Rules:

• Do not modify UI yet. Only author contracts.
• Put TODO comments in /reports/selector-adoption.md listing components that must add data-testid attributes.

Deliverables:

• contracts/ui-test-ids.json
• contracts/api-schema.(yaml|ts)
• /reports/selector-adoption.md
• CI-friendly validation script at scripts/validate-contracts.(ts|js)

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.