前言
在 Chrome DevTools Protocol（CDP）中，Runtime 域是一个非常重要的部分，它主要用于与 JavaScript 的执行环境进行交互。通过 Runtime 域，开发者可以在页面上下文中执行 JavaScript 代码、评估表达式、捕获异常等操作，类似于在浏览器的控制台中手动输入代码的操作。Runtime 域的灵活性使得它在调试、测试和自动化任务中得到了广泛应用。
本文将详细介绍 CDP 的 Runtime 域，并通过几个示例展示如何使用它在浏览器中执行代码和处理结果。
Runtime 域简介
Runtime 域包含了一系列与 JavaScript 执行相关的命令和事件，用于控制和管理页面中的 JavaScript 执行环境。常见的功能包括：
- 在页面上下文中执行任意 JavaScript 代码。
- 获取 JavaScript 的执行结果。
- 捕获和处理脚本执行时的异常。
- 处理 JavaScript 的 promise 和异步操作。
- 检查、调试 JavaScript 对象的属性和值。
Runtime 域常用命令
1. Runtime.evaluate — 执行 JavaScript 表达式
Runtime.evaluate 是 Runtime 域中最常用的命令，它用于在页面的 JavaScript 上下文中评估一个表达式。这个命令可以在页面中执行任意的 JavaScript 代码，并返回执行结果。
请求结构：
{
"id": 1,
"method": "Runtime.evaluate",
"params": {
"expression": "document.title",
"returnByValue": true
}
}
参数说明：
expression: 需要执行的 JavaScript 表达式。例如，获取页面的document.title。returnByValue: 指定返回结果时，是否将 JavaScript 对象以纯 JSON 格式返回。如果为true，则会将值序列化后返回；如果为false，则返回对象的引用。
返回结构：
{
"id": 1,
"result": {
"result": {
"type": "string",
"value": "Example Page Title"
}
}
}
在这个例子中，Runtime.evaluate 执行了表达式 document.title，并返回了当前页面的标题。
2. Runtime.callFunctionOn — 调用 JavaScript 函数
Runtime.callFunctionOn 命令允许开发者在指定的 JavaScript 对象上下文中调用一个函数。这个命令特别适合用于操作已有的 JavaScript 对象，例如 DOM 元素或自定义对象。
请求结构：
{
"id": 2,
"method": "Runtime.callFunctionOn",
"params": {
"objectId": "1234.5", // 目标对象的 ID
"functionDeclaration": "function() { return this.innerHTML; }"
}
}参数说明：
objectId: JavaScript 对象的 ID，通常通过Runtime.evaluate获取到的对象引用。functionDeclaration: 需要调用的 JavaScript 函数声明。
返回结构：
{
"id": 2,
"result": {
"result": {
"type": "string",
"value": "<p>Hello, World!</p>"
}
}
}
在此示例中，Runtime.callFunctionOn 被用于在特定 DOM 元素的上下文中调用一个函数，获取其 innerHTML 值。
3. Runtime.getProperties — 获取对象属性
Runtime.getProperties 命令用于获取 JavaScript 对象的属性和值。它在调试时非常有用，尤其当你想深入了解某个对象的结构或状态时。
请求结构：
{
"id": 2,
"result": {
"result": {
"type": "string",
"value": "<p>Hello, World!</p>"
}
}
}参数说明：
objectId: JavaScript 对象的 ID。ownProperties: 如果为true，则只返回对象自身的属性，不包括继承的属性。
返回结构：
{
"id": 3,
"result": {
"result": [
{
"name": "tagName",
"value": {
"type": "string",
"value": "DIV"
}
},
{
"name": "innerHTML",
"value": {
"type": "string",
"value": "<p>Hello, World!</p>"
}
}
]
}
}通过这个命令，开发者可以获取对象的所有属性和值，并在调试过程中检查它们的状态。
异步操作和 Promise 处理
现代 JavaScript 应用广泛使用异步操作和 Promise 对象。Runtime 域同样提供了一些机制来处理这些异步操作。
1. Runtime.awaitPromise — 处理 Promise
Runtime.awaitPromise 命令可以等待一个 Promise 对象的解析（resolve）或拒绝（reject）。这在处理异步代码时非常有用。
请求结构：
{
"id": 4,
"method": "Runtime.evaluate",
"params": {
"expression": "new Promise((resolve) => setTimeout(() => resolve(42), 1000))",
"awaitPromise": true
}
}
返回结构：
{
"id": 4,
"result": {
"result": {
"type": "number",
"value": 42
}
}
}在此例中，Runtime.evaluate 被用于执行一个延迟 1 秒后返回 42 的 Promise。通过设置 awaitPromise: true，我们可以等待 Promise 完成并直接获取其结果。
错误处理
在执行 JavaScript 代码时，错误和异常是不可避免的。Runtime 域提供了一些机制来捕获和处理这些错误，帮助开发者调试代码。
1. 捕获执行错误
Runtime.evaluate 和 Runtime.callFunctionOn 都可以通过响应结构中的 exceptionDetails 字段来返回 JavaScript 执行中的异常。
异常响应结构：
{
"id": 5,
"result": {
"exceptionDetails": {
"text": "ReferenceError: myVar is not defined",
"exception": {
"type": "object",
"className": "ReferenceError",
"description": "ReferenceError: myVar is not defined"
}
}
}
}通过检查 exceptionDetails，开发者可以捕获并处理执行中的错误，进一步提高代码的健壮性。
测试案例
import asyncio
import websockets
import json
async def runtime_complex_test(cdp_url):
async with websockets.connect(cdp_url) as websocket:
# 1. 使用 Runtime.evaluate 创建一个对象，并获取对象引用
expression = """
(() => {
const obj = {
a: 1,
b: 2,
add: function() {
return this.a + this.b;
},
async computeAsync() {
return new Promise(resolve => setTimeout(() => resolve(42), 1000));
}
};
return obj;
})();
"""
await websocket.send(json.dumps({
'id': 1,
'method': 'Runtime.evaluate',
'params': {
'expression': expression,
'returnByValue': False, # 返回对象的引用而不是值
'objectGroup': 'exampleGroup' # 对象组名，方便后续引用
}
}))
response = json.loads(await websocket.recv())
object_id = response['result']['result']['objectId']
print(f"创建对象成功，objectId: {object_id}")
# 2. 使用 Runtime.callFunctionOn 调用对象的 add 方法
await websocket.send(json.dumps({
'id': 2,
'method': 'Runtime.callFunctionOn',
'params': {
'objectId': object_id,
'functionDeclaration': 'function() { return this.add(); }',
'returnByValue': True # 直接返回函数结果
}
}))
response = json.loads(await websocket.recv())
add_result = response['result']['result']['value']
print(f"调用 add 方法的结果: {add_result}")
# 3. 使用 Runtime.getProperties 获取对象的属性
await websocket.send(json.dumps({
'id': 3,
'method': 'Runtime.getProperties',
'params': {
'objectId': object_id,
'ownProperties': True # 仅获取对象自身的属性
}
}))
response = json.loads(await websocket.recv())
properties = response['result']['result']
print("对象属性:")
for prop in properties:
name = prop['name']
value = prop['value']['value'] if 'value' in prop['value'] else '不可读取'
print(f" {name}: {value}")
# 4. 使用 Runtime.callFunctionOn 调用异步方法，并通过 Runtime.awaitPromise 处理返回的 Promise
await websocket.send(json.dumps({
'id': 4,
'method': 'Runtime.callFunctionOn',
'params': {
'objectId': object_id,
'functionDeclaration': 'function() { return this.computeAsync(); }',
'awaitPromise': True # 等待异步操作完成
}
}))
response = json.loads(await websocket.recv())
if 'result' in response and response['result']['result']['value'] == 42:
print(f"异步方法的返回值: {response['result']['result']['value']}")
# 清理对象
await websocket.send(json.dumps({
'id': 5,
'method': 'Runtime.releaseObjectGroup',
'params': {
'objectGroup': 'exampleGroup'
}
}))
print("对象已释放")
# 替换成你实际的 CDP WebSocket URL
cdp_url = "ws://localhost:9222/devtools/page/1F1A646103FECD9BDC9C29868F0E31D1"
asyncio.get_event_loop().run_until_complete(runtime_complex_test(cdp_url))
代码解释：
Runtime.evaluate：我们首先通过Runtime.evaluate执行一段 JavaScript 代码，返回一个包含属性和方法的对象。这段代码定义了一个简单的对象obj，具有属性a、b，一个同步方法add，和一个异步方法computeAsync。returnByValue: False表示我们只想返回对象的引用（objectId），而不是返回整个对象的内容。
Runtime.callFunctionOn：使用Runtime.callFunctionOn，我们在第一个对象上调用add方法，并返回其执行结果。该方法直接执行对象内部的add函数并返回其结果。returnByValue: True表示直接返回调用结果，而不是对象引用。
Runtime.getProperties：我们使用Runtime.getProperties来获取对象的所有属性及其值。返回的属性列表包括对象a和b的值。Runtime.awaitPromise：调用异步方法computeAsync时，我们需要等待Promise完成。通过awaitPromise: True，CDP 会等待异步操作完成，并返回 Promise 的最终结果。- 清理对象：最后通过
Runtime.releaseObjectGroup释放对象，避免内存泄漏。
运行结果：
执行此脚本时，你会看到以下输出，展示了每一步操作的结果：
创建对象成功，objectId: -2387282854439575449.11.1
调用 add 方法的结果: 3
对象属性:
a: 1
b: 2
add: 不可读取
computeAsync: 不可读取
异步方法的返回值: 42
对象已释放总结
Runtime 域为开发者提供了一个强大的工具集，可以用于控制和管理页面中的 JavaScript 执行环境。通过 Runtime.evaluate 和 Runtime.callFunctionOn 等命令，开发者能够以编程的方式与页面交互，执行任意的 JavaScript 代码，获取执行结果，并处理 JavaScript 的错误和异步操作。
熟练掌握 Runtime 域可以极大提升调试和自动化任务的效率，帮助开发者更好地管理和控制浏览器中的 JavaScript 执行流程。
