Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

matman

5.0.7 • Public • Published

matman

matman 端对端测试方案中的核心操作库,更多资料请参考: matman 官方文档

1. 安装

$ npm install matman --save

2. API

2.1 MatmanConfig 类

matman 方案中的配置文件,默认由项目中的 matman.config.js 提供。

2.1.1 constructor(rootPath, opts)

  • rootPath: String, 项目的根目录,必填项
  • opts: 额外参数,一般情况下是由项目中的 matman.config.js 来定义,详见 MatmanConfig 类的字段说明

MatmanConfig 类的字段如下:

字段名 类型 默认值 说明
rootPath String matman 项目的根目录,一般情况是 matman.config.js 的目录
caseModulesPath String path.resolve(rootPath, './case_modules') 测试案例的根目录
crawlerBuildPath String path.resolve(rootPath, './build/crawler-script') 前端爬虫脚本构建之后的目录
crawlerMatch RegExp /[\/|\\]crawlers[\/|\\].*\.js$/ 用于匹配是否为前端爬虫脚本的正则表达式,默认识别 crawlers 文件夹下的js
crawlerInjectJQuery Boolean true 前端爬虫脚本中是否注入jQuery
screenshotPath String path.resolve(rootPath, './build/screenshot_output') 屏幕截图保存的路径
coveragePath String path.resolve(rootPath, './build/coverage_output') 测试覆盖率文件保存的路径
matmanResultPath String path.resolve(rootPath, './build/matman_result_output') MatmanResult 执行结果数据保存的路径
isDevBuild Boolean false 是否为开发模式,若值为 true,则构建之后的前端爬虫脚本可用于代码调试

注意,必须要满足以下条件,否则会直接报错:

  • rootPath 必须真实存在
  • caseModulesPath 必须真实存在

2.2 createPageDriver(caseModuleFilePath, opts)

创建 PageDriver 对象。

  • caseModuleFilePath: String, 测试案例文件的绝对路径
  • opts: 额外参数,传递给 MatmanConfigPageDriver 使用

2.3 PageDriver 类

页面控制器。

2.3.1 constructor(matmanConfig, caseModuleFilePath, opts)

  • matmanConfig: MatmanConfig, 必填项
  • caseModuleFilePath: String, 测试案例文件的绝对路径,必填项
  • opts: 额外参数
    • opts.doNotCloseBrowser: Boolean, 是否在执行完成之后不要关闭浏览器,默认为 false
    • opts.useRecorder: Boolean, 是否使用记录器,若为 true,则在结果中会返回网络请求和浏览器事件等额外信息,默认为 false
    • opts.tag: String, 标记,在某些场景下使用,例如截图保存文件中追加该标记,用于做区分

2.3.2 useNightmare(nightmareConfig)

支持链式调用。

使用 nightmare.js 框架来做端对端测试。

2.3.3 useProxyServer(proxyServer)

支持链式调用。

走指定的代理服务,由代理服务配置请求加载本地项目,从而达到同源测试的目的;若不配置,则之前请求现网,亦可直接测试现网的服务。

  • proxyServer: String, 代理服务器,格式为 my_proxy_server.example.com:8080,例如 127.0.0.1:8899

2.3.4 useMockstar(mockstarQuery)

支持链式调用。

使用 mockstar 来做桩数据(假数据,mock 数据)。

  • mockstarQuery: MockStarQuery,mockstar 方案中用于指定桩数据的请求对象

2.3.5 setCookies(cookies)

支持链式调用。

注入 cookie。相关内容可以阅读 nightmare-handler exCookies

cookiesString ,即格式与 document.cookie 输出形式一直,例如 mykey1=myvalue1; mykey2=myvalue2

cookiesObject 时,可以支持多个 cookie 键值对,例如 {mykey1:'myvalue1', mykey2:'myvalue'}

2.3.6 setDeviceConfig(deviceConfig)

支持链式调用。

设置无头浏览器设备参数。相关内容可以阅读 nightmare-handler exDevice

deviceConfigString ,即为指定用哪种预定义的设备名字,默认值为 mobile

deviceConfigObject 时:

  • deviceConfig.name: String, 设备名字
  • deviceConfig.UA: String, 是userAgent
  • deviceConfig.width: Number, 视窗宽度
  • deviceConfig.height: Number, 视窗高度,注意这里不是指页面的高度,页面高度要小于这个值

2.3.7 setScreenshotConfig(screenshotConfig)

支持链式调用。

设置截屏参数。相关内容可以阅读 nightmare#screenshotpath-clip

screenshotConfigBoolean ,且为 true 时,则将根据当前路径自动生成截图文件路径,推荐用该方式。

screenshotConfigString ,即为截图保存的文件路径,绝对路径,例如 /root/xyz.png

screenshotConfigObject 时:

  • screenshotConfig.path: String, 截图保存的文件路径,绝对路径,例如 /root/xyz.png,如果不填写,则将根据当前路径自动生成截图文件路径
  • screenshotConfig.clip: String, 截图的区域,例如 { x: 0, y: 0, width: 0, height: 0 }
  • screenshotConfig.tag: String, 标记,会追加到 screenshotConfig.path 中,用作自定义的区分

2.3.8 setCoverageConfig(coverageConfig)

支持链式调用。

设置覆盖率参数。

coverageConfigBoolean ,且为 true 时,则将根据当前路径自动生成覆盖率文件路径,推荐用该方式。

coverageConfigString ,即为覆盖率文件路径,绝对路径,例如 /root/xyz.json

coverageConfigObject 时:

  • coverageConfig.path: String, 覆盖率文件路径,绝对路径,例如 /root/xyz.json,如果不填写,则将根据当前路径自动生成覆盖率文件路径
  • coverageConfig.tag: String, 标记,会追加到 coverageConfig.path 中,用作自定义的区分

2.3.9 setMatmanResultConfig(matmanResultConfig)

支持链式调用。

设置 MatmanResult 执行结果参数。

matmanResultConfigBoolean ,且为 true 时,则将根据当前路径自动生成 MatmanResult 执行结果文件路径,推荐用该方式。

matmanResultConfigString ,即为 MatmanResult 执行结果路径,绝对路径,例如 /root/xyz.json

matmanResultConfigObject 时:

  • matmanResultConfig.path: StringMatmanResult 执行结果文件路径,绝对路径,例如 /root/xyz.json,如果不填写,则将根据当前路径自动生成 MatmanResult 执行结果
  • matmanResultConfig.tag: String, 标记,会追加到 matmanResultConfig.path 中,用作自定义的区分

2.3.10 goto(pageUrl)

支持链式调用。

加载指定的页面地址。

  • pageUrl: String,页面的 url 地址

2.3.11 addAction(actionName, actionCall)

支持链式调用。

增加测试动作集。

  • actionName: String,动作名称,后续可通过它来获得最后的数据
  • actionCall: Function,执行函数,入参中接受一个 nightmare 对象,可以直接操作使用 nightmare Interact with the Page 的方法

以下代码来自: demo_02 :

const matman = require('matman');
 
matman
    // 创建 PageDriver,页面驱动控制器
    .createPageDriver(__filename, opts)
 
    // 无头浏览器使用 nightmare.js 框架提供,其底层用的是 Google 的 electron,基于 chromium 内核
    .useNightmare({ show: opts.show })
 
    // 其他操作,省略
    // ....
 
    // 加载页面地址
    .goto('https://www.baidu.com')
 
    // 第一步:开始操作之前
    .addAction('init', function (nightmareRun) {
        // nightmareRun 支持所有的原始 nightmare 语法和对其定制的扩展功能
        return nightmareRun.wait(500);
    })
 
    // 第二步:搜索输入框输入: matman
    .addAction('input_key_word', function (nightmareRun) {
        // nightmareRun 支持所有的原始 nightmare 语法和对其定制的扩展功能
        return nightmareRun.type('#kw', 'matman').wait(500);
    })
 
    // 第三步:点击搜索按钮,获得搜索结果
    .addAction('click_to_search', function (nightmareRun) {
        return nightmareRun.click('#su').wait('#content_left');
    })
 
    //  其他操作,省略
    // ....
 
    // 结束,获取结果
    .end();

2.3.12 wait(fn, ...args)

支持链式调用。

需要等待某些条件达成,才开始运行爬虫脚本,与 nightmare 的 wait 含义和用法一致。

2.3.13 evaluate(fn, ...args)

支持链式调用。

执行爬虫脚本或者方法。

fnString 时,即代表的是加载本地的爬虫脚本文件,支持绝对路径和相对路径,如果是相对路径,则其相对于当前文件而言,可以等效于 require 的语法。 特别注意的是,本地的爬虫脚本文件,是通过 matman build 命令构建产生的,因此该场景下一定要先提前构建出本地的爬虫脚本文件,否则会出错

fnFunction 时,则与 nightmare 的 evaluate 含义和用法一致,详见 nightmare .evaluate(fn[, arg1, arg2,...])

2.3.14 executeCustomFn(customFn)

支持链式调用。

执行自定义的方法,适用于 debug 和自定义扩展等场景。

  • customFn: Function,入参中接受一个 PageDriver 对象
const matman = require('matman');
 
matman 
    //  其他操作,省略
    // ....
 
    // 执行自定义的方法
    .executeCustomFn((pageDriver) => {
        // 没有其他的意义,只是为了 debug
        if (opts.show) {
            console.log(pageDriver);
        }
    })
 
    //  其他操作,省略
    // ....

2.3.15 end()

启动 PageDriver ,返回一个 Promise ,结果值为 MatmanResult 对象。

2.4 MatmanResult 类

2.4.1 constructor(result)

  • data: Array | Object,数据快照,如果使用 addAction(actionName, actionCall) 追加的测试动作,则该值为数组,可以通过 get(actionName) 获得指定动作的数据
  • globalInfo: Object,网络请求和浏览器事件等全局信息

2.4.2 get(actionName)

通过测试动作名字获得数据。

actionNameString 时,则该名字来自 addAction(actionName, actionCall) 定义的名字。

actionNameNumber 时,则其相对于数组索引,会从 matmanResult.data 这个数组中获取。

2.4.3 getQueue(globalInfoRecorderKey = 'recorder')

获得捕获到的请求队列。返回一个数组,数组元素为网络请求和浏览器事件等信息。

2.4.4 getNetwork(resourceType)

从结果队列中过滤出网络请求。

resourceType 详见 nightmare-handler RESOURCE_TYPE ,即:

const RESOURCE_TYPE = {
    MAIN_FRAME: 'mainFrame',
    SUB_FRAME: 'subFrame',
    STYLESHEET: 'stylesheet',
    SCRIPT: 'script',
    IMAGE: 'image',
    OBJECT: 'object',
    XHR: 'xhr',
    OTHER: 'other'
};

2.4.5 isExistInNetwork(partialURL, query = {}, resourceType, status)

根据条件,从网络请求中匹配指定的请求。

  • partialURL: String,用于匹配的部分url
  • query: Object,请求携带的 query 参数
  • resourceType: String,资源类型
  • status: Number,http 状态码

2.4.6 isExistPage(partialURL, query = {}, status)

根据条件,从网络请求中匹配指定的请求,等效于 isExistInNetwork(partialURL, query, 'mainFrame', status)

使用场景:

  • 测试跳转页面的场景,通过它可以判断是否加载了目标的页面

2.4.7 isExistXHR(partialURL, query = {}, status)

根据条件,从网络请求中匹配指定的请求,等效于 isExistInNetwork(partialURL, query, 'xhr', status)

使用场景:

  • 测试接口请求是否正确,可以利用 query 来指定请求参数,确保不会发送一个错误的请求
  • 利用 status 可以验证接口是否可能 500
  • 有些数据上报也是用 xhr 的,可以测试数据上报的字段是否正确

2.4.8 isExistImage(partialURL, query = {}, status)

根据条件,从网络请求中匹配指定的请求,等效于 isExistInNetwork(partialURL, query, 'image', status)

使用场景:

  • 测试是否加载了某张图片
  • 利用 status 可以验证图片请求是否有可能 404

2.4.9 isExistStylesheet(partialURL, query = {}, status)

根据条件,从网络请求中匹配指定的请求,等效于 isExistInNetwork(partialURL, query, 'stylesheet', status)

使用场景:

  • 测试是否加载了 css 文件
  • 利用 status 可以验证 css 文件是否有可能 404

2.4.10 isExistScript(partialURL, query = {}, status)

根据条件,从网络请求中匹配指定的请求,等效于 isExistInNetwork(partialURL, query, 'script', status)

使用场景:

  • 测试是否加载了 js 文件
  • 利用 status 可以验证 js 文件是否有可能 404

2.4.11 isExistJSBridge(partialURL, query = {})

是否存在某个 jsbridge 的调用,支持使用 iframe 和 location.href 两种形式,具体可以查看 https://github.com/matmanjs/matman-demo/tree/master/DevOps/matman-app/case_modules/page-hybrid-app。

Install

npm i [email protected]

Version

5.0.7

License

MIT

Unpacked Size

97.6 kB

Total Files

19

Last publish

Collaborators

  • avatar