How should search acceptance criteria cover exact and fuzzy matches, result fields, pagination and empty states?
“Users can search” is not an acceptance criterion. A buyer needs to define what each role is trying to find, which inputs and fields are valid, when exact or forgiving matching applies, why one result ranks ahead of another, which attributes make records distinguishable, and how permissions, pagination, empty results and changing data behave. Acceptance then uses a frozen set of real queries and expected outcomes—not a few improvised keywords at the final demonstration.
Start with the retrieval job, not the search box
This guidance applies to custom apps, Mini Programs and operational tools that retrieve products, customers, orders, equipment, cases, people or documents. It does not require a dedicated search engine for every project. A small, structured back office may be better served by database lookup and explicit filters. Large text collections, multilingual content, misspellings and relevance ranking may justify a specialist service.
Atlassian's acceptance-criteria guidance describes clear, concise and testable completion conditions. Its product-search example includes exact and partial matching, result fields, pagination and an empty state. The example's three-character trigger and 20-result page are illustrations, not universal requirements. The project must set values from its own data, tasks and device experience.
Map each role to a retrieval job before writing behaviour:
| Retrieval job | Priority fields | Typical behaviour | Information needed to identify the result |
|---|---|---|---|
| Find an order for a refund | Full order and external transaction identifiers | Exact match first | State, customer, amount, date and organisation |
| Find a customer for follow-up | Name, phone, company and approved aliases | Exact, prefix or normalized match | Permission-safe contact, owner and status |
| Find a product or installed asset | Code, barcode, name, model and legacy code | Exact code first; partial name match | Specification, state, location or ownership |
| Find an approved document | Title, body, tags and version | Full-text relevance | Title, excerpt, version, scope and update date |
“Search every field” is rarely an adequate scope. Internal notes, obsolete versions and another tenant's data may be forbidden, while irrelevant fields can degrade results. Searchable fields, visible fields and authorization need one design.
Turn matching language into observable rules
The business owner need not select an algorithm, but must specify behaviour that can pass or fail:
- Exact lookup: a complete order, serial or product code ranks first or opens directly. State how case, whitespace, punctuation and full-width characters are normalized.
- Prefix and partial matching: define the minimum input, eligible fields and whether short fragments would create unacceptable noise.
- Fuzzy matching: identify fields where a misspelling or transposition is tolerable. High-consequence identifiers, amounts and identity attributes should not become a guessed match merely because they look similar.
- Synonyms and business aliases: govern legacy codes, abbreviations and official names through a maintained mapping. Do not silently invent a relationship between business records.
- Filters: treat state, date, location, owner, category and organization as explicit constraints rather than pretending they are all free text.
Microsoft's Azure AI Search fuzzy-query documentation explains that edit-distance expansion can recover misspellings but can also match syntactically close, semantically different terms and run more slowly than ordinary queries. Elastic's independent fuzzy-query reference likewise describes edit-distance expansion and warns that examining too many variants can hurt performance. These are implementation facts from two products, not a recommendation to buy either one. They show why “more forgiving” does not automatically mean “more accurate.”
Specify a result that a person can act on
A result card should distinguish records. Two customers with the same name may need company, region, owner and status. Installed equipment may need serial number, customer, site and warranty state. A policy document may need version, publication date and applicable population. Highlighting can help explain a match, but it must never reveal a field the user is not authorized to read.
Ranking also needs an accountable order. A sensible product-specific rule might put an exact code or title first, then matches in high-value fields, followed by relevance, recency or business state. Promotions, inventory, proximity and manual pinning are separate commercial rules and should be declared. Acceptance checks not only that something appears, but that the likely target appears in a reasonable position while inactive, unauthorized and plainly irrelevant records do not outrank it.
Microsoft's result-shaping documentation separates total matches, returned fields, scoring, sorting, highlighting and pagination, and recommends choosing fields that let users distinguish results. A custom product still chooses those fields from the real task and privacy boundary.
Treat pagination as data behaviour
Define page size, default ordering, whether a changed filter returns to page one, whether conditions survive navigation, whether an exact total is necessary, and what may happen when data changes. Microsoft's documentation notes that offset-style pages are independent queries: when the index changes between requests, a record can move or appear twice.
That may be acceptable for discovery browsing but unsafe for a batch-processing queue. The application should identify records by stable IDs, never by visual row position. When the task requires stable progress, consider a unique secondary sort, a cursor or snapshot, or another agreed mechanism. Acceptance should insert, update and remove records between pages and verify the promised behaviour.
Make zero results useful—and honest
A blank area is not an empty state. Show the submitted query and active filters, preserve them for correction, and offer appropriate actions such as checking spelling, removing a filter, shortening the term or requesting a governed alias or new record.
Do not eliminate every zero-result state by returning unrelated content. “Not found” is safer for order numbers, serials and identity lookups than an approximate guess. Broader suggestions may be appropriate for product browsing or knowledge discovery. The empty-state contract changes with the consequence of a false positive.
Use a frozen acceptance set
Write every criterion as test data, input, expected result, forbidden result and evidence:
| Case | Prepared data and input | Pass condition | Evidence |
|---|---|---|---|
| Complete code | Record AB-1024 exists; enter the full code |
Target is first; another tenant's record is absent | Screenshot, result IDs and access log |
| Normalization | Enter agreed case, spacing or punctuation variants | The same record is found only for supported variants | Request and response |
| Partial name | Enter an approved product-name fragment | Expected candidates appear in the agreed order | Frozen result list |
| Typo tolerance | Enter a documented misspelling | Target appears with an explainable basis; irrelevant results remain within the agreed boundary | Results and latency |
| Tenant isolation | Search a known Organization B term as Organization A | Results, counts, suggestions and highlights expose nothing from B | Role test and audit trail |
| Pagination under change | Insert a higher-ranked record between page requests | Behaviour matches the stability contract and cannot cause duplicate processing | Two responses and unique IDs |
| Empty result | Enter a nonexistent code with active filters | Clear empty message, preserved context and an actionable next step | UI capture |
Replace the sample identifier and every quantitative threshold with project data. The set should cover frequent and long-tail queries, namesakes, old aliases, misspellings, punctuation, multiple languages, inactive records, unauthorized records, recently updated data and genuinely absent items. Business owners approve expected results before final tuning. The same set runs again after relevance, synonym or indexing changes.
Connect performance to the task
Performance criteria need data volume, concurrency, network, device and query type. Test ordinary queries, the broadest permitted query, complex filters, first-page retrieval and deep navigation separately. If the interface renders basic results before counts or recommendations, accept those completion points separately rather than using one vague “fast” target.
After launch, observe zero-result queries, reformulation, result-to-detail actions, filter use, latency, failures and authorization denials. These signals identify data, vocabulary and ranking problems; they do not prove satisfaction on their own. A high zero-result rate may mean a missing alias or demand for an object the product does not provide. Repeated clicks may indicate poor identification rather than success.
Common failure modes
- “Fuzzy search” is treated as a switch with no eligible fields, false-match boundary or latency condition.
- A polished demonstration replaces a frozen set of expected, missing and forbidden results.
- The team checks presence but not order, visible fields, authorization, inactive data or the destination record.
- Filters, code lookup, full-text retrieval and AI answers are collapsed into one vague feature.
- The first result or total count is presented as proof of search quality without measuring omissions and noise.
- Indexing delay is ignored, so a changed business record remains stale in search.
- No owner maintains aliases, synonyms, field weights and failed-query review after launch.
Sign-off checklist
- Each role and entry point has a defined target object and next action.
- Searchable, filterable, visible and forbidden fields are separate.
- Exact, prefix, partial, fuzzy, synonym and alias behaviour has a stated scope.
- Ranking explains the priority of identifiers, important fields, business state and relevance.
- Authorization is consistent across matches, counts, suggestions, highlights, exports and detail pages.
- Pagination, filters, changing data and stable identifiers have tests.
- Empty results and service failures have different, actionable states.
- A frozen set covers correct matches, false positives, omissions, unauthorized data and no-result cases.
- Performance includes a stated dataset, concurrency, network, device and query class.
- An owner reviews failed queries, aliases and ranking changes after launch.
Search is a retrieval contract across data, authorization, ranking and the business action that follows. Repeatable samples and evidence let a buyer determine whether people can find the correct object—not merely whether an endpoint returned records. For the wider delivery agreement, pair this feature-specific contract with how software acceptance criteria should be defined and handled when they fail.
References
- Atlassian: What is acceptance criteria?, accessed 30 September 2026; clear, testable, outcome-focused criteria and the product-search example.
- Microsoft Learn: Fuzzy search in Azure AI Search, accessed 30 September 2026; typo tolerance, term expansion, false matches and performance trade-offs.
- Microsoft Learn: Shape search results, accessed 30 September 2026; returned fields, ranking, counts, pagination and stability under changing data.
- Microsoft Learn: Filters for keyword search, accessed 30 September 2026; the distinction between exact filtering and text retrieval, including category and security constraints.
- Elastic: Fuzzy query, accessed 30 September 2026; independent product documentation for edit distance, query expansion and performance risk.