A Pagination Test Fixture for Catalogues That Change While You Browse
Pagination feels simple until the data moves. If a product is added or removed after a shopper loads page one, page two may repeat an item or silently skip one. This article proposes a small fixture and a test matrix for finding those faults. It is a conditional design suggestion with hypothetical examples, not a description of any existing system.
Know which pagination you have
The fault pattern depends on the method, so identify it first.
- Offset based: page two means "skip the first N records". Inserts and deletes before the current position shift everything.
- Cursor based: page two means "records after this marker". Shifts are smaller, but a deleted marker record can cause trouble.
- Snapshot based: the list is frozen when browsing starts. Shifts disappear, but the data can become stale.
If you do not know which one applies, run the matrix below and let the results tell you.
Build the fixture
Create a small test catalogue with a page size of 5 and 20 records with stable, readable identifiers, such as A01 to A20, in a fixed sort order. Use a sort key with ties on purpose, for example several records with the same category, so you also test tie ordering. Keep the fixture separate from real data.
The test script loads a page, applies a change, loads the next page, and compares what it saw against the full expected list.
Insert and delete matrix
For each row, load page 1 (A01 to A05), apply the change, load page 2, then continue to the end.
| Case | Change after page 1 | Offset risk | What to check |
|---|---|---|---|
| 1 | Insert a record sorting before A01 | Duplicate (A05 repeats on page 2) | No record appears twice |
| 2 | Insert a record inside page 1 range | Duplicate | Same |
| 3 | Insert a record after A05 | None expected | New record appears once |
| 4 | Delete A03 | Missing (A06 skipped) | Every surviving record appears |
| 5 | Delete A05, the last seen record | Missing, and cursor marker gone | Cursor still resolves |
| 6 | Delete a record on page 2 before loading it | None expected | Page 2 remains valid |
| 7 | Change a record's sort key so it moves across the boundary | Duplicate or missing | Record appears once or is explained |
| 8 | Insert and delete together | Net shift of zero but wrong content | Compare identifiers, not counts |
The last row matters because a count-only check passes while the content is wrong. Always compare identifiers.
Branching choices
If the matrix shows duplicates or gaps with an offset method, you can choose among three responses: move to cursor pagination, freeze a snapshot per browsing session, or accept the drift and tell the shopper the list may have changed. Which fits depends on how often your catalogue changes during a visit and how costly a skipped item is. A frequently changing stock list may justify a notice. A slow-moving catalogue may not.
If cursor pagination fails case 5, define a fallback: for example, cursors that encode the sort key value rather than only the record identifier, so a deleted marker still has a position.
Hypothetical worked example
With the 20-record fixture at page size 5, a tester loads page one and sees A01 to A05. A script then deletes A03. In an offset system, page two now starts at the sixth record of the remaining list, which is A07, so A06 never appears. The tester logs case 4 as a missing record. After switching the hypothetical system to cursors based on the sort key, the same test shows A06 on page two, and the full walk returns 19 distinct records.
Stop conditions
Stop and fix the pagination before further work if any case yields a duplicate or missing record that is not announced to the shopper. Stop and reconsider the fixture if results vary between identical runs, since that suggests unstable ordering rather than a pagination fault. Add a tiebreaker such as the record identifier to the sort order before retesting.
Acceptance checks
Consider the fixture and pagination acceptable when:
- Each of the eight cases has a recorded result.
- A full walk after each change returns every surviving record exactly once, or the interface clearly says the list changed.
- Sort order is deterministic, including ties.
- The test compares identifiers, not totals.
- The fixture can be rerun from a clean state in one step.
Keep the matrix with the code, and extend it whenever a new sort or filter option is added.