Testing

Algolia InstantSearch Testing: Mock Hits, Filters, and Pagination

HelpMeTest

HelpMeTest

— 5 min read
Algolia InstantSearch Testing: Mock Hits, Filters, and Pagination

Algolia InstantSearch powers search experiences for thousands of production apps, but testing it reliably is harder than it looks. The library manages complex state — queries, filters, pagination, refinements — and testing against the live Algolia API in CI introduces latency, cost, and flakiness. This guide shows you how to test InstantSearch apps properly with mocks, stubs, and the right assertions.

Understanding InstantSearch's Architecture

Before writing tests, understand what you're testing. InstantSearch works through a search client that communicates with Algolia's API, and a set of React (or vanilla JS) widgets that bind to a shared search state. Your tests need to control the search client while verifying the widget behavior.

The key insight: Algolia exposes a searchClient prop that accepts anything implementing the search() method. This is your hook for injecting mocks.

Setting Up a Mock Search Client

Create a mock client that returns controlled responses:

// test-utils/algolia-mock.js
export function createMockSearchClient(mockResults = {}) {
  return {
    search: jest.fn(([{ indexName, params }]) => {
      const results = mockResults[indexName] || {
        hits: [],
        nbHits: 0,
        nbPages: 0,
        page: 0,
        hitsPerPage: 20,
        facets: {},
      };
      return Promise.resolve({
        results: [results],
      });
    }),
  };
}

Use it in your tests:

import { render, screen, waitFor } from '@testing-library/react';
import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';
import { createMockSearchClient } from '../test-utils/algolia-mock';

const mockResults = {
  'products': {
    hits: [
      { objectID: '1', name: 'Running Shoes', price: 129.99, _highlightResult: {} },
      { objectID: '2', name: 'Trail Boots', price: 189.99, _highlightResult: {} },
    ],
    nbHits: 2,
    nbPages: 1,
    page: 0,
    hitsPerPage: 20,
    facets: { brand: { Nike: 1, Salomon: 1 } },
  },
};

test('renders search results', async () => {
  const searchClient = createMockSearchClient(mockResults);

  render(
    <InstantSearch searchClient={searchClient} indexName="products">
      <SearchBox />
      <Hits hitComponent={({ hit }) => <div data-testid="hit">{hit.name}</div>} />
    </InstantSearch>
  );

  await waitFor(() => {
    expect(screen.getAllByTestId('hit')).toHaveLength(2);
  });

  expect(screen.getByText('Running Shoes')).toBeInTheDocument();
  expect(screen.getByText('Trail Boots')).toBeInTheDocument();
});

Testing Search Query Behavior

Verify that user input triggers the correct searches:

import userEvent from '@testing-library/user-event';

test('sends correct query on search input', async () => {
  const searchClient = createMockSearchClient(mockResults);
  const user = userEvent.setup();

  render(
    <InstantSearch searchClient={searchClient} indexName="products">
      <SearchBox />
      <Hits hitComponent={({ hit }) => <div>{hit.name}</div>} />
    </InstantSearch>
  );

  const input = screen.getByRole('searchbox');
  await user.type(input, 'running');

  await waitFor(() => {
    const calls = searchClient.search.mock.calls;
    const lastCall = calls[calls.length - 1][0];
    expect(lastCall[0].params.query).toBe('running');
  });
});

Testing RefinementList Filters

Filter state is where many bugs hide. Test that filter selection updates the search correctly:

import { RefinementList } from 'react-instantsearch';

const mockResultsWithFacets = {
  'products': {
    ...mockResults.products,
    facets: {
      brand: { Nike: 5, Adidas: 3, Salomon: 2 },
    },
    renderingContent: {
      facetOrdering: {
        facets: { order: ['brand'] },
        values: { brand: { sortRemainingBy: 'count' } },
      },
    },
  },
};

test('refinement list renders facet values', async () => {
  const searchClient = createMockSearchClient(mockResultsWithFacets);

  render(
    <InstantSearch searchClient={searchClient} indexName="products">
      <RefinementList attribute="brand" />
    </InstantSearch>
  );

  await waitFor(() => {
    expect(screen.getByText('Nike')).toBeInTheDocument();
    expect(screen.getByText('Adidas')).toBeInTheDocument();
  });
});

test('clicking a refinement adds it to the query', async () => {
  const searchClient = createMockSearchClient(mockResultsWithFacets);
  const user = userEvent.setup();

  render(
    <InstantSearch searchClient={searchClient} indexName="products">
      <RefinementList attribute="brand" />
    </InstantSearch>
  );

  await waitFor(() => screen.getByText('Nike'));
  await user.click(screen.getByText('Nike'));

  await waitFor(() => {
    const calls = searchClient.search.mock.calls;
    const lastCall = calls[calls.length - 1][0];
    const facetFilters = lastCall[0].params.facetFilters;
    expect(facetFilters).toContainEqual(['brand:Nike']);
  });
});

Testing Pagination

Pagination bugs are common and annoying to debug in production. Test page transitions explicitly:

import { Pagination } from 'react-instantsearch';

const multiPageResults = {
  'products': {
    hits: Array.from({ length: 20 }, (_, i) => ({
      objectID: String(i + 1),
      name: `Product ${i + 1}`,
      _highlightResult: {},
    })),
    nbHits: 60,
    nbPages: 3,
    page: 0,
    hitsPerPage: 20,
  },
};

test('pagination shows correct page count', async () => {
  const searchClient = createMockSearchClient(multiPageResults);

  render(
    <InstantSearch searchClient={searchClient} indexName="products">
      <Pagination />
    </InstantSearch>
  );

  await waitFor(() => {
    // Pagination renders page buttons 1, 2, 3
    expect(screen.getByRole('link', { name: '2' })).toBeInTheDocument();
    expect(screen.getByRole('link', { name: '3' })).toBeInTheDocument();
  });
});

test('clicking page 2 sends correct page parameter', async () => {
  const searchClient = createMockSearchClient(multiPageResults);
  const user = userEvent.setup();

  render(
    <InstantSearch searchClient={searchClient} indexName="products">
      <Pagination />
    </InstantSearch>
  );

  await waitFor(() => screen.getByRole('link', { name: '2' }));
  await user.click(screen.getByRole('link', { name: '2' }));

  await waitFor(() => {
    const calls = searchClient.search.mock.calls;
    const lastCall = calls[calls.length - 1][0];
    expect(lastCall[0].params.page).toBe(1); // 0-indexed
  });
});

Testing Highlight Results

Algolia returns _highlightResult for matching terms. Test that your hit component renders it correctly:

import { Highlight } from 'react-instantsearch';

const hitWithHighlight = {
  objectID: '1',
  name: 'Running Shoes',
  _highlightResult: {
    name: {
      value: '<mark>Running</mark> Shoes',
      matchLevel: 'full',
      fullyHighlighted: false,
      matchedWords: ['running'],
    },
  },
};

function ProductHit({ hit }) {
  return (
    <div>
      <Highlight hit={hit} attribute="name" />
    </div>
  );
}

test('renders highlighted search terms', async () => {
  const searchClient = createMockSearchClient({
    products: {
      hits: [hitWithHighlight],
      nbHits: 1,
      nbPages: 1,
      page: 0,
      hitsPerPage: 20,
    },
  });

  render(
    <InstantSearch searchClient={searchClient} indexName="products">
      <Hits hitComponent={ProductHit} />
    </InstantSearch>
  );

  await waitFor(() => {
    const mark = document.querySelector('mark');
    expect(mark).toBeInTheDocument();
    expect(mark.textContent).toBe('Running');
  });
});

Testing useInstantSearch Hook

For custom implementations using the hook API:

import { useInstantSearch } from 'react-instantsearch';

function SearchStatus() {
  const { results, status } = useInstantSearch();
  if (status === 'loading') return <div>Loading...</div>;
  return <div>Found {results.nbHits} results</div>;
}

test('shows loading state then results count', async () => {
  let resolveSearch;
  const slowSearchClient = {
    search: jest.fn(() => new Promise(resolve => { resolveSearch = resolve; })),
  };

  render(
    <InstantSearch searchClient={slowSearchClient} indexName="products">
      <SearchStatus />
    </InstantSearch>
  );

  expect(screen.getByText('Loading...')).toBeInTheDocument();

  resolveSearch({ results: [{ hits: [], nbHits: 42, nbPages: 3, page: 0, hitsPerPage: 20 }] });

  await waitFor(() => {
    expect(screen.getByText('Found 42 results')).toBeInTheDocument();
  });
});

Testing with MSW for Integration Tests

For integration tests where you want to test real HTTP behavior:

import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';
import algoliasearch from 'algoliasearch';

const server = setupServer(
  http.post('https://*.algolia.net/1/indexes/*/queries', () => {
    return HttpResponse.json({
      results: [{
        hits: [{ objectID: '1', name: 'Widget', _highlightResult: {} }],
        nbHits: 1,
        nbPages: 1,
        page: 0,
        hitsPerPage: 20,
      }],
    });
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test('real algolia client returns mocked data via MSW', async () => {
  const client = algoliasearch('APP_ID', 'SEARCH_KEY');

  render(
    <InstantSearch searchClient={client} indexName="products">
      <Hits hitComponent={({ hit }) => <div data-testid="hit">{hit.name}</div>} />
    </InstantSearch>
  );

  await waitFor(() => {
    expect(screen.getByTestId('hit')).toHaveTextContent('Widget');
  });
});

E2E Testing with HelpMeTest

For full end-to-end search testing — covering real browser behavior, network requests, and UI interactions — HelpMeTest lets you write tests in plain English without code:

Open browser to https://your-app.com/search
Type "running shoes" in the search input
Verify at least 3 results appear
Click the "Nike" brand filter
Verify results only show Nike products
Click page 2 in pagination
Verify the URL contains page=2

HelpMeTest runs these tests in real browsers with 24/7 monitoring, so you catch regressions in your Algolia integration before users do.

Common Pitfalls

Don't test Algolia's ranking algorithm. Your job is to test that your app sends the right query parameters and renders the response correctly — not that Algolia returns the best results.

Mock at the client level, not the widget level. Mocking individual widgets breaks the integration between them. Always mock the searchClient.

Account for debouncing. InstantSearch debounces queries. Use waitFor with appropriate timeouts rather than asserting on intermediate states.

Test the empty state. Always verify what renders when hits is an empty array. Many UIs break silently.

Summary

Testing Algolia InstantSearch effectively means:

  1. Mocking the searchClient to control search responses
  2. Verifying that user interactions (typing, filtering, paginating) send correct query parameters
  3. Asserting that hit rendering, highlighting, and facet UI work correctly
  4. Using MSW for integration-level HTTP testing
  5. Using HelpMeTest for E2E monitoring in production environments

Keep unit tests fast with mock clients, and use E2E tests to catch the integration issues that mocks miss.

Read more