Chromeless项目API完全指南：浏览器操作自动化详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01184/article/details/148392161

Chromeless项目API完全指南：浏览器操作自动化详解

chromeless 🖥 Chrome automation made simple. Runs locally or headless on AWS Lambda. 项目地址: https://gitcode.com/gh_mirrors/ch/chromeless

前言

Chromeless是一个基于Chrome Headless的自动化测试工具，它提供了一套简洁的API来实现浏览器中的各种操作。本文将全面解析Chromeless的API功能，帮助开发者快速掌握这个强大的工具。

核心概念

Chromeless工作原理

Chromeless通过Chrome DevTools Protocol与浏览器交互，可以本地运行或远程连接浏览器实例。它抽象了底层协议的复杂性，提供了高级API来执行常见的浏览器操作。

初始化配置

创建Chromeless实例时，可以通过配置对象进行个性化设置：

const chromeless = new Chromeless({
  debug: true,  // 开启调试输出
  viewport: {   // 设置视口尺寸
    width: 1280,
    height: 800,
    scale: 1
  },
  implicitWait: true,  // 元素隐式等待
  waitTimeout: 15000   // 等待超时时间(毫秒)
});

核心API详解

页面导航与控制

页面跳转 - goto(url, timeout)
- 支持设置超时时间
- 自动等待页面加载完成

await chromeless.goto('https://example.com', 10000);

用户代理设置 - setUserAgent(useragent)
- 必须在页面跳转前调用
- 可用于移动设备访问测试

await chromeless
  .setUserAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X)')
  .goto('https://m.example.com');

用户交互实现

点击操作 - click(selector, x, y)
- 支持精确坐标点击
- 自动处理元素可见性

// 点击按钮中心
await chromeless.click('#submit-btn');

// 点击特定坐标
await chromeless.click('#map', 100, 200);

键盘输入 - type(input, selector)
- 支持直接输入或指定输入框
- 实现用户输入行为

// 在搜索框中输入关键词
await chromeless.type('chromeless', 'input[name="q"]');

// 直接输入(需先聚焦元素)
await chromeless
  .focus('#comment')
  .type('这是一条测试评论');

页面等待策略

显式等待 - wait(timeout|selector)
- 支持时间等待和元素等待两种模式
- 可配置全局超时时间

// 等待1秒
await chromeless.wait(1000);

// 等待元素出现(最多10秒)
await chromeless.wait('#loading-complete');

条件等待 - wait(fn)
- 等待自定义条件满足
- 支持异步判断逻辑

await chromeless.wait(() => {
  return document.readyState === 'complete';
});

页面内容操作

执行JavaScript - evaluate(fn)
- 在页面上下文中执行代码
- 可返回任意JSON可序列化数据

const title = await chromeless.evaluate(() => {
  return document.title;
});

HTML操作 - html() / setHtml(html)
- 获取或设置完整HTML
- 可用于模板测试

// 设置自定义HTML
await chromeless.setHtml('<h1>测试页面</h1>');

// 获取当前HTML
const pageHtml = await chromeless.html();

截图与导出

页面截图 - screenshot(selector, options)
- 支持全屏或元素截图
- 可指定保存路径

// 全屏截图
const fullPage = await chromeless.screenshot();

// 元素截图
const logo = await chromeless.screenshot('#logo', {
  filePath: './logo.png'
});

PDF导出 - pdf(options)
- 需在无头模式下运行
- 支持多种打印选项

const pdf = await chromeless
  .goto('https://example.com')
  .pdf({
    landscape: true,
    margin: '1cm'
  });

Cookie管理

Chromeless提供了完整的Cookie操作API：

// 设置Cookie
await chromeless.setCookies('session', 'abc123');

// 获取特定Cookie
const cookie = await chromeless.cookies('session');

// 清除所有Cookie
await chromeless.clearCookies();

高级功能

视口控制

动态调整浏览器视口尺寸：

await chromeless.setViewport({
  width: 375,
  height: 667,
  deviceScaleFactor: 2  // 视网膜屏幕缩放
});

文件上传

处理文件输入框：

await chromeless.setFileInput(
  '#upload-input',
  ['/path/to/file1.jpg', '/path/to/file2.jpg']
);

缓存与存储

清理浏览器数据：

// 清除缓存
await chromeless.clearCache();

// 清除特定存储
await chromeless.clearStorage(
  'https://example.com',
  'local_storage, indexeddb'
);

最佳实践

错误处理：建议使用try-catch包裹可能失败的操作
资源释放：操作完成后务必调用end()方法
性能优化：合理设置等待时间，避免不必要的延迟

try {
  const result = await chromeless
    .goto('https://example.com')
    .evaluate(/* ... */)
    .end();
} catch (err) {
  console.error('操作失败:', err);
}