Link header rather than constructing URLs, and assert three things about the union: it equals the reference set, it contains no duplicate identifiers, and its order matches the reference sequence. Page lengths and a spot-check of page one cannot detect a hidden record. Then repeat the traversal with an insert and a delete landing between requests, because that is when offset pagination skips and duplicates rows.Nothing in an ordinary pagination suite can detect a record that was never returned. Page one has the right length. Page two starts with a different item. An out-of-range page comes back empty. All three assertions hold on an endpoint that quietly drops rows out of a nightly reconciliation walk.
\n\nThe records lost that way are not corrupt, not filtered, and not on a boundary. They were pushed across one by rows inserted ahead of them while the client sat between two requests — and no assertion about a single response can watch that happen.
\n\nPagination is a property of a traversal, not of a response, so no assertion about one response can establish it. What you need is a set whose membership and order you decided in advance, and three claims about the union of every page.
\n\nimport { test, expect } from '@playwright/test';\nimport { seedOrders, allPages } from './support/orders';\n\ntest('a full traversal returns every order exactly once, in order', async ({ request }) => {\n // 11 records with a deliberate tie: three share a createdAt value, and the\n // page size does not divide the total. Both are where traversals break.\n const reference = await seedOrders(request, {\n count: 11,\n duplicateTimestampsAt: [4, 5, 6],\n });\n\n const pages = await allPages(request, '/v1/orders?sort=-createdAt,-id&limit=3');\n const seen = pages.flatMap((page) => page.items.map((o: { id: string }) => o.id));\n\n // 1. Completeness: nothing hidden, nothing extra.\n expect(new Set(seen)).toEqual(new Set(reference.ids));\n // 2. Uniqueness: a record that appears on two pages is as wrong as a missing one.\n expect(seen.length).toBe(reference.ids.length);\n // 3. Order: the sequence, not just the membership.\n expect(seen).toEqual(reference.idsInSortOrder);\n // 4. Shape: only the last page may be short.\n expect(pages.slice(0, -1).map((p) => p.items.length)).toEqual([3, 3, 3]);\n expect(pages.at(-1)!.items.length).toBe(2);\n});Assertions one and two look redundant and are not. Comparing sets catches a missing record; comparing lengths catches a duplicated one, because a set of eleven distinct IDs can come from twelve responses. Run both, and keep the sorted sequence separate from the membership check so a failure tells you whether data went missing or merely moved.
\n\nDeliberately choosing a count the page size does not divide is worth the small effort. A total of twelve with a limit of three hides every off-by-one in the final page, and a final page is where the cursor either terminates or loops.
\n\nPostgreSQL's documentation is blunt about the underlying issue: without an explicit sort step, \"the rows will be returned in an unspecified order\", which \"will depend on the scan and join plan types and the order on disk, but it must not be relied on\". Adding ORDER BY created_at DESC constrains rows with different timestamps and leaves rows with equal ones free to come back in any order — and free to come back in a different order on the next request, because a subsequent query may use a different plan.
That is enough to lose a record. If three orders share a timestamp and a page boundary falls between the second and the third, request two can return the same row again and never return the one it displaced.
\n\nThe fix is a total order: every sort must end in a column that is unique, in the same direction.
\n\n-- Rows sharing created_at may appear in any order, and a different order\n-- each time the query runs.\nORDER BY created_at DESC\nLIMIT 3 OFFSET 3;\n\n-- A total order. id breaks every tie, so the sequence is reproducible.\nORDER BY created_at DESC, id DESC\nLIMIT 3;The test that discriminates needs more tied rows than fit on one page. Three records with an identical timestamp and a page size of three cannot detect the bug, because the tie never straddles a boundary. Seed at least pageSize + 1 tied rows, then assert the full sequence twice:
test('a tie straddling a page boundary traverses identically twice', async ({ request }) => {\n await seedOrders(request, { count: 9, sameTimestampForAll: true });\n\n const first = await allPages(request, '/v1/orders?sort=-createdAt,-id&limit=4');\n const second = await allPages(request, '/v1/orders?sort=-createdAt,-id&limit=4');\n\n const ids = (pages: typeof first) => pages.flatMap((p) => p.items.map((o: { id: string }) => o.id));\n expect(ids(first)).toEqual(ids(second));\n expect(new Set(ids(first)).size).toBe(9);\n});Repeating the traversal is what makes this a test rather than a coin flip. A single walk over an unstable sort passes most of the time; two walks compared against each other fail as soon as the plan differs, and they fail with output that names the rows that moved.
\n\nSorting on a nullable column is where a correct-looking API behaves differently in staging and production, and the reason is documented rather than mysterious. The two most common engines have opposite defaults.
\n\n| Engine | ORDER BY col ASC | ORDER BY col DESC |
|---|---|---|
| PostgreSQL | Nulls last | Nulls first |
| MySQL | Nulls first | Nulls last |
PostgreSQL documents that null values sort as if larger than any non-null value, which makes NULLS FIRST the default for descending order and NULLS LAST otherwise. MySQL documents the reverse: nulls are presented first for ascending order and last for descending. Neither is wrong, and an API that sorts by shippedAt without an explicit null clause has a placement that comes from its connection string.
Two consequences for the suite. Where nulls appear is part of the API's contract and belongs in the description, so the test asserts a position rather than tolerating either. And a nullable sort column cannot be the tie-breaker, because null values are equal to each other for ordering purposes and put you straight back into an unstable sort.
\n\ntest('unshipped orders sit at the end of a descending shippedAt sort', async ({ request }) => {\n const reference = await seedOrders(request, { shipped: 4, unshipped: 3 });\n\n const pages = await allPages(request, '/v1/orders?sort=-shippedAt,-id&limit=3');\n const seen = pages.flatMap((p) => p.items);\n\n // The declared contract: nulls last regardless of engine. If the API has not\n // declared one, this test is the forcing function to make it decide.\n expect(seen.slice(0, 4).map((o) => o.id)).toEqual(reference.shippedIdsDesc);\n expect(new Set(seen.slice(4).map((o) => o.id))).toEqual(new Set(reference.unshippedIds));\n});Link header rather than building the next URLIf the API paginates with a cursor, the cursor is an opaque token and the client's job is to follow a link, not to assemble one. A test that reads response.body.nextCursor and appends it to a base path is asserting an implementation detail, and it will keep passing after the server moves the cursor into the header where clients look for it.
RFC 8288 defines the serialisation, and four of its rules trip up hand-written assertions. The target IRI sits inside angle brackets and may be a relative reference, which parsers MUST resolve against the request URI — and explicitly not against any base IRI in the message content. The rel parameter MUST be present and MUST NOT appear more than once in a link-value, with later occurrences ignored. Parameter values may be given as a token or a quoted string and recipients MUST be able to parse both, so rel=next and rel=\"next\" are the same link. And rel may carry several space-separated relation types, which are compared case-insensitively.
; All four of these advertise the same next page.\nLink: </v1/orders?cursor=b3JkXzk5MQ&limit=3>; rel=\"next\"\nLink: </v1/orders?cursor=b3JkXzk5MQ&limit=3>; rel=next\nLink: <https://api.example.com/v1/orders?cursor=b3JkXzk5MQ>; rel=\"next last\"\nLink: </v1/orders?cursor=b3JkXzk5MQ>; rel=\"NEXT\"; title=\"page 2\"A traversal helper that handles those cases is short, and writing it once removes a whole class of false failures:
\n\n/** Returns the resolved next-page URL, or null when the chain ends. */\nexport function nextLink(headerValue: string | undefined, requestUrl: string): string | null {\n if (!headerValue) return null;\n\n for (const value of headerValue.split(/,(?=\\s*<)/)) {\n const target = value.match(/<([^>]*)>/)?.[1];\n if (!target) continue;\n\n // rel may be a token or quoted, and may list several types.\n const rel = value.match(/;\\s*rel\\s*=\\s*(?:\"([^\"]*)\"|([^;,\\s]+))/i);\n const types = (rel?.[1] ?? rel?.[2] ?? '').toLowerCase().split(/\\s+/);\n // Relation types compare case-insensitively; only the first rel counts.\n if (types.includes('next')) return new URL(target, requestUrl).toString();\n }\n return null;\n}Then the termination condition is the absence of a next link, not a page shorter than the limit. Those are different conditions: a server may legitimately return a full page and no next link when the last record happens to fill it, and it may return a short page with a next link when a filter is applied after the fetch. Assert on the link, and add a hard iteration cap so a cursor that returns itself fails as a test rather than as a hung run.
\n\nThis is the failure the opening describes, and it is the test almost nobody writes because it requires doing something between two requests.
\n\nThe mechanism is worth stating precisely, because it decides the expectation rather than being background. Offset pagination addresses rows by position in the result set. Insert a row that sorts ahead of the current offset and every later row shifts down by one, so the row that was about to be returned moves behind the offset and is never seen. Delete such a row and everything shifts up, so a row already returned is returned again. Keyset pagination addresses rows by value — \"the next three rows after (created_at, id)\" — and inserting ahead of the cursor changes nothing about which rows follow it.
That asymmetry is not a preference. For any traversal a client walks to completion — an export, a reconciliation, a sync — keyset is the correct mechanism and offset is a known-lossy one. Offset remains reasonable for a paginated screen a person clicks through, where a shifted row is a cosmetic surprise rather than a missing payment.
\n\ntest('an order inserted mid-traversal does not displace an unread one', async ({ request }) => {\n const reference = await seedOrders(request, { count: 7 });\n\n const page1 = await getPage(request, '/v1/orders?sort=-createdAt,-id&limit=3');\n\n // Land a record that sorts ahead of everything already returned.\n const intruder = await seedOrders(request, { count: 1, newest: true });\n\n const rest = await followFrom(request, page1);\n const seen = [...page1.items, ...rest.flatMap((p) => p.items)].map((o) => o.id);\n\n // Every pre-existing order appears exactly once. The late arrival may or may\n // not appear — a cursor taken before it existed is not required to see it.\n expect(new Set(seen)).toEqual(\n new Set(seen.includes(intruder.ids[0]) ? [...reference.ids, ...intruder.ids] : reference.ids),\n );\n expect(new Set(seen).size).toBe(seen.length);\n});Note what that test does not assert. Whether the newly inserted record appears is a snapshot question, and requiring either answer would be inventing a guarantee. What is not negotiable is that no pre-existing record vanishes and none arrives twice. Write the deletion variant too, with the deleted row sorting ahead of the cursor, because it fails differently: offset duplicates rather than skips, and a suite that only tests inserts will report the endpoint as sound.
\n\nBefore writing filter cases, check how the description says the parameters are spelled, because the OpenAPI defaults are not what most people assume. For a query parameter, style defaults to form, and when style is form, explode defaults to true. An array parameter left at the defaults is therefore serialised as repeated parameters, not as a comma-joined list.
- name: sort\n in: query\n schema: { type: array, items: { type: string } }\n # Defaults: style=form, explode=true -> ?sort=-createdAt&sort=-id\n- name: status\n in: query\n explode: false\n schema: { type: array, items: { type: string, enum: [PLACED, SHIPPED] } }\n # explode: false -> ?status=PLACED,SHIPPED\n- name: filter\n in: query\n style: deepObject\n explode: true # required in practice: deepObject with false is undefined\n schema: { type: object, properties: { status: { type: string } } }\n # ?filter[status]=SHIPPEDThe deepObject note is in the specification itself: despite false being the documented default for explode outside form, the combination of false with deepObject is undefined. An API relying on that pairing has no defined wire format, and two clients generated from the same description can disagree — which surfaces as a filter that silently matches everything.
With the spelling settled, filter composition needs one case per combination rule rather than one per filter. Two filters that must both hold, a filter combined with a sort, a filter whose result is empty, and a filter that eliminates everything after the first page. That last one is the interesting case: it distinguishes an API that filters before paginating from one that fetches a page and then filters it, and only the first can keep its page sizes honest.
\n\nBoundary sizes are cheap and worth one case each: limit=1, limit at the documented maximum, limit one above it — which should be refused or clamped, and the description must say which — and a traversal whose total is an exact multiple of the limit, where the final request returns an empty page or no next link.
A suite asserting items.length on each page and a total in the response envelope will pass on an endpoint that returns one row twice and drops another, because both numbers stay correct. The diagnosis is a grep: if no test in the file compares a set of identifiers against a set you seeded, completeness is untested no matter how many cases there are. This is the same reason the total in the envelope is not evidence — it usually comes from a separate COUNT query that does not share the paginated query's plan.
Five records with a page size of ten produce one page, and one page exercises no boundary, no cursor and no tie. The symptom is a suite that never reaches a second request. Size the fixture from the behaviour: at least three pages, a tie wider than one page, a total that is not a multiple of the limit, and at least one null in every nullable sort column. That is around a dozen records, which is still fast.
\n\nCompleteness assertions are the most order-dependent tests you will write: any other worker inserting into the same collection breaks them, and it breaks them intermittently. Scope every traversal to data only it can see — a per-test tenant, account or tag included in the filter — and assert that scoping in the test rather than assuming it. A completeness test against a shared table is not flaky; it is measuring the wrong set.
\n\nTest the guarantee it can actually make, and write down the one it cannot. A stable total order and correct behaviour at every boundary are achievable on offset pagination and worth covering. Completeness under concurrent writes is not, so rather than a test that passes when the race does not happen, record the limitation where consumers will see it and give the reconciliation-style callers a different route: a snapshot endpoint, an as-of timestamp filter, or a change feed. A skipped test with a comment is more honest than a passing one that only fails in production.
\n\nNot in the suite that gates merges. Decoding couples the test to an encoding the API is free to change, and it will produce a failure that looks like a pagination bug when a field name changed inside a base64 blob. There is one exception worth making deliberately: a single test asserting that the cursor is opaque in the way you intended — that it is not a plain offset, and that a tampered cursor is rejected rather than silently treated as page one. Write that test against the property, not against the contents.
\n\nIt depends on what the description promises, and this is worth deciding rather than inheriting. An exact total requires a second query whose answer can already be stale by the time the response is serialised, so a total that disagrees with the number of records a traversal yields is expected on a busy collection. If the API documents the total as exact, the disagreement is a defect; if it documents it as approximate, the test asserts it is within a stated tolerance and the traversal is the only source of truth for completeness. Silence in the description is the actual bug.
\n\nCombinatorial expansion is exactly what it is good for, and it will produce a fuller cross product of filters, sorts and page sizes than anyone writes by hand. What it cannot supply is the reference data. The expected result for every one of those combinations comes from a set you seeded and ordered yourself, and a model asked to predict which records should match will produce an expectation derived from the same assumptions the implementation might have got wrong. Take the combinations; compute every expectation from the reference set.
\n\nLink field ABNF, the target IRI in angle brackets and the requirement to resolve relative references against the request rather than any base IRI in the content (§3.1), and the rel parameter rules — present exactly once, later occurrences ignored, multiple space-separated relation types permitted (§3.3)NULLS FIRST the default for DESC and NULLS LAST otherwiseORDER BY ... ASC and last for DESC, the opposite of PostgreSQL's defaultstyle defaulting to form for query parameters, explode defaulting to true when style is form and false otherwise, the statement that deepObject combined with explode: false is undefined, and allowReserved for reserved characters in query valuesheaders() for reading the Link field, and the response accessors used throughout the examplesPick the collection endpoint a machine walks to completion — the export, the sync, the nightly reconciliation — and read its sort clause. If it does not end in a unique column in the same direction, you have found a defect without writing a test, and it is the one most likely to be losing records already.
\n\nThen write the traversal test: seed a dozen records with a tie wider than one page and a null in each nullable sort column, walk the pages by following the Link header, and assert set equality, length equality and the full sequence against your reference. Run it twice in the same test. Add the insert-between-pages variant once it passes. Save the reference sequence, the cursor or offset behind each request, and the union that came back, then compare records seeded against records seen. Those two numbers have to match, and they have to come from different places — one from your fixture, one from the traversal. Read them both out of the same response envelope and they will agree while being wrong.