Playground Msw Tests

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.

• ❌ 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.
• ❌ 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).

• ✅ 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.

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 type from @mastra/client-js and have 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.