分页 Bug 很少在第一页就暴露。它通常发生在两次请求之间插入了一条记录，然后消费者悄悄漏掉一条审计事件。

为什么需要这个 Skill

API 分页测试用于检查消费者遍历变化中的集合时，是否会漏项、重复或产生超出契约的不稳定排序。

Skill 用来做什么

当团队需要围绕“页大小、游标或 offset 语义、稳定排序、数据变化、重复、漏项和终止”工作时，使用 API 分页测试 Skill。

Awesome QA Skills 按语言和测试阶段组织 Skill。系列总览 解释通用安装方式，本文只聚焦 API 分页测试。

它适合这些场景：团队需要重复检查页大小、游标或 offset 语义、稳定排序、数据变化、重复、漏项和终止；多个证据来源互相矛盾；交接时必须说明哪些内容仍未验证。

结果至少要把页大小、游标或 offset 语义、稳定排序、数据变化、重复、漏项和终止接回来源和验证动作。设计清单不能直接写成通过结论。

它不做什么

API 分页测试 Skill 可以组织遍历结果的材料、证据和下一步动作，但它不能替代：

  • 业务或领域负责人对规则、范围和风险的确认。
  • 真实环境、账号、数据、日志或运行结果；静态分析不会自动升级为运行证据。
  • 发布、合规、生产操作和残余风险接受等授权决定。
  • 在输入相互冲突时替团队选择一个未经确认的事实。

它主要检查哪些内容

这个 Skill 的价值不在于把关键词再列一遍，而在于把每个关注点接到可观察的输入、判断和收口动作。先用源 Skill 已定义的输出字段整理一张小矩阵：

检查关注点开始前要问结果应留下什么
遍历结果完整、无重复且有序的记录集合观察到的 ID 与预期 ID
分页发现漏项、重复、游标无效、排序不稳或总数错误页码与变化时点
消费者动作重试、使用快照、更换游标或澄清契约负责人和证据

如果某一行只有经验判断、没有来源或验证方法，就把它留在待确认项里，不要提前写成通过。

开始之前先审计输入

围绕“遍历结果”开始分析时，先把输入分成六种状态。缺口不会自动变成失败，但也不能被隐藏在结论里。

状态含义本 Skill 的处理方式
known材料直接证明的事实标出来源、版本和时间，允许进入判断
missing本轮需要但尚未提供的材料列出最小补证动作，结论保持受限
conflicting来源之间互相矛盾并列来源和冲突点，交给负责人裁决
stale材料存在但版本或时间已经过期标出新鲜度，不把旧结论当当前事实
out_of_scope有关但不在本轮范围内明确排除，避免分析悄悄扩大
assumptions为继续分析而暂时采用的假设写出验证方式和失效条件

至少把输入版本、范围、环境、证据位置和负责人放在一起。没有运行记录时，只能交付分析、设计或验证计划，不能写执行通过。

从问题到结构化发现

先把来源、范围、证据状态、分析判断、责任角色、动作、关闭条件和验证方式连起来，再写结论。下面的案例保留这个 Skill 的专属编号和领域语境。

分层写法

围绕遍历结果，不要把四种语气揉成一句“建议通过”：

层次写法本文应用
事实材料直接显示了什么引用来源中的重点、版本、输入或运行记录
基于证据的推断多个事实共同支持的判断说明推断链，并保留不确定性
建议下一步最小动作是什么指定补证、复核、执行或回归路径
人工决策谁需要决定什么由负责人确认范围、风险接受、资源和发布含义

一个完整案例

本节按输入、分析、发现、决策和验证展开；材料不足时保留 missing、conflicting 或 assumptions，不把它们改写成通过。

输入

材料这次提供什么缺失时怎么处理
集合契约排序键、游标或 offset 规则、页大小限制和快照语义不要假设 offset 自动代表快照
变化计划分页请求之间的插入、更新、删除、归档和重复键事件记录准确时间
遍历证据已看到的 ID、返回游标、总数和结束标志与权威测试夹具比较

可以这样调用：


请使用 api-pagination-testing Skill。

任务：在新事件持续写入、旧事件不断归档时遍历审计日志 API
输入材料：[需求、版本、链接、日志、报告或数据路径]
范围：[本次包含和排除的对象]
未知项：[缺失的环境、账号、数据或权限]
期望输出：[按风险排序的发现、证据状态和下一步动作]

先审计输入。分开写事实、假设和待确认问题。没有运行记录时不要声称已经执行。

分析

先从一个边界清楚的小回合开始：在新事件持续写入、旧事件不断归档时遍历审计日志 API。以每页 50 条读取审计事件，在第一页之后插入两条新事件，再使用返回游标继续读取。把收集到的 ID 与按时间戳和 ID 排序的测试夹具比较。正确的游标可以让新事件不进入本轮遍历，但不能重复或漏掉原集合。

交接产物要同时保留输入版本、时间窗口、证据索引、负责人和下一次验证动作。Skill 可以整理不确定性，不能制造缺失的产物。

发现

示例发现：把一次问题写成可交接动作

下面的字段示例只展示记录方式，不代表真实环境已经执行。

假设当前材料无法证明“遍历结果”已经满足要求，发现可以这样写。它既不替团队补写规则，也不把缺失证据伪装成失败。

字段示例写法
来源与范围记录本轮使用的需求、版本、环境和遍历结果的具体对象
发现遍历结果的判断条件或结果仍缺少可追溯依据
证据状态missing / assumptions；如果来源相互矛盾则改为 conflicting
影响与优先级说明会影响哪个用户、链路或交付决定，不凭感觉扩大等级
负责人和人工决策由业务、开发、安全或测试负责人确认规则和风险取舍
动作与关闭条件补齐最小证据；关闭条件是来源、判断和责任人都能复核
验证指定一次可重复的检查、查询或运行，并保存原始产物

这类记录的重点是让下一位同事能从发现回到来源，再执行一项能改变结论的动作。

决策

责任角色和待决策问题应由对应负责人确认；Skill 不替他们做风险取舍。

验证

关闭前按发现中的验证方式执行，并保留原始产物；没有执行记录时，状态仍然保持未验证。

发现如何进入下一阶段

交接产物

输出字段它要回答什么示例状态
遍历结果完整、无重复且有序的记录集合观察到的 ID 与预期 ID
分页发现漏项、重复、游标无效、排序不稳或总数错误页码与变化时点
消费者动作重试、使用快照、更换游标或澄清契约负责人和证据

没有运行记录、查询结果或原始产物时，不要写“已通过”。好的分页测试会在 API 允许数据变化时把集合当成移动目标。它记录 ID 而不是盲信总数，并明确排序键。

下一步路由

至少交付来源、证据状态、负责人、关闭条件和验证动作；下一阶段的结论仍受证据状态约束。

怎样准备更好的输入

如果第一次调用只有一行目标，输出就应该保持受限。补充来源版本、受影响对象、环境、已知缺陷和决策负责人，才能从“看起来完整的清单”推进到可用评审。

和其他 Skill 怎么配合

容易踩的坑

  1. 只断言每页数量。
  2. 把变化中的总数当成完整性证明。
  3. 不在分页请求之间改变集合就测试游标。

安装与调用

全局安装这个 Skill：


npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/api-pagination-testing -g

安装后使用 api-pagination-testing Skill，并附上真实项目材料。

常见问题

offset 分页一定是错误的吗？

不一定。如果有明确快照或稳定排序，它可以成立；测试要验证真实契约。

最后返回空页代表什么？

必须明确是集合结束、游标无效还是临时读取问题，因为客户端动作不同。

参考

源 Skill 与执行契约

完整执行契约位于 API 分页测试 提示词。调用 Skill 前先阅读它；提示词定义了详细流程和输出契约。源目录 中还包含入口文件以及实际存在的配套资料。

入口文件重点约束页大小、游标或 offset 语义、稳定排序、数据变化、重复、漏项和终止。写结论前先阅读配套提示词，并保留这个 Skill 的决策边界。

参考链接

安全测试白盒测试背靠背测试本地化测试边界测试
分享