Vue Testing Patterns (@data-client/vue)

Composable Testing with renderDataCompose()

import { renderDataCompose } from '@data-client/vue/test';
import { reactive, computed } from 'vue';

it('useQuery() should return cached data', async () => {
  const { result } = await renderDataCompose(
    () => useQuery(Article, { id: 5 }),
    {
      initialFixtures: [
        {
          endpoint: ArticleResource.get,
          args: [{ id: 5 }],
          response: { id: 5, title: 'hi ho', content: 'whatever' },
        },
      ],
    },
  );
  expect(result.value).toEqual(Article.fromJS({ id: 5, title: 'hi ho', content: 'whatever' }));
});

Options:

initialFixtures - Pre-populate store state (static fixtures)
resolverFixtures - Intercept requests with dynamic responses
props - Reactive props object (use reactive())
managers, initialState, gcPolicy - Custom configuration

Return values (renderDataCompose() is async; always await it):

result - Whatever the composable returned: useQuery/useCache give a ComputedRef (.value is undefined when not in the store); useSuspense gives a Promise of one, so await result once, then read .value, which stays reactive
controller - Controller instance for manual actions
wrapper - Vue Test Utils wrapper
cleanup() - Cleanup function (always call in afterEach/after test)
allSettled() - Wait for all in-flight fetches (including ones a prop change just started) and the re-render
waitForNextUpdate() - Deprecated: it gives up silently after 1 second, so a test can pass while still suspended, and can hang under fake timers. Use await result for a Promise result, and await allSettled() after changing props or calling the controller

Component Testing with mountDataClient()

import { mountDataClient } from '@data-client/vue/test';
import { defineComponent, h, reactive } from 'vue';

it('should render article component', async () => {
  const ArticleComp = defineComponent({
    props: { id: Number },
    async setup(props) {
      const article = await useSuspense(ArticleResource.get, () => ({ id: props.id }));
      return () => h('div', [
        h('h3', article.value.title),
        h('p', article.value.content),
      ]);
    },
  });

  const props = reactive({ id: 5 });
  const { wrapper, cleanup } = mountDataClient(ArticleComp, {
    props,
    initialFixtures: [
      {
        endpoint: ArticleResource.get,
        args: [{ id: 5 }],
        response: { id: 5, title: 'hi ho', content: 'whatever' },
      },
    ],
  });

  await flushUntil(() => wrapper.find('h3').exists());
  expect(wrapper.find('h3').text()).toBe('hi ho');
  cleanup();
});

Features:

Suspense is automatically integrated (shows fallback while loading)
Use data-testid="suspense-fallback" to test loading state
Synchronous; returns wrapper, controller, app, cleanup() and allSettled()

Async Waiting Patterns

flushUntil(predicate) (for component tests): copy the helper from waiting for renders; it throws if the condition never holds.

await flushUntil(() => wrapper.find('h3').exists());
await flushUntil(() => wrapper.find('h3').text() === 'Expected Title');

Reactive Props Testing

Pattern 1: Testing prop changes:

const props = reactive({ id: 1 });
const { result } = await renderDataCompose(
  () => useQuery(Article, computed(() => ({ id: props.id }))),
  {
    initialFixtures: [
      { endpoint: ArticleResource.get, args: [{ id: 1 }], response: { id: 1, title: 'First' } },
      { endpoint: ArticleResource.get, args: [{ id: 2 }], response: { id: 2, title: 'Second' } },
    ],
  },
);

expect(result.value?.title).toBe('First');

// Change props - result updates after a tick
props.id = 2;
await nextTick();
expect(result.value?.title).toBe('Second');

Pattern 2: Conditional arguments (null handling):

const props = reactive({ id: 1 as number | null });
const { result } = await renderDataCompose(
  (props: { id: number | null }) => 
    useSuspense(ArticleResource.get, computed(() => props.id !== null ? { id: props.id } : null)),
  { props },
);

const articleRef = await result;
expect(articleRef.value).toBeDefined();

// Set to null - becomes undefined
props.id = null;
await nextTick();
expect(articleRef.value).toBeUndefined();

Fixtures and Interceptors

Static Fixture:

{
  endpoint: ArticleResource.get,
  args: [{ id: 5 }],
  response: { id: 5, title: 'hi ho', content: 'whatever' },
}

Dynamic Interceptor:

resolverFixtures: [
  {
    endpoint: ArticleResource.get,
    response: ({ id }) => ({ id, title: `Article ${id}`, content: 'dynamic' }),
  },
]

Error Fixture:

{
  endpoint: ArticleResource.get,
  args: [{ id: 5 }],
  response: new Error('Not found'),
  error: true,
}

Testing Mutations

it('should update collection when pushed', async () => {
  const { result, controller } = await renderDataCompose(
    () => useQuery(ArticleResource.getList.schema, {}),
    {
      initialFixtures: [
        { endpoint: ArticleResource.getList, args: [], response: [{ id: 1, title: 'First' }] },
      ],
      resolverFixtures: [
        { endpoint: ArticleResource.getList.push, response: (body) => body },
      ],
    },
  );

  expect(result.value?.length).toBe(1);

  await controller.fetch(ArticleResource.getList.push, {
    id: 2,
    title: 'Second',
    content: 'new',
  });
  await nextTick();

  expect(result.value?.length).toBe(2);
});

Testing with Controller

setResponse() for instant updates:

const { result, controller } = await renderDataCompose(() => useSuspense(...));
const dataRef = await result;

expect(dataRef.value.title).toBe('Original');

controller.setResponse(
  ArticleResource.get,
  { id: 5 },
  { id: 5, title: 'Updated', content: 'new content' }
);

await nextTick();
expect(dataRef.value.title).toBe('Updated'); // Reactive!

Testing with nock (HTTP Mocking)

Use nock when a test must exercise the real fetch path — verifying URL construction, headers, request bodies, retries, or anything in your RestEndpoint/Resource networking layer. For pure store/state behavior, prefer initialFixtures/resolverFixtures (lighter and faster).

Minimal shape:

import nock from 'nock';

beforeAll(() => {
  nock(/.*/)
    .persist()
    .defaultReplyHeaders({ 'Access-Control-Allow-Origin': '*', 'Content-Type': 'application/json' })
    .options(/.*/).reply(200)            // CORS preflight (required in JSDOM)
    .get('/article/5').reply(200, { id: 5, title: 'hi ho' });
});

afterAll(() => nock.cleanAll());

For dynamic server state, mutating-closure replies, request spying with jest.fn(), error responses, and mixing nock with fixtures, see references/nock-http-mocking.md.

Testing Polling and Subscriptions

For composables with pollFrequency, useLive, or useSubscription, use fake timers so polls fire deterministically. Core flow:

jest.useFakeTimers() before mount/render (so the interval is created under fake timers).
Render, then jest.advanceTimersByTime(frequency) to drive the initial fetch.
Mutate the response (e.g. responseMock.mockReturnValue(...)), advance time again, await allSettled() and await nextTick().
Restore real timers in afterEach: jest.useRealTimers().

Quick example:

jest.useFakeTimers();
const responseMock = jest.fn(() => payload);

const { result, allSettled, cleanup } = await renderDataCompose(
  () => useSuspense(PollingArticleResource.get, { id: payload.id }),
  { resolverFixtures: [{ endpoint: PollingArticleResource.get, response: responseMock }] },
);

jest.advanceTimersByTime(frequency);
await allSettled();
const articleRef = await result;

responseMock.mockReturnValue({ ...payload, title: 'updated' });
jest.advanceTimersByTime(frequency);
await allSettled();
await nextTick();

expect(articleRef!.value.title).toBe('updated');
jest.useRealTimers();
cleanup();

For unsubscribe patterns, component-level polling tests, fake-timer-safe flushUntil, polling via nock, and common pitfalls, see references/polling-subscriptions.md.

Best Practices

Always call cleanup() - Prevents memory leaks and test pollution
Use reactive() for props - Enables testing prop changes
Use flushUntil() in component tests - More reliable than fixed delays
Remember nextTick() - After mutations/setResponse to allow Vue reactivity to propagate
Use initialFixtures for initial state - Pre-populate the store
Use resolverFixtures for dynamic responses - Intercept requests with functions
Test both empty and populated states - Verify undefined behavior
Pass prop-derived args as getters or computed() - Async setup runs once, so useSuspense(Resource.get, () => ({ id: props.id })) follows prop changes; a plain { id: props.id } is read once

References

For detailed API documentation, see the references directory:

Fixtures - Fixture format reference
mockInitialState - Create initial state for DataClientPlugin
unit-testing-components - mountDataClient() guide, setup and options
unit-testing-composables - renderDataCompose() guide
nock-http-mocking - Full nock setup, dynamic server state, request spying, errors, pitfalls
polling-subscriptions - Fake-timer patterns for useLive/useSubscription/pollFrequency, unsubscribe verification, polling via nock

Common Patterns

Empty state test:

const { result } = await renderDataCompose(() => useQuery(Article, { id: 5 }));
expect(result.value).toBe(undefined);

Testing nested collections:

const userTodos = new Collection(new schema.Array(Todo), {
  argsKey: ({ userId }) => ({ userId }),
});

const { result } = await renderDataCompose(
  () => useQuery(userTodos, { userId: '1' }),
  { initialFixtures: [/* ... */] },
);

expect(result.value?.length).toBe(2);
expect(result.value?.[0]).toBeInstanceOf(Todo);

data-client-vue-testing