MCP Testing Package

This package provides a test harness for MCP (Model Context Protocol) tools, allowing you to define test scenarios in YAML or JSON format.

Features

• YAML/JSON Test Scenarios: Define tests declaratively
• Import Support: Link external data files to avoid cluttering test files
• Setup/Cleanup: Run setup and cleanup steps
• Assertions: Validate tool responses
• Result Storage: Store tool results for use in later steps
• Dependencies: Define dependencies between test steps

Test Scenario Format

Basic Structure

name: "Interactive object creation test"
description: "Test creating a backlog item interactively"

setup:
  - name: "List milestones"
    tool: "zqk_object_list"
    args:
      kind: "milestone"
    store_result: "milestones"

tests:
  - name: "Create object interactively"
    tool: "zqk_create_object_interactive"
    args:
      kind: "backlog_item"
      title: "Test Item"
    import: "references.yaml"
    import_path: "args"
    expected:
      success: true
      has_field:
        session_id: true

Import Support

Import external data files to keep test scenarios clean:

references.yaml:

milestone_refs:
  - "MIL-001"
  - "MIL-002"
goal_refs:
  - "GOAL-001"

test-scenario.yaml:

tests:
  - name: "Create object with references"
    tool: "zqk_create_object_interactive"
    args:
      kind: "backlog_item"
      title: "Test Item"
    import: "references.yaml"
    import_path: "args"  # Merge into args

Top-Level Imports

Import complete scenario files:

name: "Composite test"
imports:
  - "common-setup.yaml"
  - "common-cleanup.yaml"

tests:
  - name: "My test"
    tool: "zqk_object_list"
    args:
      kind: "backlog_item"

Assertions

Validate tool responses:

tests:
  - name: "Create object"
    tool: "zqk_create_object_interactive"
    args:
      kind: "backlog_item"
    expected:
      success: true
      has_fields:
        - "session_id"
        - "filled_template"
      equals:
        kind: "backlog_item"
      matches:
        session_id: "^interactive-.*"

Result Storage and Dependencies

Store results and use them in later steps:

setup:
  - name: "Get milestone"
    tool: "zqk_object_get"
    args:
      id: "MIL-001"
    store_result: "milestone"

tests:
  - name: "Create item with milestone"
    tool: "zqk_create_object_interactive"
    depends_on:
      - "milestone"
    args:
      kind: "backlog_item"
      milestone_refs:
        - "${milestone.id}"  # Variable interpolation (future)

Usage

package main

import (
    "github.com/zqk-os/zqk/pkg/mcp/testing"
)

func main() {
    loader := testing.NewScenarioLoader("./test-scenarios")
    scenario, err := loader.LoadScenario("my-test.yaml")
    if err != nil {
        log.Fatal(err)
    }

    executor := testing.NewScenarioExecutor(server)
    results, err := executor.RunScenario(scenario)
    if err != nil {
        log.Fatal(err)
    }

    // Process results
}

File Organization

test-scenarios/
├── scenarios/
│   ├── interactive-creation.yaml
│   └── object-query.yaml
├── data/
│   ├── references.yaml
│   ├── large-reference-list.yaml
│   └── test-data.yaml
└── common/
    ├── setup.yaml
    └── cleanup.yaml