Raml-mocker 是基于 Raml 的 mock server,Raml 是 RESTfull API 描述语言,同时支持自定义指令。raml-mocker 可以根据 raml 描述文档读取到 API 中的 uri 及 response 中的 example 继而生成 mock server。
git clone https://github.com/xbl/raml-mocker-starter.git raml-api
cd raml-api
git remote rm origin
yarn
# or
npm install
yarn start
# or
npm start
curl -i http://localhost:3000/api/v1/articles
# or
curl -i http://localhost:3000/api/v1/articles/bbb
yarn run build
# or
npm run build
此功能使用了raml2html。
{
"controller": "./controller",
"raml": "./raml",
"main": "api.raml",
"port": 3000,
"plugins": []
}
- controller: controller 目录路径,在高级篇中会有更详细说明
- raml: raml 文件目录
- main: raml 目录下的入口文件
- port: mock server 服务端口号
- plugins: 插件(可能会有变动)
raml-mocker 可以不写 js 代码生成Mock Server,只需要在response 添加 example:
/books:
/{id}:
post:
body:
application/json:
type: abc
responses:
200:
body:
application/json:
type: song
example: !include ./books_200.json
books_200.json
{
"code": 200,
"data": [
{
"id": 1,
"title": "books title",
"description": "books desccription1"
},
{
"id": 2,
"title": "books title",
"description": "books desccription2"
}
]
}
在 raml 文档中添加 (controller)
指令,即可添加动态的 Server,如:
/books:
type:
resourceList:
get:
description: 获取用户的书籍
(controller): user#getBook
responses:
200:
body:
type: song[]
example: !include ./books_200.json
在文档中 (controller)
表示 controller 目录下 user.js 中 getBook 函数。
controller/user.js
exports.getBook = (req, res, webApi) => {
console.log(webApi);
res.send('Hello World!');
}
Raml-mocker 是在 expressjs 基础上进行开发,req、res 可以参考 express 文档。
webApi 会返回文档中的配置:
{
"absoluteUri": "/api/:version/users/:user_id/books",
"method": "get",
"controller": "user#getBook",
"responses": [
{
"code": "200",
"body": "... example ...",
"mimeType": "application/json"
}
]
}
如此,raml-mocker 提供了更多可扩展空间,我们甚至可以在 controller 中实现一定的逻辑判断。
Raml-mocker 提供了插件机制,允许我们在不使用 controller
指令的时候对 response 的内容进行处理,例如使用Mockjs。
注意:插件的这种形式还没有想好,未来可能会有变动,即便有变动也会尽可能向下兼容。
.raml-config.json
{
"controller": "./controller",
"raml": "./raml",
"main": "api.raml",
"port": 3000,
"plugins": ["./plugins/mock.js"]
}
./plugins/mock.js
var { mock } = require('mockjs');
module.exports = (body) => {
try {
return mock(JSON.parse(body));
} catch(e) {}
return body;
}
在 1.1.0 中增加 API 测试,通过在 raml 文件中添加 response 数据的描述,来验证 response 的数据是否符合预期。
- 在 types 文件中编写商品 Type,描述了返回数据的类型,以及对象中字段验证:
Product:
type: object
properties:
productId:
type: string
minLength: 4
maxLength: 36
required: true
productName: string
description: string
price: number
- 在 API Raml 中添加 type 字段:
get:
description: 商品列表
queryParameters:
isStar:
description: 是否精选
type: boolean
required: false
example: true
responses:
200:
body:
# 这里描述的商品数组
type: Product[]
example: !include ./products_200.json
/{productId}:
get:
description: 商品详情
(controller): product#getProductDetail
(uriParameters):
productId:
description: productId
example: aaaa
responses:
200:
body:
# 这里描述的商品
type: Product
example: !include ./product_200.json
- 启动 Mock Server,并运行测试
# 启动 Mock Server
npm start
# 运行 API 测试
npm test
运行测试时默认会测试 Mock Server的 response,设置不同的环境方式如下:
编辑 .raml-config.json 文件
{
"controller": "./controller",
"raml": "./raml",
"main": "api.raml",
"port": 3000,
"runner": {
"local": "http://localhost:3000",
"dev": "http://abc.com:3001"
}
}
在 runner 添加不同的环境对应的 HOST,通过 SET NODE_ENV
来更改运行不同环境的测试。
cross-env NODE_ENV=dev raml-runner
# 为了方便已经在模板项目中添加了 npm script,可自由更改
npm run test:dev
以上只能满足不需要登录的 API 测试,登录的接口则需要 优先 执行,然后再执行其他接口,此处为了简单增加了(runner)
指令:
/login
post:
description: 登录
body:
username:
description: 用户名
type: string
required: true
example: abc
password:
description: 密码
type: string
required: true
example: abc
(runner):
after: ./runner/afterLogin.js
responses:
200:
body:
type: string
example: fdafda232432fdaxfda25dfa
解析 raml 文件会优先执行带有 (runner)
指令的接口,并在执行完成之后调用 after
对应的 js 文件。
afterLogin.js
module.exports = (axios, response) => {
axios.defaults.headers.common['Authorization'] = response.data;
}
测试发请求使用的 axios 模块,所以这里会在函数参数中添加 axios 实例,以及执行 login 接口的 response 对象。通常,设置 Header 就可以满足登录所需要的大部分场景。
- API 自动化测试
- 自动化增加前置条件,如:登录
- 测试数据导入
- Mock Server 增加请求参数验证
- 上传文件的处理
- baseUriParameters
- Proxy 代理
在1.1.0 以后 对原本的 raml 中 uri 动态参数有些调整:
# 1.1.0 以前
/products/:productId
# 1.1.0 以后
/products/{productId}
此调整不会 break 之前的功能,在使用API 测试的时候必须修改。