MSW + client-js Fixtures: Primary Testing Strategy

Core Principle

Drive the real transport, mock the network.

Tests in packages/playground and packages/playground-ui MUST be written as Vitest tests that exercise the real @mastra/client-js SDK, the real React Query cache, and the real component/hook code paths. The only seam we mock is the network boundary, via MSW.

This catches contract drift between the playground and @mastra/client-js at typecheck time and at test time — something vi.mock('@/hooks/...') style tests cannot do.

Priority Order

When you write or refactor a test for these packages, choose in this order:

1. MSW + typed client-js fixtures (THIS SKILL) — for hooks, pages, routes, data-fetching, gating, redirect logic, query/mutation flows, error paths.
2. Playwright E2E (e2e-tests-studio skill) — only for genuine cross-page user journeys, real browser concerns (focus/keyboard/viewport), or anything that requires a real running Mastra server.
3. Pure unit tests — only for self-contained utilities/services with no network, no React Query, no router involvement.

If the same behavior can be covered by both #1 and #2, prefer #1. MSW tests are faster, deterministic, run in CI without browsers, and assert the real wire contract.

What NOT to do

• ❌ vi.mock('@/domains/.../hooks/use-agents') — mocking our own hooks hides cache, gating and transport bugs.
• ❌ Implementation-mirror tests — do not duplicate source class strings, branch logic, generated shapes, or calculations without asserting a real behavior or regression.
• ❌ Class-name-only visual tests — expect(node.className).toContain(...) usually just tests that the implementation string exists. Prefer no test over a className duplication test; use computed style, user-visible behavior, or a browser/Storybook check unless the class string itself is the public API.
• ❌ Inline TypeScript types in tests (type AgentLite = { id: string }) — these drift silently from the real SDK.
• ❌ as any / as unknown as ListAgentsResponse on fixture data, MSW responses, request payloads, hook inputs, or component event inputs.
• ❌ Returning bespoke shapes from MSW handlers that don't match the real @mastra/client-js response. If a field is optional, include it as optional in the fixture, don't omit the type.

What TO do

• ✅ Put fixtures in a __tests__/fixtures/ folder next to the test file.
• ✅ Type every fixture with a response type re-exported from @mastra/client-js (e.g. ListStoredAgentsResponse, GetAgentResponse, BuilderSettingsResponse, GetToolResponse, GetWorkflowResponse, ListStoredSkillsResponse).
• ✅ Use direct imports and inferred types from real SDK, hook, component, DOM, or Testing Library APIs for MSW payloads, request payloads, hook inputs, and component events.
• ✅ Register MSW handlers per test with server.use(...) so handlers reset between tests via the global afterEach.
• ✅ Render through MastraReactProvider + QueryClientProvider + MemoryRouter so the real client SDK is the transport.
• ✅ Use vi.fn() wrappers inside MSW handlers to assert which endpoints were hit (great for testing enabled: ... gating without mocking hooks).

Standard Test Skeleton

// @vitest-environment jsdom
import { MastraReactProvider } from '@mastra/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { cleanup, render, screen } from '@testing-library/react';
import { http, HttpResponse } from 'msw';
import { MemoryRouter } from 'react-router';
import { afterEach, describe, expect, it } from 'vitest';

import { server } from '@/test/msw-server';
import { Subject } from '../subject';
import { happyPathResponse } from './fixtures/subject';

const BASE_URL = 'http://localhost:4111';

const renderSubject = () => {
  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
  return render(
    <MastraReactProvider baseUrl={BASE_URL}>
      <QueryClientProvider client={queryClient}>
        <MemoryRouter>
          <Subject />
        </MemoryRouter>
      </QueryClientProvider>
    </MastraReactProvider>,
  );
};

afterEach(() => cleanup());

describe('Subject', () => {
  it('renders the happy path', async () => {
    server.use(http.get(`${BASE_URL}/api/agents`, () => HttpResponse.json(happyPathResponse)));

    renderSubject();

    expect(await screen.findByText('Expected behavior')).not.toBeNull();
  });
});

Standard Fixture File

// packages/playground/src/.../__tests__/fixtures/subject.ts
import type { ListStoredAgentsResponse } from '@mastra/client-js';

export const emptyStoredAgents: ListStoredAgentsResponse = {
  agents: [],
  total: 0,
  page: 1,
  perPage: 50,
  hasMore: false,
};

export const oneDraftAgent: ListStoredAgentsResponse = {
  ...emptyStoredAgents,
  agents: [
    {
      id: 'agent-1',
      name: 'Draft Agent',
      instructions: '',
      model: { provider: 'openai', name: 'gpt-4o-mini' },
      status: 'draft',
      // ...other required fields from StoredAgentResponse
    },
  ],
  total: 1,
};

If a required field on the SDK response type is missing from your fixture, that's a real test failure — fix the fixture, never as any it. The same applies to hook inputs, component events, and request payloads: type the helper at the real boundary instead of casting the test into compiling.

Existing Infrastructure to Reuse

• packages/playground/src/test/msw-server.ts — exports server. The global vitest.setup.ts calls server.listen({ onUnhandledRequest: 'error' }), server.resetHandlers() after each test, and server.close() at the end. This means unhandled requests fail tests loudly — that's the contract.
• packages/playground/vitest.setup.ts — already wires MSW lifecycle, jsdom polyfills (matchMedia, Element.prototype.scrollTo), so test files just add their own server.use(...) per case.

Recipes

Test loading state without mocking hooks

Defer the MSW handler's resolution with a promise gate:

const gate = (() => {
  let resolve: () => void = () => {};
  const promise = new Promise<void>(r => {
    resolve = r;
  });
  return { promise, resolve };
})();

server.use(
  http.get(`${BASE_URL}/api/stored/agents`, async () => {
    await gate.promise;
    return HttpResponse.json(emptyStoredAgents);
  }),
);

renderSubject();
expect(screen.getByTestId('spinner')).not.toBeNull();

gate.resolve();
await waitFor(() => expect(screen.queryByTestId('spinner')).toBeNull());

Assert that a query is gated (enabled: false)

Wrap the handler in a vi.fn and assert it was never called:

const onAgents = vi.fn<() => void>();
server.use(
  http.get(`${BASE_URL}/api/agents`, () => {
    onAgents();
    return HttpResponse.json(emptyAgents);
  }),
);

renderSubject(); // user has no write access → hook should not fire

await new Promise(resolve => setTimeout(resolve, 50));
expect(onAgents).not.toHaveBeenCalled();

Assert per-feature-flag gating

Use a single MSW handler per endpoint and one vi.fn per endpoint, then toggle the builder-settings response to flip features on/off and assert which handlers were hit.

Vary response by query string

Read request.url inside the handler:

server.use(
  http.get(`${BASE_URL}/api/stored/agents`, ({ request }) => {
    const status = new URL(request.url).searchParams.get('status');
    return HttpResponse.json(status === 'draft' ? oneDraftAgent : emptyStoredAgents);
  }),
);

Thin component seams that ARE acceptable to mock

You may replace these with very thin stubs:

• A heavy child component that has its OWN dedicated test (e.g. mock AgentBuilderStarter to <div data-testid="agent-builder-starter" />).
• react-router's Navigate so you can assert the redirect target instead of letting it actually navigate.
• Button / Spinner style atoms from @mastra/playground-ui only when the real component requires more global context than the test needs.

Never mock our own data hooks, services, or auth gating logic — drive those through their real implementations against MSW.

Verification Checklist

Before considering a test done:

• All fixtures import a response type from @mastra/client-js; MSW payloads, request payloads, hook inputs, and component events use direct imports or inferred production boundary types; no bespoke test-only shapes and no as any / as unknown as casts.
• No vi.mock of @/domains/.../hooks/*, @/domains/.../services/*, @mastra/client-js, or @mastra/react.
• pnpm --filter ./packages/playground typecheck passes — proves fixtures conform to the live SDK shape.
• The new test runs in isolation AND as part of the package suite without onUnhandledRequest: 'error' failures.
• Coverage for the file under test is at the target level (usually 100% for hooks/pages, since MSW makes every branch reachable).

When to Reach for Playwright Instead

Reach for e2e-tests-studio only when at least one is true:

• The behavior spans multiple pages with real navigation/history.
• The behavior requires a real Mastra server (streaming, workflow execution, real model providers).
• The behavior is fundamentally a browser concern (drag-drop, focus traps, viewport, file uploads).

Everything else — fetching, caching, redirects, gating, optimistic updates, error states, empty states, pagination, search params — belongs in this skill.