| 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 | ```
|