Data Client Vue Testing

Vue Testing Patterns (@data-client/vue)

Composable Testing with renderDataCompose()

typescriptCopy code
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()

typescriptCopy code
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.

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

Reactive Props Testing

Pattern 1: Testing prop changes:

typescriptCopy code
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):

typescriptCopy code
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:

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

Dynamic Interceptor:

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

Error Fixture:

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

Testing Mutations

typescriptCopy code
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:

typescriptCopy code
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:

typescriptCopy code
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:

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

Quick example:

typescriptCopy code
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:

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

Testing nested collections:

typescriptCopy code
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);