Testing

Meilisearch Testing Guide: Index Operations, Search Validation, and Facets

HelpMeTest

HelpMeTest

— 6 min read
Meilisearch Testing Guide: Index Operations, Search Validation, and Facets

Meilisearch has become a popular choice for teams that want fast, typo-tolerant search without the operational overhead of Elasticsearch. Its simple API makes it easy to integrate, but that same simplicity can give false confidence. Bugs in your indexing logic, filter syntax, or facet configuration don't announce themselves — they silently corrupt your search experience. This guide shows you how to test Meilisearch integrations properly.

What to Test in a Meilisearch Integration

A typical Meilisearch integration has three main concerns:

  1. Index management — creating indexes, configuring settings (searchable attributes, filterable attributes, ranking rules)
  2. Document operations — adding, updating, and deleting documents from indexes
  3. Search operations — queries, filters, facets, sort, and pagination

All three need tests. Most teams only test the third.

Mocking the Meilisearch Client

Meilisearch's JavaScript client is easy to mock because operations are async and the API surface is small:

// test-utils/meilisearch-mock.js
export function createMockMeilisearchClient() {
  const indexes = new Map();

  const createIndexObject = (uid) => ({
    addDocuments: jest.fn(async (docs) => {
      if (!indexes.has(uid)) indexes.set(uid, { docs: [], settings: {} });
      indexes.get(uid).docs.push(...docs);
      return { taskUid: 1, status: 'enqueued' };
    }),
    updateDocuments: jest.fn(async (docs) => {
      return { taskUid: 2, status: 'enqueued' };
    }),
    deleteDocument: jest.fn(async (id) => {
      return { taskUid: 3, status: 'enqueued' };
    }),
    deleteAllDocuments: jest.fn(async () => {
      if (indexes.has(uid)) indexes.get(uid).docs = [];
      return { taskUid: 4, status: 'enqueued' };
    }),
    search: jest.fn(async (query, options = {}) => ({
      hits: [],
      estimatedTotalHits: 0,
      query,
      limit: options.limit || 20,
      offset: options.offset || 0,
      processingTimeMs: 1,
      facetDistribution: {},
    })),
    updateSettings: jest.fn(async (settings) => {
      if (!indexes.has(uid)) indexes.set(uid, { docs: [], settings: {} });
      Object.assign(indexes.get(uid).settings, settings);
      return { taskUid: 5, status: 'enqueued' };
    }),
    getSettings: jest.fn(async () => indexes.get(uid)?.settings || {}),
    waitForTask: jest.fn(async (taskUid) => ({ status: 'succeeded', taskUid })),
  });

  return {
    index: jest.fn((uid) => createIndexObject(uid)),
    createIndex: jest.fn(async (uid, options) => {
      indexes.set(uid, { docs: [], settings: {} });
      return { taskUid: 0, status: 'enqueued' };
    }),
    getIndex: jest.fn(async (uid) => {
      if (!indexes.has(uid)) throw new Error(`Index ${uid} not found`);
      return createIndexObject(uid);
    }),
    getIndexes: jest.fn(async () => ({
      results: Array.from(indexes.keys()).map(uid => ({ uid })),
    })),
    _indexes: indexes, // expose for assertions
  };
}

Testing Index Operations

Test that your service creates indexes with the right configuration:

import { createMockMeilisearchClient } from '../test-utils/meilisearch-mock';
import { SearchIndexService } from '../services/search-index';

describe('SearchIndexService', () => {
  let client;
  let service;

  beforeEach(() => {
    client = createMockMeilisearchClient();
    service = new SearchIndexService(client);
  });

  test('creates articles index on initialization', async () => {
    await service.initialize();

    expect(client.createIndex).toHaveBeenCalledWith('articles', {
      primaryKey: 'id',
    });
  });

  test('configures searchable attributes after index creation', async () => {
    await service.initialize();

    const index = client.index('articles');
    expect(index.updateSettings).toHaveBeenCalledWith(
      expect.objectContaining({
        searchableAttributes: ['title', 'content', 'author'],
      })
    );
  });

  test('configures filterable attributes for faceting', async () => {
    await service.initialize();

    const index = client.index('articles');
    expect(index.updateSettings).toHaveBeenCalledWith(
      expect.objectContaining({
        filterableAttributes: ['category', 'tags', 'published_at'],
      })
    );
  });

  test('sets ranking rules in correct order', async () => {
    await service.initialize();

    const index = client.index('articles');
    expect(index.updateSettings).toHaveBeenCalledWith(
      expect.objectContaining({
        rankingRules: ['words', 'typo', 'proximity', 'attribute', 'sort', 'exactness'],
      })
    );
  });
});

Testing Document Sync Operations

Document sync is where bugs cause real data loss. Test adds, updates, and deletes:

describe('document operations', () => {
  test('adds new article to index', async () => {
    const client = createMockMeilisearchClient();
    const service = new SearchIndexService(client);
    await service.initialize();

    const article = {
      id: 'article-1',
      title: 'Getting Started with Meilisearch',
      content: 'Meilisearch is a fast search engine...',
      author: 'Jane Smith',
      category: 'tutorials',
      published_at: '2026-01-15',
    };

    await service.indexArticle(article);

    expect(client.index('articles').addDocuments).toHaveBeenCalledWith([article]);
  });

  test('deletes article from index when unpublished', async () => {
    const client = createMockMeilisearchClient();
    const service = new SearchIndexService(client);
    await service.initialize();

    await service.removeArticle('article-1');

    expect(client.index('articles').deleteDocument).toHaveBeenCalledWith('article-1');
  });

  test('bulk indexes multiple articles efficiently', async () => {
    const client = createMockMeilisearchClient();
    const service = new SearchIndexService(client);
    await service.initialize();

    const articles = Array.from({ length: 100 }, (_, i) => ({
      id: `article-${i}`,
      title: `Article ${i}`,
      content: `Content for article ${i}`,
      author: 'Test Author',
      category: 'general',
      published_at: '2026-01-01',
    }));

    await service.bulkIndex(articles);

    // Should batch into chunks of 50 for efficiency
    expect(client.index('articles').addDocuments).toHaveBeenCalledTimes(2);
    expect(client.index('articles').addDocuments.mock.calls[0][0]).toHaveLength(50);
    expect(client.index('articles').addDocuments.mock.calls[1][0]).toHaveLength(50);
  });
});

Testing Search Result Validation

The search interface is what users see. Test that your service maps Meilisearch responses correctly:

describe('search operations', () => {
  test('returns formatted search results', async () => {
    const client = createMockMeilisearchClient();
    const service = new SearchIndexService(client);
    await service.initialize();

    const mockHits = [
      {
        id: 'article-1',
        title: 'Meilisearch Tutorial',
        content: 'Learn Meilisearch...',
        _formatted: {
          title: '<em>Meilisearch</em> Tutorial',
        },
      },
    ];

    client.index('articles').search.mockResolvedValueOnce({
      hits: mockHits,
      estimatedTotalHits: 1,
      query: 'meilisearch',
      limit: 20,
      offset: 0,
      processingTimeMs: 3,
    });

    const results = await service.search('meilisearch');

    expect(results.items).toHaveLength(1);
    expect(results.items[0].id).toBe('article-1');
    expect(results.items[0].highlightedTitle).toBe('<em>Meilisearch</em> Tutorial');
    expect(results.total).toBe(1);
    expect(results.processingTime).toBe(3);
  });

  test('sends correct parameters for paginated search', async () => {
    const client = createMockMeilisearchClient();
    const service = new SearchIndexService(client);
    await service.initialize();

    client.index('articles').search.mockResolvedValueOnce({
      hits: [],
      estimatedTotalHits: 50,
      query: 'test',
      limit: 10,
      offset: 20,
      processingTimeMs: 1,
    });

    await service.search('test', { page: 3, perPage: 10 });

    expect(client.index('articles').search).toHaveBeenCalledWith('test', {
      limit: 10,
      offset: 20, // (page 3 - 1) * perPage 10
      attributesToHighlight: ['title', 'content'],
    });
  });
});

Testing Faceted Filtering

Facets are where Meilisearch configuration errors are most painful to debug. Test filter syntax carefully:

test('applies category filter correctly', async () => {
  const client = createMockMeilisearchClient();
  const service = new SearchIndexService(client);
  await service.initialize();

  client.index('articles').search.mockResolvedValueOnce({
    hits: [],
    estimatedTotalHits: 0,
    query: '*',
    limit: 20,
    offset: 0,
    processingTimeMs: 1,
    facetDistribution: { category: { tutorials: 5 } },
  });

  await service.search('*', { filters: { category: 'tutorials' } });

  expect(client.index('articles').search).toHaveBeenCalledWith('*', 
    expect.objectContaining({
      filter: 'category = "tutorials"',
    })
  );
});

test('combines multiple filters with AND logic', async () => {
  const client = createMockMeilisearchClient();
  const service = new SearchIndexService(client);
  await service.initialize();

  client.index('articles').search.mockResolvedValueOnce({
    hits: [], estimatedTotalHits: 0, query: '*', limit: 20, offset: 0, processingTimeMs: 1,
  });

  await service.search('*', {
    filters: { category: 'tutorials', tags: 'javascript' },
  });

  expect(client.index('articles').search).toHaveBeenCalledWith('*',
    expect.objectContaining({
      filter: 'category = "tutorials" AND tags = "javascript"',
    })
  );
});

test('requests facet distribution for sidebar', async () => {
  const client = createMockMeilisearchClient();
  const service = new SearchIndexService(client);
  await service.initialize();

  const mockFacets = {
    category: { tutorials: 12, guides: 8, news: 5 },
    tags: { javascript: 15, typescript: 10 },
  };

  client.index('articles').search.mockResolvedValueOnce({
    hits: [],
    estimatedTotalHits: 25,
    query: '*',
    limit: 20,
    offset: 0,
    processingTimeMs: 2,
    facetDistribution: mockFacets,
  });

  const results = await service.searchWithFacets('*', ['category', 'tags']);

  expect(client.index('articles').search).toHaveBeenCalledWith('*',
    expect.objectContaining({
      facets: ['category', 'tags'],
    })
  );

  expect(results.facets.category).toEqual({ tutorials: 12, guides: 8, news: 5 });
});

Testing Date Range Filters

Date filtering is a common source of bugs because Meilisearch requires Unix timestamps for numeric filtering:

test('converts date range to timestamp filter', async () => {
  const client = createMockMeilisearchClient();
  const service = new SearchIndexService(client);
  await service.initialize();

  client.index('articles').search.mockResolvedValueOnce({
    hits: [], estimatedTotalHits: 0, query: '*', limit: 20, offset: 0, processingTimeMs: 1,
  });

  const startDate = new Date('2026-01-01');
  const endDate = new Date('2026-03-31');

  await service.search('*', { dateRange: { start: startDate, end: endDate } });

  const expectedStart = Math.floor(startDate.getTime() / 1000);
  const expectedEnd = Math.floor(endDate.getTime() / 1000);

  expect(client.index('articles').search).toHaveBeenCalledWith('*',
    expect.objectContaining({
      filter: `published_at >= ${expectedStart} AND published_at <= ${expectedEnd}`,
    })
  );
});

Integration Tests with Docker

For real behavior testing, run Meilisearch in Docker:

import { MeiliSearch } from 'meilisearch';
import { execSync } from 'child_process';

describe('Meilisearch integration', () => {
  let client;
  const MEILISEARCH_PORT = 7700;
  const MASTER_KEY = 'test-master-key';

  beforeAll(async () => {
    // Assumes Docker is available in CI
    execSync(
      `docker run -d --name meilisearch-test -p ${MEILISEARCH_PORT}:7700 ` +
      `-e MEILI_MASTER_KEY=${MASTER_KEY} getmeili/meilisearch:v1.8`,
      { stdio: 'pipe' }
    );
    
    // Wait for container to be ready
    await new Promise(r => setTimeout(r, 2000));

    client = new MeiliSearch({
      host: `http://localhost:${MEILISEARCH_PORT}`,
      apiKey: MASTER_KEY,
    });
  }, 30_000);

  afterAll(() => {
    execSync('docker rm -f meilisearch-test', { stdio: 'pipe' });
  });

  test('creates index and searches with typo tolerance', async () => {
    const index = client.index('test-articles');
    await index.addDocuments([
      { id: 1, title: 'Introduction to Meilisearch', category: 'tutorial' },
    ]);
    await index.waitForTask((await index.addDocuments([])).taskUid);

    // Test typo tolerance — "meilsearch" should match "Meilisearch"
    const results = await index.search('meilsearch');
    expect(results.hits.length).toBeGreaterThan(0);
    expect(results.hits[0].title).toBe('Introduction to Meilisearch');
  });
});

E2E Testing with HelpMeTest

Beyond unit and integration tests, monitor your search UX end-to-end with HelpMeTest:

Go to https://your-app.com/search
Search for "meilisearch tutorial"
Verify results appear in under 500ms
Verify results include relevant articles
Click the "tutorials" category filter
Verify results are filtered to tutorial articles only
Type a misspelled query "meillisearch"
Verify typo-tolerant results still appear

HelpMeTest runs these checks continuously, alerting you when search breaks due to index issues, configuration changes, or Meilisearch version upgrades.

Common Mistakes to Avoid

Not waiting for task completion. Meilisearch operations are asynchronous — addDocuments returns a task that runs in the background. In integration tests, always waitForTask before searching.

Missing filterable attributes. If you filter on an attribute that's not in filterableAttributes, Meilisearch returns an error. Test your settings configuration, not just your query logic.

Unix timestamp confusion. Meilisearch uses numeric filter syntax for dates. Test that your date conversion produces the right Unix timestamp, especially around timezone handling.

Assuming immediate index availability. After creating an index and configuring settings, there's processing time. In integration tests, wait for configuration tasks to complete before testing search behavior.

Summary

Effective Meilisearch testing covers:

  1. Index configuration tests — schema, searchable/filterable attributes, ranking rules
  2. Document operation tests — add, update, delete, bulk indexing
  3. Search parameter tests — query construction, pagination, filter syntax
  4. Facet tests — distribution requests and filter combinations
  5. Date and numeric filter tests — timestamp conversion and range syntax
  6. Integration tests with Docker for real behavior validation
  7. E2E monitoring with HelpMeTest for continuous search health

Mock at the unit level for speed. Use Docker containers for integration confidence. Monitor continuously in production.

Read more