How to Test Meilisearch UI with Playwright: Complete 2026 Guide

1. Why Testing Meilisearch UI Is Harder Than It Looks

Meilisearch is a fast, typo-tolerant search engine that returns results in under 50 milliseconds. On the surface, testing a search UI sounds trivial: type a query, check the results. In practice, five structural characteristics of Meilisearch make reliable UI testing significantly more complex than a simple input/output assertion.

First, typo tolerance is enabled by default and adapts based on word length. A one-character word tolerates zero typos, a word with five or more characters tolerates up to two typos, and words in between tolerate one. This means a search for “helo” returns results for “hello,” but a search for “he” does not. Your tests must account for these thresholds or they will pass locally and fail unpredictably when someone adds shorter product names to the index.

Second, Meilisearch's filter syntax uses a specific grammar that differs from SQL and from other search engines. Filters look like genre = "sci-fi" AND rating > 4 but require every filterable attribute to be explicitly declared in filterableAttributes before the index accepts it. A filter on an undeclared attribute returns zero results without any error message in the UI, which is a common source of silent test failures.

Third, sortable attributes must also be pre-declared. Sorting by a field that is not in sortableAttributes returns a 400 error from the API, but most search UI libraries catch that error silently and show an empty result set. Fourth, the distinct attribute collapses duplicate entries (for example, multiple variants of the same product) into a single hit, which changes your expected result count in ways that are difficult to predict without understanding the index configuration. Fifth, Meilisearch offers both offset/limit pagination and a newer finite pagination mode, and they behave differently when combined with filters and sorting.

A good Meilisearch UI test suite covers all five of these surfaces. The sections below walk through each scenario you need, with runnable Playwright TypeScript code you can paste directly into your project.

2. Setting Up a Reproducible Test Environment

Meilisearch tests are only deterministic when you control the index state completely. That means seeding a known dataset before each test run, configuring settings (filterable, sortable, distinct attributes) explicitly, and waiting for Meilisearch to finish processing before running any search assertions. Skipping any of these steps leads to flaky tests.

Docker Setup and Environment Variables

Index Seeding Script

Every test run should start with a clean, fully indexed dataset. The seeding script deletes the existing index, creates a fresh one with all required settings, adds documents, and waits for the indexing task to complete. This guarantees deterministic results regardless of what previous test runs left behind.

Playwright Configuration

3. Scenario: Basic Search and Result Rendering

The first scenario every Meilisearch integration needs is a basic search query that returns results and renders them correctly in the UI. This is your smoke test. If this breaks, nobody can search your application and you want to know immediately. The flow is straightforward: the user types a query in the search input, the UI debounces the input (typically 200 to 300 milliseconds), sends a request to Meilisearch, receives the response, and renders the hits.

import { test, expect } from '@playwright/test';

test('basic search returns matching results', async ({ page }) => {
  await page.goto('/search');
  const searchInput = page.getByRole('searchbox');
  await searchInput.fill('headphones');
  await page.waitForTimeout(500);

  const results = page.locator('[data-testid="search-hit"]');
  await expect(results.first()).toBeVisible();

  const hitCount = await results.count();
  expect(hitCount).toBeGreaterThanOrEqual(2);
  await expect(results.first()).toContainText(/headphones/i);

  const hitCounter = page.getByTestId('hit-count');
  await expect(hitCounter).toContainText(/\d+ result/i);
});

4. Scenario: Typo Tolerance Verification

Meilisearch's typo tolerance is one of its most valuable features, but it is also one of the hardest to test correctly. The engine uses a distance-based algorithm that allows a configurable number of character substitutions, insertions, or deletions based on word length. By default, words with fewer than 5 characters allow one typo, and words with 8 or more characters allow two typos. These thresholds are configurable via the typoTolerance.minWordSizeForTypos setting.

The tricky part for testing is that typo tolerance interacts with ranking rules. An exact match always ranks higher than a one-typo match, which ranks higher than a two-typo match. Your test must verify not just that results appear, but that they appear in the correct relevance order. A search for “headphonas” (one typo in an 10-character word) should return “Headphones” results, but a search for “hep” (attempting “help” with one typo in a 3-character input) may return nothing because the word is too short for typo tolerance to activate.

test('single typo returns correct results', async ({ page }) => {
  await page.goto('/search');
  const searchInput = page.getByRole('searchbox');
  await searchInput.fill('headphonas');
  await page.waitForTimeout(500);

  const results = page.locator('[data-testid="search-hit"]');
  await expect(results.first()).toBeVisible();
  await expect(results.first()).toContainText(/headphones/i);
});

5. Scenario: Faceted Filter Syntax and Combination

Meilisearch supports faceted filtering through a custom filter syntax that looks like SQL but has its own rules. Filters use operators like =, !=, >, <, TO (for ranges), and IN (for multiple values). You can combine them with AND, OR, and NOT. The critical prerequisite is that every attribute you want to filter on must be declared in filterableAttributes before you index documents.

In the UI, faceted filters typically appear as checkboxes, dropdown menus, range sliders, or clickable category badges. The challenge for testing is verifying that the UI correctly translates user interactions into Meilisearch filter syntax, and that the results accurately reflect the applied filters. A common bug is the UI sending category: Electronics (colon syntax from other search engines) instead of category = "Electronics" (Meilisearch syntax), which silently returns zero results.

6. Scenario: Sortable Attributes and Ranking

Meilisearch separates its relevance ranking from explicit sorting. By default, results are ranked by a combination of word matching, typo proximity, attribute position, and exactness. When you apply a sort (for example, “price ascending”), Meilisearch overrides the relevance ranking with the specified sort order. The key caveat is that only attributes listed in sortableAttributes can be sorted. Attempting to sort by an undeclared attribute returns an API error, which most search UI libraries catch silently and display as an empty or unsorted result set.

Testing sort behavior requires verifying three things: that the sort dropdown or button exists and is functional, that the results are actually reordered according to the selected criterion, and that switching between sort options updates the results correctly. A subtle bug to watch for is sort stability: when two documents have the same sort value (for example, two products at $79.99), Meilisearch falls back to the default ranking rules for the tiebreaker, but the UI may display them in an inconsistent order across requests.

test('sort by price ascending', async ({ page }) => {
  await page.goto('/search');
  await page.getByRole('searchbox').fill('');
  await page.waitForTimeout(500);

  const sortSelect = page.getByLabel('Sort by');
  await sortSelect.selectOption('price:asc');
  await page.waitForTimeout(500);

  const priceElements = page.locator('[data-testid="hit-price"]');
  const count = await priceElements.count();
  const prices: number[] = [];
  for (let i = 0; i < count; i++) {
    const text = await priceElements.nth(i).textContent();
    prices.push(parseFloat(text?.replace('$', '') || '0'));
  }
  for (let i = 1; i < prices.length; i++) {
    expect(prices[i]).toBeGreaterThanOrEqual(prices[i - 1]);
  }
});

7. Scenario: Distinct Attribute Deduplication

The distinctAttribute setting in Meilisearch collapses multiple documents that share the same value for a given field into a single result. A common use case is product variants: if you have five color variants of the same shoe, each as a separate document, setting distinctAttribute: "sku" or distinctAttribute: "brand" ensures only one variant appears per group.

This feature is deceptive to test because it changes the result count in ways that are not obvious from the query alone. A search for “wireless” in our test dataset would normally return four SoundMax products, but with distinctAttribute: "brand" set, only one SoundMax product appears (the most relevant one). Your test must know the distinct attribute configuration to predict the correct result count. If the index configuration changes and the distinct attribute is removed, your tests will suddenly see more results and fail. Conversely, if someone adds a distinct attribute you did not account for, tests expecting a certain number of results will see fewer and break.

8. Scenario: Pagination vs Infinite Hits

Meilisearch offers two pagination strategies, and they work differently under the hood. The default uses offset and limit parameters for infinite-scroll-style loading. The alternative uses page and hitsPerPage for traditional numbered pagination. The critical difference is that the offset/limit approach does not return a totalPages or totalHits count by default (these appear as estimatedTotalHits), while the page/hitsPerPage approach returns exact totalHits and totalPages.

This distinction matters for testing because your assertions about “how many total results exist” depend on which pagination mode your UI uses. The maxTotalHitssetting in the index's pagination configuration caps the number of results Meilisearch will return across all pages. If you set maxTotalHits: 100 but your index has 500 matching documents, the API only returns the first 100 regardless of how many pages you request.

test('page navigation shows correct results', async ({ page }) => {
  await page.goto('/search');
  await page.getByRole('searchbox').fill('');
  await page.waitForTimeout(500);

  const results = page.locator('[data-testid="search-hit"]');
  const page1First = await results.first().textContent();

  const nextBtn = page.getByRole('button', { name: /next/i });
  if (await nextBtn.isVisible()) {
    await nextBtn.click();
    await page.waitForTimeout(500);
    const page2First = await results.first().textContent();
    expect(page2First).not.toBe(page1First);

    await page.getByRole('button', { name: /prev/i }).click();
    await page.waitForTimeout(500);
    const restored = await results.first().textContent();
    expect(restored).toBe(page1First);
  }
});

9. Common Pitfalls That Break Meilisearch Test Suites

After reviewing dozens of Meilisearch GitHub issues and community forum threads, here are the pitfalls that most frequently break real search test suites. Each one is sourced from actual production failures.

The Indexing Race Condition

The single most common cause of flaky Meilisearch tests is the indexing race condition. Unlike synchronous databases, Meilisearch processes document additions and setting updates as asynchronous tasks. When you call index.addDocuments(), it returns immediately with a task ID while the actual indexing happens in the background. If your test starts searching before the task completes, it will see stale or empty results.

Network Request Interception for Debugging

When a Meilisearch test fails, intercepting the network request reveals whether the problem is in the UI (sending the wrong query) or the backend (returning unexpected data). Playwright's route interception is invaluable for diagnosing these failures.

10. Writing These Scenarios in Plain English with Assrt

The Playwright scenarios above are thorough but verbose. Each one requires understanding Playwright's locator API, managing timeouts and waits, parsing text content for assertions, and handling the specific behavior of your search UI library. Assrt lets you express the same scenarios in plain English, and it compiles them into the equivalent Playwright TypeScript code.

Here is the faceted filter scenario (Section 5) rewritten as an Assrt file. The scenario file describes the intent, not the implementation. Assrt figures out the selectors, waits, and assertions based on your actual running application.

Assrt compiles each scenario block into the same Playwright TypeScript you saw in the preceding sections, committed to your repo as real tests you can read, run, and modify. When Meilisearch updates its API, when your search UI library renames components, or when someone changes the index configuration, Assrt detects the failure, analyzes the new DOM, and opens a pull request with the updated locators. Your scenario files stay untouched.

Start with the basic search smoke test. Once it is green in your CI, add the typo tolerance scenario, then the faceted filter tests, then sort verification, then distinct attribute deduplication, then pagination. In a single afternoon you can have complete Meilisearch search UI coverage that most production applications never manage to achieve by hand.