yaomp v2.1.0

YAOMP

YST Automated operation media platform
version: 2.1.0

Installtion

  # yarn
  yarn add yaomp -S --registry=https://registry.npmjs.org/

  # npm
  npm i yaomp -S --registry=https://registry.npmjs.org/

Quick Start

Create Yaomp instance ｜ 创建Yaomp实例

• dialog.js

// 编写中间件
module.exports = async (ctx, next) => {
  ctx.page.printIn('log', 'Show Dialog');
  await ctx.page.evaluate(async () => {
    await new Promise(resolve => {
      alert('Dialog');
      resolve(1);
    })
  })
  ctx.page.printIn('log', 'Close Dialog');
  await next();
}

• index.js

const { Yaomp, Browser } = require('yaomp');
const showDialog = require('./dialog');
const app = new Yaomp();

async function main() {
  const page = await app.init(
    Browser.create({
      // 创建浏览器配置
      // Create browser configuration
      headless: false,
      defaultViewport: null
    })
  );


  // 使用中间件
  // use middlewares
  // 编写中间件
  app
    .use(async (ctx, next) => {
      const { page } = ctx;
      await page.goto('https://www.xxx.com');
      const input = await page.$('input#kw');
      await input.type('Hello Yaomp!!!', { delay: 100 });
      await input.press('Enter');
      await next(); // 如果中间件没有写next 则不会向下执行
    })
    .use(showDialog)
    .use(Browser.close());

  app.runner({ page });
}

main();

Namespaces

• ctx.page.mouse 获取鼠标实例

Namespaces Detail

• ctx.page.mouse

  • return YAOMP.Mouse

  • ctx.page.mouse.click(x,y,[options])

    • 鼠标点击
    • x number
    • y number
    • options Object
      • button string - 点击位置 left, right 或 middle, 默认是left
      • clickCount number - 点击次数 默认是1
      • delay number 在毫秒内且在 mousedown 和 mouseup 之间等待的时间。 默认为0。
    • return Promise

• ctx.page.mouse.down([options])

  • 鼠标按下
  • options Object
    • button string - 点击位置 left, right 或 middle, 默认是left
    • clickCount number - 点击次数 默认是1
  • return Promise

• ctx.page.mouse.move(x,y,[options])

  • 鼠标移动
  • x number
  • y number
  • options Object
    • steps number - 默认是1 中间触发mousemove事件
  • return Promise

• ctx.page.mouse.up([options])

  • 鼠标弹起
  • options Object
    • button string - 点击位置 left, right 或 middle, 默认是left
    • clickCount number - 点击次数 默认是1
  • return Promise

Methods

• ctx.page.$ 获取单个元素
• ctx.page.$$ 获取多个元素
• ctx.page.$x 通过xpath表达式解析
• ctx.page.$eval 对dom进行获取/操作
• ctx.page.$$eval 对多个dom进行获取/操作
• ctx.page.frames 获取页面中存在的frame标签
• ctx.page.browser 获取当前page实例所属的Browser实例
• ctx.page.goto 跳转指定网址
• ctx.page.cookies获取cookies
• ctx.page.setCookie 插入cookies
• ctx.page.deleteCookie 删除Cookies
• ctx.page.screenshot 屏幕截图
• ctx.page.setGeolocation 设置页面的地理位置
• ctx.page.setUserAgent 设置用户代理
• ctx.page.goBack 返回上一层
• ctx.page.goForward 进入下一层
• ctx.page.hover
• ctx.page.reload 页面刷新
• ctx.page.url 获取URL
• ctx.page.evaluate 注入js执行
• ctx.page.evaluateOnNewDocument preload
• ctx.page.setRequestInterception 拦截请求
• ctx.page.waitFor 等待几秒
• ctx.page.waitForFunction 等待页面上下文执行的方法
• ctx.page.waitForNavigation 等待页面跳转完成
• ctx.page.waitForRequest 等待请求
• ctx.page.waitForResponse 等待响应
• ctx.page.waitForSelector 等待获取某个元素
• ctx.page.waitForXPath 等待通过xpath获取元素

Events

• ctx.page.on(event,callback)
  • close 监听页面关闭
  • console 监听控制台输出
  • dialog 监听dialog
  • domcontentloaded 监听Dom加载完
  • error 监听报错
  • load 监听Dom加载完
  • request 监听请求
  • response 监听响应
  • requestfailed 监听请求完成
  • requestfinished 监听响应完成

Medhods Detail

• ctx.page.$(selector)

  • 获取单个元素
  • selector string 选择器
  • return Promise<YAOMP.ElementHandle<Element> | null>

• ctx.page.$$(selector)

  • 获取多个元素
  • selector string 选择器
  • return Promise<YAOMP.ElementHandle<Element>[]>

• ctx.page.$x(expression)

  • 通过xpath去解析元素
  • expression string xPath 表达式
  • return Promise<YAOMP.ElementHandle<Element>[]>

• ctx.page.$eval(selector, pageFunction[, ...args])

  • 对Dom进行获取/操作
  • 此方法在页面内执行 document.querySelector，然后把匹配到的元素作为第一个参数传给 pageFunction。
  • selector string 选择器
  • pageFunction Function 在浏览器实例上下文中要执行的方法 ，如果 pageFunction 返回的是 Promise，那么此方法会等 promise 完成后返回其返回值
  • ...args ...YAOMP.Serializable|YAOMP.JSHandle 要传给 pageFunction 的参数。（比如你的代码里生成了一个变量，在页面中执行方法时需要用到，可以通过这个 args 传进去）
  • return Promise<YAOMP.Serializable>

• ctx.page.$$eval(selector, pageFunction[, ...args])

  • 对多个Dom进行获取/操作
  • 此方法在页面内执行 document.querySelector，然后把匹配到的元素作为第一个参数传给 pageFunction。
  • selector string 选择器
  • pageFunction Function 在浏览器实例上下文中要执行的方法 ，如果 pageFunction 返回的是 Promise，那么此方法会等 promise 完成后返回其返回值
  • ...args ...YAOMP.Serializable|YAOMP.JSHandle 要传给 pageFunction 的参数。（比如你的代码里生成了一个变量，在页面中执行方法时需要用到，可以通过这个 args 传进去）
  • return Promise<YAOMP.Serializable>

• ctx.page.goto(url[,options])

  • 跳转页面
  • url string 跳转地址 地址应该带有http协议, 比如 http:// | https://
  • opetions 选项
    • timeout number 跳转等待时间，单位是毫秒, 默认是30秒, 传 0 表示无限等待。
    • waitUntil string | Array<string> 满足什么条件认为页面跳转完成，默认是 load 事件触发时。指定事件数组，那么所有事件触发后才认为是跳转完成。事件包括
      • load - 页面的load触发时
      • documentloaded - 页面的Documentloaded触发时
      • networkidle0 - 不再有网络连接时触发（至少500毫秒后）
      • networkidle2 - 只有2个网络连接时触发（至少500毫秒后）
    • referer string 引用标头值
  • return Promise<?Promise<YAOMP.HTTPResponse>> Promise对象resolve后是主要的请求的响应。如果有多个跳转, resolve后是最后一次跳转的响应

• ctx.page.frames()

  • 返回加载到页面中的所有iframe标签
  • return Promise<Array<YAOMP.Frame>>

• ctx.page.browser()

  • 获取当前page实例所属的Browser实例
  • return YAOMP.Browser

• ctx.page.cookies([...urls])

  • 获取页面的Cookies
  • 如果不指定任何 url，此方法返回当前页面域名的 cookie。 如果指定了 url，只返回指定的 url 下的 cookie。
  • ...urls string
  • return Promise<Array<Object>>
    • name string - cookie 的名称
    • value string - cookie 的值
    • domain string - cookie 的域
    • path string - 服务器的路径
    • expires number - 过期时间 Unix time, 单位是秒
    • httpOnly boolean - 是否可以获取到该条cookie
    • secure boolean - 规定是可以通过https来传输cookie
    • session boolean
    • sameSite boolean - "Strict"或者"Lax" Cookie 允许服务器要求某个 cookie 在跨站请求时不会被发送

• ctx.page.setCookie(...cookies)

  • 插入cookies

  • ...cookies Object

    • name string - cookie 的名称
    • value string - cookie 的值
    • domain string - cookie 的域
    • path string - 服务器的路径
    • expires number - 过期时间 Unix time, 单位是秒
    • httpOnly boolean - 是否可以获取到该条cookie
    • secure boolean - 规定是可以通过https来传输cookie
    • session boolean
    • sameSite boolean - "Strict"或者"Lax" Cookie 允许服务器要求某个 cookie 在跨站请求时不会被发送

  • return Promise

• ctx.page.deleteCookie(...cookies)
  		```
  	
  		- 删除cookies
  		- ...cookies `Object`
  	
  		  - name `string 必传` - cookie的名称
  		  - url `string` 
  		  - domain `string`
  		  - path `string`
  		  - secure `string`
  		- return `Promise`

• ctx.page.screenshot([options])

  • 屏幕截图
  • options Object
    • path string 截图保存路径。截图图片类型将从文件扩展名推断出来。如果是相对路径，则从当前路径解析。如果没有指定路径，图片将不会保存到硬盘
    • type string 指定截图类型, 可以是 jpeg 或者 png。默认 'png'
    • quality number 图片质量, 可选值 0-100. png 类型不适用
    • fullpage boolean 如果设置为true，则对完整的页面（需要滚动的部分也包含在内）。默认是false
    • clip Object 指定裁剪区域。需要配置:
      • x number 裁剪区域相对于左上角（0， 0）的x坐标
      • y number 裁剪区域相对于左上角（0， 0）的y坐标
      • width number 裁剪宽度
      • height number 裁剪高度
    • omitBackground boolean 隐藏默认的白色背景，背景透明。默认不透明
    • encoding string 图像的编码可以是 base64 或 binary。 默认为“二进制”
  • return Promise<[Buffer|String|void]> Promise对象，resolve后是截图的buffer

• ctx.page.setGeolocation(options)

  • 设置页面地理位置
  • options Object
    • latitude number - 维度 范围 -90 and 90
    • longitude number - 经度 范围 -180 and 180
    • accuracy number - 可选的非负精度值
  • return Promise

• ctx.page.setUserAgent(userAgent)

  • 设置用户页面代理
  • userAgent string 在此页面中使用的特定用户代理
  • return Promise

• ctx.page.goBack([options])

  • 导航到页面历史的前一个页面
  • options Object 选项
    • timeout number 跳转等待时间，单位是毫秒, 默认是30秒, 传 0 表示无限等待。
    • waitUntil string | Array<string> 满足什么条件认为页面跳转完成，默认是 load 事件触发时。指定事件数组，那么所有事件触发后才认为是跳转完成。事件包括
      • load - 页面的load触发时
      • documentloaded - 页面的Documentloaded触发时
      • networkidle0 - 不再有网络连接时触发（至少500毫秒后）
      • networkidle2 - 只有2个网络连接时触发（至少500毫秒后）
  • return Promise<YAOMP.HTTPResponse> Promise对象resolve后是主要的请求的响应。如果有多个跳转, resolve后是最后一次跳转的响应. 如果不能回退，解析后是null

• ctx.page.goForward([options])

  • 导航到页面历史的后一个页面
  • options Object 选项
    • timeout number 跳转等待时间，单位是毫秒, 默认是30秒, 传 0 表示无限等待。
    • waitUntil string | Array<string> 满足什么条件认为页面跳转完成，默认是 load 事件触发时。指定事件数组，那么所有事件触发后才认为是跳转完成。事件包括
      • load - 页面的load触发时
      • documentloaded - 页面的Documentloaded触发时
      • networkidle0 - 不再有网络连接时触发（至少500毫秒后）
      • networkidle2 - 只有2个网络连接时触发（至少500毫秒后）
  • return Promise<YAOMP.HTTPResponse> Promise对象resolve后是主要的请求的响应. 如果有多个跳转, resolve后是最后一次跳转的响应. 如果不能向前，resolve后是null

• ctx.page.hover(selector)

  • 要hover的元素
  • selector string 要hover的元素的选择器 如果有多个匹配的元素，hover第一个.
  • return Promise Promise对象，当匹配的元素成功被hover后resolve。如果没有匹配的元素，将会rejected。

• ctx.page.reload([options])

  • 刷新页面
  • options Object 选项
    • timeout number 跳转等待时间，单位是毫秒, 默认是30秒, 传 0 表示无限等待。
    • waitUntil string | Array<string> 满足什么条件认为页面跳转完成，默认是 load 事件触发时。指定事件数组，那么所有事件触发后才认为是跳转完成。事件包括
      • load - 页面的load触发时
      • documentloaded - 页面的Documentloaded触发时
      • networkidle0 - 不再有网络连接时触发（至少500毫秒后）
      • networkidle2 - 只有2个网络连接时触发（至少500毫秒后）
  • return Promise Promise对象解析后是主要的请求的响应. 如果有多个跳转, 解析后是最后一次跳转的响应

• ctx.page.url()

  • 返回当前页面的URL
  • return string

• ctx.page.evaluate(pageFunction[, ...args])

  • pageFunction function | string 要在页面实例上下文中执行的方法

    • 如果pageFunction返回的是Promise，ctx.page.evaluate将等待promise完成，并返回其返回值
    • 如果pageFunction返回的是不能序列化的值，将返回undefined

  • ...args YAOMP.SerializableOrJSHandle 要传给 pageFunction 的参数

  • return Promise<YAOMP.UnwrapPromiseLike<YAOMP.EvaluateFnReturnType<T>>>

  • const result = await ctx.page.evaluate(x => Promise.resolve(8 * x), 7);
    console.log(result); // 56

  • console.log(await ctx.page.evaluate('1 + 2')); // 3
    const x = 10;
    console.log(await ctx.page.evaluate(`3 * ${x}`)); // 30

• ctx.page.evaluateOnNewDocument(pageFunction[, ...args])

  • 当作preload去使用

  • pageFunction function ｜ string 要在页面实例上下文中执行的方法

  • ...args YAOMP.Serializable 要传给pageFunction的参数

  • return Promise

  • 添加一个方法，在下面的场景下被调用

    • 跳转页面完成
    • iframe页面加载或跳转完成。这种场景指定的函数被调用的上下文是新加载的iframe

  • 页面加载前重写window.navigator.webdriver属性例子

  • await ctx.page.evaluateOnNewDocument(() => {
      const _protos_ = window.navigator.__proto__;
      Reflect.deleteProperty(_protos_,'webdriver');
      navigator.__proto__ = _protos_;
    });

• ctx.page.waitFor(delay)

  • 等待几秒
  • deplay number 单位 秒
  • return Promise

• ctx.page.waitForFunction(pageFunction[, options[, ...args]])

  • pageFunction function | string 要在浏览器实例上下文执行的方法
  • options Object
    • polling string | number - pageFunction 执行的时间间隔，默认为 raf。如果 polling 是一个数字，则将其视为执行函数的时间间隔（以毫秒为单位）。如果 polling 是一个字符串，那么它可以是以下值之一
      • raf - 在 requestAnimationFrame 回调中不断执行 pageFunction。这是最紧密的轮询模式，适合观察样式变化
      • mutation - 对每个 DOM 突变执行 pageFunction.
    • timeout number 最长时间，单位是毫秒. 默认 30000 (30 seconds). 传 0 表示不会超时
  • ...args YAOMP.SerializableOrJSHandle 传给 pageFunction的参数
  • return Promise Promise 对象，当 pageFunction 返回等于true的结果时resolve, resolves 为结果的 JSHandle 类型

• ctx.page.waitForNavigation

  • 等待页面跳转
  • options Object 选项
    • timeout number 跳转等待时间，单位是毫秒, 默认是30秒, 传 0 表示无限等待。
    • waitUntil string | Array<string> 满足什么条件认为页面跳转完成，默认是 load 事件触发时。指定事件数组，那么所有事件触发后才认为是跳转完成。事件包括
      • load - 页面的load触发时
      • documentloaded - 页面的Documentloaded触发时
      • networkidle0 - 不再有网络连接时触发（至少500毫秒后）
      • networkidle2 - 只有2个网络连接时触发（至少500毫秒后）
  • return Promise<[?YAOMP.HTTPResponse]> Promise对象resolve后是主要的请求的响应。如果有多个跳转, resolve后是最后一次跳转的响应。如果由于使用 History API 而导航到不同的锚点或导航，导航将以 null 解析。

• ctx.page.waitForRequest(urlOrPredicate[, options])

  • 等待请求 / 监听响应

  • urlOrPredicate string｜function 要等待的 URL 或 执行方法

  • options Object 选项

    • timeout number 最大等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时

  • return Promise<YAOMP.HTTPRequest>

  • const res = await ctx.page.waitForRequest('https://www.xxx.com/api_v1/user/list');
    console.log(res);

  • await ctx.page.waitForRequest(async request => {
      const url = request.url();
      if(url.includes('https://www.xxx.com/api_v1/user/list')) {
        // do something ...
        return true; // 返回true 停止监听
      }
      
      return false; // 返回false会继续监听该接口 直到返回true停止
    })

• ctx.page.waitForResponse(urlOrPredicate[, options])

  • 等待响应 / 监听响应
  • urlOrPredicate string｜function 要等待的 URL 或 执行方法
  • options Object 选项
    • timeout number 最大等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时
  • return Promise<YAOMP.HTTPResponse>

  • const res = await ctx.page.waitForResponse('https://www.xxx.com/api_v1/user/list');
    const json = await res.json();
    console.log(json);

  • await ctx.page.waitForResponse(async response => {
      const url = response.url();
      if(url.includes('https://www.xxx.com/api_v1/user/list')) {
        // do something ...
        return true; // 返回true 停止监听
      }
      
      return false; // 返回false会继续监听该接口 直到返回true停止
    })

•  ctx.page.waitForSelector(selector[, options])

• 选择元素 / 等待某个元素出现并选择

• 等待指定的选择器匹配的元素出现在页面中，如果调用此方法时已经有匹配的元素，那么此方法立即返回。 如果指定的选择器在超时时间后扔不出现，此方法会报错

• selector string 选择器

• options Object

  • visible boolean - 等元素出现在dom中并且可以看到, 比如。 没有 display: none 或者 visibility: hidden 样式。 默认是 false
  • hidden boolean - 等元素在dom中消失或看不到, 比如。 有 display: none 或者 visibility: hidden 样式。 默认是 false
  • timeout number - 最大等待时间，单位是毫秒，默认是30000 (30 seconds)，传0表示不会超时

• return Promise<YAOMP.ElementHandle> Promise对象，当指定选择器匹配的元素添加到dom中时resolve

• const modalBtn = await ctx.page.waitForSelector('#Modal .modal-body .modal-content .modal-footer > button:last-child');
  await modalBtn.click();

• ctx.page.waitForXPath(xpath[, options])

  • 等待通过xpath获取某个元素
  • xpath string 要等待的元素的xpath表达式
  • options Object
    • visible boolean - 等元素出现在dom中并且可以看到, 比如. 没有 display: none 或者 visibility: hidden 样式. 默认是 false.
    • hidden boolean - 等元素在dom中消失或看不到, 比如. 有 display: none 或者 visibility: hidden 样式. 默认是 false
    • timeout number 最大等待时间，单位是毫秒，默认是30000 (30 seconds)，传0表示不会超时
  • return Promise<YAOMP.ElementHandle<Element> | null>
  • 等待指定的xpath匹配的元素出现在页面中，如果调用此方法时已经有匹配的元素，那么此方法立即返回。 如果指定的xpath在超时时间后扔不出现，此方法会报错。

• ctx.page.setRequestInterception(value)

  • 拦截请求

  • 场景：可用于拦截请求并修改其参数再提交

  • value boolean 是否启用请求拦截器

  • return Promise

  • 启用请求拦截器，会激活 request.abort, request.continue 和 request.respond 方法。这提供了修改页面发出的网络请求的功能

  • // 一旦启用请求拦截，每个请求都将停止，除非它继续，响应或中止。 通过请求拦截器取消所有图片请求 :
    
    await ctx.page.setRequestInterception(true);
    page.on('request', async request => {
      if (request.url().endsWith('.png') || request.url().endsWith('.jpg'))
          request.abort();
        else
          request.continue();
      });
    })

​