1 | # matman
|
2 |
|
3 | [matman](https://github.com/matmanjs/matman) 端对端测试方案中的核心操作库。
|
4 |
|
5 | ## 1. 安装
|
6 |
|
7 | ```
|
8 | $ npm install matman --save
|
9 | ```
|
10 |
|
11 | ## 2. API
|
12 |
|
13 | ### 2.1 CaseParser 类
|
14 |
|
15 | 测试用例处理类。每一个测试用例都是一个 CaseParser 对象。
|
16 |
|
17 | #### 2.1.1 constructor(rootPath, opts)
|
18 |
|
19 | - `rootPath`: `String`, 测试用例的脚本目录,必填项
|
20 | - `opts`: 额外参数
|
21 |
|
22 | #### 2.1.2 getCrawlerScriptPath(relativePath)
|
23 |
|
24 | 获得构建之后的爬虫脚本文件的绝对路径路径。
|
25 |
|
26 | `relativePath` 是一个相对路径,而返回的是该文件的绝对路径。在确定 `relativePath` 值时,可以参考 CommonJS 规范中的 `require` 方法。
|
27 |
|
28 | ```javascript
|
29 |
|
30 | const { CaseParser } = require('matman');
|
31 | const caseParser = new CaseParser(__dirname);
|
32 |
|
33 | // 获取 crawlerScript 爬虫脚本路径,返回构建之后文件的绝对路径,例如: /user/xxx/yyy/crawlers/get-page-info
|
34 | const crawlerScriptPath = caseParser.getCrawlerScriptPath('../../crawlers/get-page-info');
|
35 |
|
36 | ```
|
37 |
|
38 | #### 2.1.3 handleOperate(pageUrl, crawlerScriptPath, opts = {}, callAction)
|
39 |
|
40 | 模拟用户进行交互操作。
|
41 |
|
42 | 请求参数:
|
43 |
|
44 | - `pageUrl`:`String`,必填,页面的 URL 地址
|
45 | - `crawlerScriptPath`:`String`,必填,运行在浏览器中的前端爬虫脚本的绝对路径,建议使用 `getCrawlerScriptPath(relativePath)` 方法来动态获取
|
46 | - `opts`:`Object`,额外参数
|
47 | - `opts.show`:`Boolean`,运行时的无头浏览器是否需要可见,默认为 `false`,即隐藏在后台运行
|
48 | - `opts.proxyServer`:`String`,代理服务器,例如 `127.0.0.1:8899`,或者 `my_proxy_server.example.com:8080` ,会直接透传给 [nightmare 的 switches 配置项](https://github.com/segmentio/nightmare#switches) 中的 `proxy-server` 字段
|
49 | - `opts.wait`:`String | Number`,wait 配置,会直接透传给 [nightmare 的 wait 配置项](https://github.com/segmentio/nightmare#waitms)
|
50 | - `opts.doNotEnd`:`Boolean`,是否在执行完成之后不要关闭浏览器,默认为 `false`
|
51 | - `opts.cookie`:`String`,为浏览器注入cookie,格式与 `document.cookie` 一致
|
52 | - `opts.mockstarQuery`:`Object`,指定 mockstar 的query参数,用于数据打桩,为 [mockstar](https://www.npmjs.com/package/mockstar) 中的 `MockStarQuery` 对象
|
53 | - `opts.screenshot`:`String | Boolean | Object`,截图设置,如果是 `Object` 值,则需要包含 `path` 和 `clip` 两个属性,处理之后会直接透传给 [nightmare 的 screenshot 配置项](https://github.com/segmentio/nightmare#screenshotpath-clip)
|
54 | - `opts.device`:`String | Object`,设备设置,如果是 `Object` 值,则需要包含 `name`、 `UA`、 `width` 和 `height` 两个属性,处理之后会直接透传给 [nightmare-handler 的 exDevice 配置项](https://github.com/helinjiang/nightmare-handler/blob/HEAD/docs/exDevice.md)
|
55 | - `opts.tag`:`String`,特定标记,例如两个 test 脚本都使用同一个行为脚本,那么如果定义了 `tag`,则截图命名中会将其加入其中,避免覆盖,特别的,如果传入 `__dirname` ,我们将自动获取当前文件名,可以简化使用
|
56 | - `callAction`:`Function`,定义用户交互行为的函数,接受一个 `BaseHandle` 对象参数
|
57 |
|
58 | 返回一个 `Promise`, `resolve` 返回的值为 `CaseParserOperateResult` 对象,除了包含了 `{data: Array, _dataIndexMap:Object, globalInfo: Object}` ,同时提供了以下方法:
|
59 |
|
60 | - `get(key)` ,获得指定自定义行为名字的数据结果
|
61 | - `getQueue()`,获得所有的事件结果
|
62 | - `getNetwork(resourceType)`,获得指定 `resourceType` 的网络请求列表,若 `resourceType` 为空,则返回所有。`resourceType` 目前支持八种:`mainFrame`、`subFrame`、`stylesheet`、`script`、`image`、`object`、`xhr`、`other`
|
63 | - `isExistInNetwork(partialURL, query, resourceType)`,从网络请求列表过滤出匹配的结果
|
64 | - `isExistPage(partialURL, query)`,从网络请求列表过滤出匹配的结果,且指定 `resourceType` 为 `mainFrame`
|
65 | - `isExistXHR(partialURL, query)`,从网络请求列表过滤出匹配的结果,且指定 `resourceType` 为 `xhr`
|
66 |
|
67 |
|
68 | #### 3.1.4 handleScan(pageUrl, crawlerScriptPath, opts, delayBeforeClose)
|
69 |
|
70 | 获取页面信息,适合无交互行为的场景。
|
71 |
|
72 | 请求参数和返回请参考 `handleOperate` 方法,也是返回一个 `Promise`, 但 `resolve` 返回的值结构为 `{data: Object, globalInfo: Object}` 。
|
73 |
|
74 | 另外定义了一个 `delayBeforeClose` 参数,该值会在 `opts.useRecorder` 为 `true` 时启用,用于延迟关闭窗口,以便能够完整收集一些异步请求信息。
|
75 |
|
76 | 它本质上是 `handleOperate` 的一个特殊场景,近似等效于:
|
77 |
|
78 | ```
|
79 | return this.handleOperate(pageUrl, crawlerScriptPath, opts, (testAction) => {
|
80 | // scan 行为是一种特殊的操作,因为它只有一个行为,且结果也不再是数组
|
81 | testAction.addAction(function (nightmareRun) {
|
82 | return nightmareRun.wait(opts.wait || 500);
|
83 | });
|
84 | })
|
85 | ```
|