# Mastra

Test your Mastra agents with deterministic LLM responses and AG-UI event streams. aimock integrates natively with CopilotKit's Mastra support.

## Quick Start

Mastra agents support multiple LLM providers through its model configuration. For OpenAI-compatible models, set the base URL to point at aimock. The simplest approach is setting the `OPENAI_BASE_URL` environment variable.

Point your agent at aimock typescript

    import { Agent } from "@mastra/core/agent";

    const agent = new Agent({
      name: "my-agent",
      instructions: "You are a helpful assistant",
      model: {
        provider: "OPEN_AI",
        name: "gpt-4o",
        toolChoice: "auto",
      },
    });

    // Set OPENAI_BASE_URL=http://localhost:4010/v1 to redirect to aimock
    // All completions will be served from aimock fixtures

## With Vitest Plugin

The `useAimock` plugin starts and stops the aimock server automatically around your test suite. No manual setup or teardown required.

mastra-agent.test.ts typescript

    import { describe, it, expect } from "vitest";
    import { useAimock } from "@copilotkit/aimock/vitest";
    import { Agent } from "@mastra/core/agent";

    const mock = useAimock({ fixtures: "./fixtures" });

    describe("Mastra agent", () => {
      it("handles a travel planning request", async () => {
        process.env.OPENAI_BASE_URL = mock().url + "/v1";

        const agent = new Agent({
          name: "travel-planner",
          instructions: "You are a travel planning assistant",
          model: { provider: "OPEN_AI", name: "gpt-4o" },
        });
        const result = await agent.generate("plan a trip to Tokyo");
        expect(result.text).toContain("Tokyo");
      });
    });

## Tool Call Workflows

Mastra agents use tools extensively for travel planning, API calls, and multi-step workflows. Define tool call fixtures to test these interactions deterministically.

fixtures/mastra-tools.json json

    {
      "fixtures": [
        {
          "match": { "userMessage": "plan a trip", "sequenceIndex": 0 },
          "response": {
            "toolCalls": [
              {
                "name": "search_flights",
                "arguments": { "origin": "SFO", "destination": "NRT", "date": "2025-03-15" }
              }
            ]
          }
        },
        {
          "match": { "userMessage": "plan a trip", "sequenceIndex": 1 },
          "response": {
            "toolCalls": [
              {
                "name": "search_hotels",
                "arguments": { "city": "Tokyo", "checkIn": "2025-03-15", "checkOut": "2025-03-22" }
              }
            ]
          }
        },
        {
          "match": { "userMessage": "plan a trip", "sequenceIndex": 2 },
          "response": {
            "content": "I found a great itinerary for your Tokyo trip!\n\n**Flight:** SFO → NRT on March 15, departing 11:30 AM (United UA837) — $890 round trip\n\n**Hotel:** Hotel Gracery Shinjuku, March 15–22 — $185/night\n\nWould you like me to book these, or would you prefer different options?"
          }
        }
      ]
    }

Each fixture fires once in sequence using `sequenceIndex`. The first call triggers a flight search, the second searches for hotels, and the third returns the combined itinerary. See Fixtures for the full matching syntax.

## AG-UI Frontend Testing

When using Mastra with CopilotKit, the frontend receives AG-UI event streams. Use `AGUIMock` to test the frontend separately from the agent — no running Mastra server required.

Mock the AG-UI layer typescript

    import { LLMock } from "@copilotkit/aimock";
    import { AGUIMock } from "@copilotkit/aimock";

    const llm = new LLMock();
    const agui = new AGUIMock();

    agui.onMessage("hello", "Hi from the agent!");
    agui.onToolCall(/search/, "web_search", '{"q":"test"}', { result: "[]" });

    llm.mount("/agui", agui);
    const url = await llm.start();

    // Point your CopilotKit frontend at url + "/agui"
    // It receives deterministic AG-UI SSE event streams

This lets you develop and test CopilotKit UI components against canned agent responses without running Mastra or any LLM provider. See AGUIMock for the full API.

## CI with GitHub Action

Run your Mastra agent tests in CI with a single step. The aimock GitHub Action starts the server, waits for it to be healthy, and cleans up when the job finishes.

workflow.yml yaml

    steps:
      - uses: actions/checkout@v4
      - uses: CopilotKit/aimock@v1
        with:
          fixtures: ./fixtures
      - run: pnpm test
        env:
          OPENAI_BASE_URL: http://127.0.0.1:4010/v1

See GitHub Action for all available inputs and outputs.