Apifox使用-接口调试

正文：

接口调试
前后置操作
响应和断言
环境和变量

接口调试

Apifox除了写接口文档以外，另一个重要的功能就是做接口调试相当于postman。

当新建了一个接口文档并保存了以后，文档的后面会出现三个页签：修改文档、运行、高级Mock

在运行这里我们就可以进行接口的调试了，当然对于这里而言，我们是先有了接口文档再进行接口调试，实际上我们还可以先进行接口调试然后将接口调试的结果保存为接口文档。在页面底部进行工作模式的切换

调试模式，即代码优先

Apifox 中调试模式 专门面向 Code First 模式。当后端开发完业务代码之后，可以在调试模式下快捷地测试接口，并在调试的过程中由 Apifox 自动生成接口文档。调试模式适合习惯于先行进行接口参数调试，再生成接口文档的团队。在调试模式下，开发者只需要编辑界面中接口参数，修改后即可直接发送请求，保存后生成文档

文档模式，即API优先

相对于调试模式，文档模式更强调设计接口的重要性。“文档模式”面向 Design First 模式。采用 Design First 模式的研发团队首先专注于定义和规划 API 的结构、功能和行为。Design First 方法强调 API 作为一个独立的组件来设计，这个组件需要在未来多个应用程序和服务之间适应。

在文档模式下，运行时会自动读取接口文档的信息，如：

接口路径、参数名会自动从 修改文档 读取，无需手动输入
参数值默认读取 修改文档 里的 示例值，也可手动修改，进行调试
填写好参数后，点击发送按钮即可运行。

保存为用例

Apifox还有一个重要的优点就是保存为用例

保存为用例 是将当前填写的参数保存起来，方便下次或者其他人用来调试接口。保存为用例后，接口用例 会显示在左侧树状菜单里接口的下一级（如图）。

一般而言，接口测试要考虑异常的场景，如：多参、少参、无参、空参、错误参数等，Apifox在保存为用例这里直接给出了一些接口测试用例的情况：成功、失败、记录不存在、数据为空、缺少参数、参数有误、已登录、未登录、没有权限、正常，除了Apifox自带的这些测试用例场景外，当然也可以自己设计接口测试用例。

发送后会出现控制台

暂存

文档模式下，还有一个要注意的点就是暂存

在已有参数的情况下，修改参数名、数据类型、参数说明，修改项左侧会有“黄色标记”，鼠标移动到“黄色标记”上时，会显示和接口文档的区别。

（1）您可以选择复原，和接口文档保持一致；

（2）可以选择保存到文档，将修改项同步到接口文档；

（3）也可以选择不操作，以当前修改项进行调试

快捷请求

有时候你得调试外部接口，这时你无需创建接口文档，直接发起快捷请求即可，快捷请求有三个入口：

这里有一个注意点：如果输入的 URL 未添加 http:// 或 https:// 作为起始参数，那么实际发出请求的时候将会自动加上当前环境中的前置 URL。

前后置操作

（1）前置操作

前置操作是在 API 请求之前执行的脚本代码，可以用于做以下事情：

设置 API header (请求头)
- 　　它们可用于设置请求的请求头、请求正文、验证请求参数和配置身份验证等
设置API参数
- 　　前置操作能够访问环境变量、全局变量和请求变量中的数据。前置操作也可以帮助请求者了解请求参数以及如何处理它们。
添加身份验证
- 　　例如基本身份验证或 OAuth。在发送 API 请求之前，前置操作可以被用来获取访问令牌或者其他权限，确保 API 请求发送的是有效的和合法的请求

变量替换

“变量替换”功能通常用于在发送 API 请求前，作用是把接口请求参数里的所有的已引用变量（包括动态值）替换成真实的请求内容。通常用于处理接口签名等转换场景。此时主要涉及以下两种场景：

通过脚本 set 变量

该场景下的操作需要放在“变量替换”之前运行，否则通过该脚本 set 的变量就不会对当前接口的请求参数生效。

接口签名脚本

该场景下的脚本需放在“变量替换”之后，这样脚本才能获取到该接口实际请求的参数值，否则获取到的参数值是变量替换之前的模板数据。

（2）后置操作

后置操作能够利用获取来自接口响应的数据，例如状态代码、header、body 等信息，进行二次处理

验证 API 响应的状态码和响应时间是否符合预期。
验证 API 响应的内容，如 JSON 或 XML 数据。
从 API 响应中提取数据，并将其用于后续请求。
自动提取响应中需要的数据

提取变量

“后置操作”支持添加“提取变量”功能，可以基于接口返回结果自动提取数据并设置为变量（临时变量/环境变量/全局变量），方便其它接口运行的时候直接使用

在“后置操作”页中添加“提取变量”

运行后在控制台查看提取的变量

（3）层级关系

前后置操作都可以在接口目录中设置父级操作。父级操作可以被继承到该目录下的所有接口中，适用于需要在多个接口中执行相同的前置操作的场景，例如鉴权，变量替换等

（4）数据库操作

1，在“前置操作“中引用数据库，修改文档中即可添加数据库操作

2，输入 SQL 命令，例如 SELECT * FROM user LIMIT 2

3，将查询结果提取到 3 个变量结果：allUser，user，userName

（5）脚本

Apifox 包含一个基于Javascript的脚本引擎，通过脚本（JavaScript代码片段）可实现在接口请求或集合测试时添加动态行为

使用后置脚本功能测试（断言）请求返回结果的正确性。
使用前置脚本动态修改接口请求参数，如增加接口签名参数等。
使用脚本操作变量并在接口请求之间传递数据。
脚本可以直接调用其他语言编写的程序，支持java(.jar)、python、php、js、BeanShell、go、shell、ruby、Lua 等语言编写的外部程序

前置脚本

前置脚本是在请求发送前执行的代码片段。例如要在请求头中包含时间戳或在 URL 参数中发送随机的字母、数字、字符串等数据。

你可以在接口的“前置操作” tab 页中添加前置脚本，发送接口请求前将自动运行前置脚本

示例：

例如要在请求头中包含当前时间戳，那么可以将函数返回值设置为环境变量。

将参数 timestamp 的值设置为 {{timestamp}} 。当请求发送时，前置脚本将被执行，环境变量 timestamp 的值会被设置为当前时间戳，同时 {{timestamp}}也会被替换为当前时间戳。

前置脚本使用 JavaScript 编写，语法与后置脚本完全相同，但不存在pm.response对象。

其他示例：

后置脚本

发送接口请求后执行的代码片段也称为后置脚本。主要用来断言请求返回的结果是否正确、将请求返回的结果数据写入环境变量等场景。

你可以在接口的“后置操作” tab 页中添加后置脚本，接口返回响应后将自动运行后置脚本

示例：

断言请求响应是否正确

// pm.response.to.have 示例
pm.test('返回结果状态码为 200', function() {
  pm.response.to.have.status(200);
});

// pm.expect() 示例
pm.test('当前为正式环境', function() {
  pm.expect(pm.environment.get('env')).to.equal('production');
});

// response assertions 示例
pm.test('返回结果没有错误', function() {
  pm.response.to.not.be.error;
  pm.response.to.have.jsonBody('');
  pm.response.to.not.have.jsonBody('error');
});

// pm.response.to.be* 示例
pm.test('返回结果没有错', function() {
  // assert that the status code is 200
  pm.response.to.be.ok; // info, success, redirection, clientError,  serverError, are other variants
  // assert that the response has a valid JSON body
  pm.response.to.be.withBody;
  pm.response.to.be.json; // this assertion also checks if a body  exists, so the above check is not needed
});

将接口响应数据写入至环境变量

// 获取 JSON 格式的请求返回数据
var jsonData = pm.response.json();

// 将 jsonData.token 的值写入环境变量
pm.environment.set('token', jsonData.token);

其他示例：

全局脚本/分组脚本

支持全局设置（在根目录里设置）前置操作、后置操作，设置后项目里的所有接口运行时都会生效。
支持分组里设置前置操作、后置操作，设置后分组里的所有接口运行时都会生效。

接口请求的执行流程如下：

[全局前置脚本] -> [分组前置脚本] -> [接口前置脚本] -> [发送接口请求] -> [返回接口结果] -> [全局后置脚本] -> [分组后置脚本] -> [接口后置脚本]

公共脚本

公共脚本主要用途是实现脚本复用，避免在多个地方重复编写相同功能的脚本。

你可以将频繁被引用的脚本或通用的类与方法编写至公共脚本中，然后在接口中直接引用。

创建公共脚本

使用公共脚本

点击接口中的“前置操作”或“后置操作”页，在此处引用公共脚本。发起接口请求时将优先运行公共脚本；公共脚本的运行顺序与添加顺序保持一致

注意事项：

脚本之间是可以实现相互调用，以下是具体的使用场景：

普通脚本使用纯函数通过 return 返回的方式调用公共脚本，不建议使用 pm.sendRequest 和 pm.environments.set 方法。
公共脚本之间支持相互调用。

为了避免脚本之间的变量冲突，所有脚本执行的时候都是在各自的作用域（通过闭包包裹）下运行。

若使用var、let、const、function 声明的变量或者方法，那么归属于局部变量或局部方法，无法被其他脚本调用的。如果想要使得变量或方法被其他脚本调用，需要将脚本改成全局变量或全局方法。

请确保不同脚本之间全局变量或者全局方法命名间没有冲突。
调用脚本需要注意脚本执行顺序，只有后置的脚本可以调用先执行的脚本。

脚本调试

调试脚本可以在前置脚本和后置脚本里编写，使用console.log('hello')方式将调试信息写入控制台，打开控制台即可查看

响应和断言

校验响应

校验响应以 接口文档-修改文档 页面内填写的 返回响应 作为判断标准，与 请求接口 的获得的返回值进行对比。不需要人工核对，提高效率和准确性

（1）校验响应 的校验范围：

接口返回的 HTTP 状态码
返回内容的数据格式：JSON、XML、HTML、Raw、Binary
数据结构：仅JSON、XML可配置数据结构

（2）如果上述 2 者一致，则显示 ”返回数据结构校验通过!“

（3）当不一致时，就会报错并提示具体是哪部分不一致。此时你可以选择修改 接口文档-修改文档 内的 返回响应 ；也可以通知后端同学修改后端代码

（4）校验响应 开关默认打开。可以在界面项目设置-通用设置-功能设置-高级设置 关闭全局开关，注意：全局开关只会对 接口文档-运行 生效，不会对已保存的 接口用例 生效

断言

“后置操作”支持添加断言，你可以对接口返回的数据或响应时间设置断言，以判断当前接口返回是否符合预期

（1）设置断言

打开 Apifox 中的某条接口，在“后置操作”页中设置断言。例如输入 $.data.status。还可以添加多个断言。

提示：根对象使用 $ 符号进行表示，而无需区分是对象还是数组。

（2）查看结果

运行后即可查看断言结果

环境和变量

环境管理

项目往往有不同的环境，如开发环境、测试环境、生产环境等，如果环境发生变动时，频繁地修改接口地址中的前缀 URL 及反复配置参数对于接口调试工作而言十分繁琐。而环境管理正是管理着不同的“前置 URL”与“接口参数值”

环境管理

Apifox 默认提供正式环境、开发环境、测试环境、本地 Mock 与云端 Mock。每个环境中包含服务（前置 URL）、环境变量、参数三项可配置项。

前置URL

发起接口请求时，前置 URL 将自动添加至接口路径前并组合成接口的最终请求的 URL。

例如在正式环境中设置的前置 URL 为 https://www.api.com，接口路径为 /pets/123，那么实际发送的接口请求 URL 将被自动组合为： https://www.api.com/pets/123。

注意点：

前置 URL 末尾建议不要加上斜杠 /，设计接口时建议在接口路径中以斜杠 / 起始。
如果接口路径本身就以http://或https://起始，实际发出请求时将自动过滤前置 URL 值。因此不建议在接口路径中手动写入前缀 URL。
不建议在同一个环境中添加多条前置 URL。
自动化脚本可通过 pm.request.getBaseUrl() 获取当前运行环境选择的的 前置 URL。

环境变量使用示例：

在“测试环境”中添加一个名为my_variable的变量，并将本地值设置值为hello后点击保存。a

在某个接口中的参数值内输入 {{my_variable}}，并选择以测试环境。点击“发送”按钮后，系统会自动将 {{my_variable}} 替换为 hello 后发送接口请求。

注意点：

系统内置名为BASE_URL的特殊环境变量，其值为当前环境的前置 URL，使用方式{{BASE_URL}}。
如用户手动添加了名为BASE_URL的环境变量，则会覆盖掉系统内置BASE_URL的值。
自动化脚本可通过 pm.environment.get('BASE_URL') 方式读取前置 URL。
脚本不能修改前置 URL，脚本 pm.environment.set('BASE_URL','xxx')会生成一个真正的名为BASE_URL的环境变量，而不会修改前置 URL。
Apifox 版本号大于等于 1.0.12 才支持内置BASE_URL。

环境变量/全局变量/临时变量

变量类型

环境变量
全局变量
临时变量

环境变量

环境变量是最常用的变量类型。同一个变量可以在不同的环境设置不同的值，变量值会跟随环境切换而改变。

全局变量

全局变量中的数值不会随着环境切换而改变，在环境管理页中的左上方进行设置。

临时变量

临时变量仅在单次运行接口用例或测试管理里的测试用例或测试套件过程中有效，不会持久保存至系统。

使用变量

所有类型的变量都是通过双大括号的方式，如{{token}}。

变量一经定义，在接口运行 tab、接口用例、快捷调试、集合测试的所有参数值、前置/后置脚本等各功能页中都可以使用该变量。环境中的额外参数也同样可以使用变量。

Body参数

请求 Body 为 json 或者 raw 格式的，也可以直接使用变量、动态变量，使用方式如下：

{
    "field1": "{{stringVariable}}",
    "field2": {{intVariable}},
    "field3": {{arrayVariable}},
    "field4": {{objectVariable}},
    "field5": {{$timestamp}}
}

注意事项：

json 格式里 string 类型的值，使用变量的时候需要加上双引用；其他类型的值不要加双引号，如上面例子所示。
如果以没有加双引号的方式使用了变量，请不要使用格式化功能，如有提示 JSON 格式不正确，直接忽略即可。

其他变量

若变量的值为对象或数组形式，可以通过{{variableName.attributeName}}或{{variableName[0].attributeName}}方式读取变量里的属性值，示例：

变量user的值为如下格式对象：

接口参数中以{{user.name}}方式引用user对象里的name属性值。
自定义代码中以pm.variables.get("user.name")方式引用user对象里的name属性值。

{
  "id": 1,
  "name": "jack"
}

变量user的值为如下格式数组

接口参数中以{{user[0].name}}方式引用user数组里第一个对象里的name属性值。
自定义代码中以pm.variables.get("user[0].name")方式引用user数组里第一个对象里的name属性值。

[
  {
    "id": 1,
    "name": "jack"
  }
]

如上所示，读取变量（对象或数组）里的属性值写法{{user.name}}遵循JSON Path语法规范，只需将JSON Path里的$符号替换为变量名既可

变量优先级

所有变量都是通过双大括号的方式引用，当不同类型变量存在相同名称的变量时，系统会根据优先级决定使用哪个类型的变量。

变量优先级：

临时变量 > 测试数据变量 > 环境变量 > 全局变量

本地值和远程值

环境变量存在本地值和远程值的差异。所有使用到变量的地方，实际运行的时候优先读写“本地值”，而不会读写“远程值”。“本地值” 仅存放在本地，不会同步到云端，团队成员之间也不会相互同步，适合存放 token、账号密码等敏感数据。

在远程值中填写的数据将保存至远端服务器中，主要用于团队间共享数据值

注意事项：

由于本地值仅存放在本地，使用一些清理软件清理 Apifox 文件缓存会导致本地值被清空，请务必注意

通过脚本调用变量

环境变量

// 设置环境变量
pm.environment.set('variable_key', 'variable_value');

// 获取环境变量
var variable_key = pm.environment.get('variable_key');

// unset 环境变量
pm.environment.unset('variable_key');

环境变量支持数组、对象、字符串等形式存储，你可以参考以下代码将对象或数组（非字符串）写入环境变量

var array = [1, 2, 3, 4];
pm.environment.set('array', JSON.stringify(array));

var obj = { a: [1, 2, 3, 4], b: { c: 'val' } };
pm.environment.set('obj', JSON.stringify(obj));

读取的时候，需要使用 JSON.parse 逆转换。

try {
  var array = JSON.parse(pm.environment.get('array'));
  var obj = JSON.parse(pm.environment.get('obj'));
} catch (e) {
  // 处理异常
}

全局变量

// 设置全局变量
pm.globals.set('variable_key', 'variable_value');

// 获取全局变量
var variable_key = pm.globals.get('variable_key');

// unset 全局变量
pm.globals.unset('variable_key');

临时变量

// 设置临时变量
pm.variables.set('variable_key', 'variable_value');

// 获取临时变量
var variable_key = pm.variables.get('variable_key');

// unset 临时变量
pm.variables.unset('variable_key');

动态值

动态变量是在接口运行中，参数的值按照指定定义好的系统规则自动生成的变量，常用于测试模拟环境。

动态值中支持添加变量、常量、动态变量、自定义表达式等多种类型参数。

添加动态变量