├── .github ├── axe-linter.yml ├── review.yml └── workflows │ └── sync-master-into-develop.yml ├── .gitignore ├── test ├── extension │ ├── content.js │ ├── background.js │ ├── devtools.js │ ├── page.html │ ├── devtools.html │ ├── panel.html │ └── manifest.json ├── extension-manifest-v3 │ ├── content.js │ ├── background.js │ ├── devtools.js │ ├── page.html │ ├── devtools.html │ ├── panel.html │ └── manifest.json ├── fixtures │ ├── frame.html │ └── index.html ├── integration.ts ├── test.ts └── test-manifest-v3.ts ├── .mocharc.json ├── .babelrc ├── src ├── puppeteer-adapter.ts └── index.ts ├── tsconfig.json ├── .eslintrc.js ├── code_of_conduct.md ├── SECURITY.md ├── package.json ├── .circleci └── config.yml ├── CHANGELOG.md ├── README.md └── LICENSE /.github/axe-linter.yml: -------------------------------------------------------------------------------- 1 | exclude: 2 | - CHANGELOG.md 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | dist 3 | .nyc_output 4 | coverage -------------------------------------------------------------------------------- /test/extension/content.js: -------------------------------------------------------------------------------- 1 | (() => { 2 | window.extension_content_script = true; 3 | })() -------------------------------------------------------------------------------- /test/extension-manifest-v3/content.js: -------------------------------------------------------------------------------- 1 | (() => { 2 | window.extension_content_script = true; 3 | })() -------------------------------------------------------------------------------- /test/extension/background.js: -------------------------------------------------------------------------------- 1 | // eslint-disable-next-line @typescript-eslint/no-unused-vars 2 | var foo 3 | -------------------------------------------------------------------------------- /.mocharc.json: -------------------------------------------------------------------------------- 1 | { 2 | "require": "ts-node/register", 3 | "extensions": ["ts"], 4 | "spec": ["test/*.ts"] 5 | } -------------------------------------------------------------------------------- /.github/review.yml: -------------------------------------------------------------------------------- 1 | # Require that merge commits have security review performed on them. 2 | review_merges: true 3 | -------------------------------------------------------------------------------- /test/extension-manifest-v3/background.js: -------------------------------------------------------------------------------- 1 | // eslint-disable-next-line @typescript-eslint/no-unused-vars 2 | var foo 3 | -------------------------------------------------------------------------------- /test/extension/devtools.js: -------------------------------------------------------------------------------- 1 | // eslint-disable-next-line @typescript-eslint/no-empty-function 2 | chrome.devtools.panels.create('test extension', '', 'panel.html', ()=> {}) -------------------------------------------------------------------------------- /test/extension-manifest-v3/devtools.js: -------------------------------------------------------------------------------- 1 | // eslint-disable-next-line @typescript-eslint/no-empty-function 2 | chrome.devtools.panels.create('test extension', '', 'panel.html', ()=> {}) -------------------------------------------------------------------------------- /test/extension/page.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | extension page 6 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /test/extension-manifest-v3/page.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | extension page 6 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /.babelrc: -------------------------------------------------------------------------------- 1 | { 2 | "presets": [ 3 | [ 4 | "@babel/env", 5 | { 6 | "targets": { 7 | "node": 12 8 | } 9 | } 10 | ], 11 | "@babel/typescript" 12 | ] 13 | } -------------------------------------------------------------------------------- /test/extension/devtools.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | devtools page 6 | 7 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /test/extension-manifest-v3/devtools.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | devtools page 6 | 7 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /test/fixtures/frame.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Puppeteer Devtools Test Fixture Frame 5 | 6 | 7 |
8 |

Inner Frame

9 |
10 | 11 | -------------------------------------------------------------------------------- /test/extension/panel.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 10 | 11 | 12 |
devtools panel
13 | 14 | -------------------------------------------------------------------------------- /test/fixtures/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Puppeteer Devtools Test Fixture Page 5 | 6 | 7 |
8 |

Hello

9 | 10 |
11 | 12 | -------------------------------------------------------------------------------- /test/extension-manifest-v3/panel.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 10 | 11 | 12 |
devtools panel
13 | 14 | -------------------------------------------------------------------------------- /src/puppeteer-adapter.ts: -------------------------------------------------------------------------------- 1 | import { type DOMWorld } from 'puppeteer/lib/cjs/puppeteer/common/DOMWorld.js' 2 | import { ExecutionContext } from 'puppeteer/lib/cjs/puppeteer/common/ExecutionContext.js' 3 | import Protocol from 'devtools-protocol' 4 | import { type CDPSession } from 'puppeteer/lib/cjs/puppeteer/common/Connection.js' 5 | 6 | export type ExecutionContextDescription = 7 | Protocol.Runtime.ExecutionContextDescription 8 | export { DOMWorld, CDPSession, ExecutionContext } 9 | -------------------------------------------------------------------------------- /.github/workflows/sync-master-into-develop.yml: -------------------------------------------------------------------------------- 1 | name: Sync master/develop branches 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | 8 | jobs: 9 | create_sync_pull_request: 10 | runs-on: ubuntu-latest 11 | steps: 12 | - uses: dequelabs/action-sync-branches@v1 13 | with: 14 | github-token: ${{ secrets.GITHUB_TOKEN }} 15 | pr-title: "chore: merge master into develop" 16 | pr-reviewers: scurker,schne324 17 | pr-labels: chore 18 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "es2017", 4 | "module": "commonjs", 5 | "moduleResolution": "node", 6 | "noImplicitReturns": true, 7 | "noFallthroughCasesInSwitch": true, 8 | "pretty": true, 9 | "strict": true, 10 | "sourceMap": true, 11 | "outDir": "./dist", 12 | "declaration": true, 13 | "skipLibCheck": true, 14 | "noImplicitAny": true, 15 | "esModuleInterop": true, 16 | "resolveJsonModule": true 17 | }, 18 | "include": ["src/*.ts", "test/*.ts"] 19 | } 20 | -------------------------------------------------------------------------------- /test/extension/manifest.json: -------------------------------------------------------------------------------- 1 | { 2 | "manifest_version": 2, 3 | "name": "Test Chrome Extension", 4 | "description": "Test Chrome Extension", 5 | "version": "1.2.3", 6 | "devtools_page": "devtools.html", 7 | "content_scripts": [ 8 | { 9 | "matches": ["*://testpage.test/", "*://testpage.test/frame"], 10 | "js": ["content.js"], 11 | "all_frames": true, 12 | "run_at": "document_start" 13 | } 14 | ], 15 | "background": { 16 | "scripts": ["background.js"], 17 | "persistent": true 18 | }, 19 | "content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self'", 20 | "web_accessible_resources": ["page.html"] 21 | } 22 | -------------------------------------------------------------------------------- /.eslintrc.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | env: { 3 | browser: true, 4 | es6: true, 5 | node: true, 6 | webextensions: true, 7 | }, 8 | extends: [ 9 | 'eslint:recommended', 10 | 'plugin:@typescript-eslint/eslint-recommended', 11 | 'plugin:@typescript-eslint/recommended', 12 | 'prettier', 13 | ], 14 | plugins: ['eslint-plugin-import', '@typescript-eslint'], 15 | root: true, 16 | rules: { 17 | '@typescript-eslint/no-explicit-any': 'off', 18 | 'comma-dangle': 0 19 | }, 20 | overrides: [ 21 | { 22 | files: ['*.ts'], 23 | parser: '@typescript-eslint/parser', 24 | parserOptions: { 25 | project: './tsconfig.json', 26 | }, 27 | }, 28 | ], 29 | } 30 | -------------------------------------------------------------------------------- /test/extension-manifest-v3/manifest.json: -------------------------------------------------------------------------------- 1 | { 2 | "manifest_version": 3, 3 | "name": "Test Chrome Extension Manifest V3", 4 | "description": "Test Chrome Extension Manifest V3", 5 | "version": "1.2.3", 6 | "devtools_page": "devtools.html", 7 | "content_scripts": [ 8 | { 9 | "matches": ["*://testpage.test/", "*://testpage.test/frame"], 10 | "js": ["content.js"], 11 | "all_frames": true, 12 | "run_at": "document_start" 13 | } 14 | ], 15 | "background": { 16 | "service_worker": "background.js" 17 | }, 18 | "content_security_policy": { 19 | "extension_pages": "script-src 'self' ; object-src 'self'" 20 | }, 21 | "web_accessible_resources": [{ 22 | "resources": ["page.html"], 23 | "matches": [""] 24 | }] 25 | } 26 | -------------------------------------------------------------------------------- /test/integration.ts: -------------------------------------------------------------------------------- 1 | import assert from 'assert' 2 | import puppeteer from 'puppeteer' 3 | 4 | describe('integration', () => { 5 | 6 | it('puppeteer target should have internal _targetInfo property', async () => { 7 | const browser = await puppeteer.launch() 8 | const [page] = await browser.pages() 9 | await page.goto('about:blank') 10 | 11 | const target = await browser.waitForTarget( 12 | target => target.url() === 'about:blank' 13 | ) 14 | const anyTarget = target as any 15 | 16 | // Target._targetType.type is an internal property used to force puppeteer to allow us 17 | // to use Target.page() for targets that do not normally return pages such as those 18 | // used by extension contexts. 19 | // 20 | // Having a page context allows us to use puppeteer method that would not normally be available. 21 | // 22 | // see: https://github.com/puppeteer/puppeteer/issues/4247 23 | // see: https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#targettype 24 | assert(typeof anyTarget._targetInfo === 'object') 25 | assert('type' in anyTarget._targetInfo) 26 | await browser.close() 27 | }) 28 | 29 | it('puppeteer should have internal ExecutionContext module', () => { 30 | assert.doesNotThrow(() => { 31 | require('puppeteer/lib/cjs/puppeteer/common/ExecutionContext.js') 32 | }) 33 | }) 34 | 35 | }) -------------------------------------------------------------------------------- /code_of_conduct.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | Deque is committed to providing a safe, inclusive, and welcoming virtual environment for contributors. 4 | 5 | We created this policy not because we anticipate bad behavior, but because we believe that articulating our values and obligations to one another reinforces a level of respect among contributors and because having a code of conduct provides us with clear avenues to correct our virtual culture should it ever stray from that course. 6 | 7 | ## Code of Conduct Policy 8 | 9 | We expect all contributors to Deque open-source projects to uphold the principles of this Code of Conduct. We do not tolerate disruptive or disrespectful behavior, messages, images, or interactions by any participant, in any form. 10 | 11 | We will not tolerate harassment or discrimination based on age, ancestry, color, gender identity or expression, national origin, physical or mental disability, religion, sexual orientation, or any other characteristic. 12 | 13 | ## Enforcement and Reporting 14 | 15 | Contributors asked to stop any harassing behavior are expected to comply immediately; regardless, Deque reserves the right to remove or block anyone from any repository at the discretion of Deque employees. 16 | 17 | If you have any concerns, please contact a code-owner or other Deque employee via direct message on the [axe Community Slack](https://accessibility.deque.com/axe-community) with details about the nature of the concern. 18 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | ## Security 2 | 3 | Deque takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organization [Dequelabs](https://github.com/dequelabs). 4 | 5 | If you believe you have found a security vulnerability in any Deque-owned repository that meets [Deque's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. 6 | 7 | ## Reporting Security Issues 8 | 9 | **Please do not report security vulnerabilities through public GitHub issues.** 10 | 11 | Instead, email them to Deque Security at [security@deque.com](mailto:security@deque.com). 12 | 13 | You should receive a response within 24 business hours. If for some reason you do not, please follow up via email to ensure we received your original message. 14 | 15 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 16 | 17 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 18 | * Full paths of source file(s) related to the manifestation of the issue 19 | * The location of the affected source code (tag/branch/commit or direct URL) 20 | * Any special configuration required to reproduce the issue (e.g. OS, browser, settings, options etc.) 21 | * Step-by-step instructions to reproduce the issue 22 | * Proof-of-concept or exploit code (if possible) 23 | * Impact of the issue, including how an attacker might exploit the issue 24 | 25 | This information will help us triage your report more quickly. 26 | 27 | We currently do not have a bug bounty program. 28 | 29 | ## Preferred Languages 30 | 31 | We prefer all communications to be in English. 32 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "puppeteer-devtools", 3 | "version": "3.3.0", 4 | "description": "Extended puppeteer methods for getting extension devtools contexts", 5 | "main": "dist/index.js", 6 | "types": "dist/index.d.ts", 7 | "files": [ 8 | "dist" 9 | ], 10 | "scripts": { 11 | "build": "npm-run-all build:definition build:ts", 12 | "build:definition": "tsc --emitDeclarationOnly", 13 | "build:ts": "babel src --out-dir dist --extensions \".ts\"", 14 | "clean:dist": "rimraf dist", 15 | "coverage": "nyc mocha", 16 | "fmt": "prettier --write *.{md,js,json} 'src/**/*.{md,ts,json}'", 17 | "lint": "eslint .", 18 | "prebuild": "npm-run-all clean:*", 19 | "prepare": "npm run build", 20 | "release": "standard-version", 21 | "test": "mocha --parallel" 22 | }, 23 | "author": "Jason Wilson ", 24 | "license": "MPL-2.0", 25 | "repository": { 26 | "type": "git", 27 | "url": "https://github.com/dequelabs/puppeteer-devtools.git" 28 | }, 29 | "publishConfig": { 30 | "registry": "https://registry.npmjs.org/" 31 | }, 32 | "devDependencies": { 33 | "@babel/cli": "^7.7.0", 34 | "@babel/core": "^7.7.2", 35 | "@babel/preset-env": "^7.7.1", 36 | "@babel/preset-typescript": "^7.7.2", 37 | "@types/mocha": "^10.0.6", 38 | "@typescript-eslint/eslint-plugin": "^5.61.0", 39 | "@typescript-eslint/parser": "^5.61.0", 40 | "eslint": "^8.44.0", 41 | "eslint-config-prettier": "^8.8.0", 42 | "eslint-plugin-import": "^2.27.5", 43 | "husky": "^3.1.0", 44 | "lint-staged": "^12.3.3", 45 | "mocha": "^10.2.0", 46 | "npm-run-all": "^4.1.5", 47 | "nyc": "^15.1.0", 48 | "prettier": "^3.0.0", 49 | "puppeteer": "14.1.1", 50 | "rimraf": "^3.0.0", 51 | "standard-version": "^9.3.2", 52 | "ts-node": "^8.5.2", 53 | "typescript": "^5.1.6" 54 | }, 55 | "peerDependencies": { 56 | "puppeteer": ">= 9.1.1 <= 14.1.1" 57 | }, 58 | "prettier": { 59 | "singleQuote": true, 60 | "arrowParens": "avoid", 61 | "bracketSpacing": true, 62 | "printWidth": 80, 63 | "semi": false, 64 | "tabWidth": 2, 65 | "useTabs": false, 66 | "trailingComma": "none" 67 | }, 68 | "husky": { 69 | "hooks": { 70 | "pre-commit": "lint-staged" 71 | } 72 | }, 73 | "lint-staged": { 74 | "*.ts": [ 75 | "eslint --fix", 76 | "prettier --write" 77 | ], 78 | "*.{json,md}": [ 79 | "prettier --write" 80 | ] 81 | }, 82 | "nyc": { 83 | "include": [ 84 | "src/**/*.ts" 85 | ], 86 | "extension": [ 87 | ".ts" 88 | ], 89 | "require": [ 90 | "ts-node/register" 91 | ], 92 | "reporter": [ 93 | "text-summary", 94 | "html" 95 | ], 96 | "sourceMap": true, 97 | "instrument": true, 98 | "checkCoverage": true, 99 | "statements": 95, 100 | "branches": 84, 101 | "functions": 95, 102 | "lines": 95 103 | } 104 | } 105 | -------------------------------------------------------------------------------- /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | version: 2.1 2 | 3 | orbs: 4 | browser-tools: circleci/browser-tools@1.4.6 5 | 6 | defaults: &defaults 7 | docker: 8 | - image: cimg/node:20.10-browsers 9 | working_directory: ~/puppeteer-devtools 10 | 11 | commands: 12 | install_chrome: 13 | parameters: 14 | chrome-version: 15 | type: string 16 | default: "latest" 17 | steps: 18 | - run: sudo apt-get update 19 | - browser-tools/install-chrome: 20 | chrome-version: << parameters.chrome-version >> 21 | - run: 22 | command: | 23 | google-chrome --version 24 | name: Google Chrome Version 25 | 26 | npm_cache_key: &npm_cache_key 27 | v2-node-modules-cache-{{ checksum "package-lock.json" }} 28 | 29 | restore_node_modules_cache: &restore_node_modules_cache 30 | restore_cache: 31 | keys: 32 | - *npm_cache_key 33 | - v2-node-modules-cache- 34 | 35 | npm_auth: &npm_auth 36 | run: 37 | name: npm auth 38 | command: npm config set "//registry.npmjs.org/:_authToken" $NPM_AUTH 39 | 40 | jobs: 41 | dependencies: 42 | <<: *defaults 43 | steps: 44 | - checkout 45 | - <<: *restore_node_modules_cache 46 | # Skip the bundled version of chrome; always use the one provided from circle 47 | - run: PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm ci 48 | - save_cache: 49 | paths: 50 | - node_modules 51 | key: *npm_cache_key 52 | test: 53 | <<: *defaults 54 | parameters: 55 | chrome-version: 56 | type: string 57 | steps: 58 | - install_chrome: 59 | chrome-version: << parameters.chrome-version >> 60 | - checkout 61 | - <<: *restore_node_modules_cache 62 | - run: PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome npm run coverage 63 | lint: 64 | <<: *defaults 65 | steps: 66 | - checkout 67 | - <<: *restore_node_modules_cache 68 | - run: npm run lint 69 | release_next: 70 | <<: *defaults 71 | steps: 72 | - checkout 73 | - <<: *restore_node_modules_cache 74 | - <<: *npm_auth 75 | # Tag develop commits with commit hash and push out with next tag 76 | - run: npm version "$(node -p 'require("./package.json").version')-next-${CIRCLE_SHA1:0:8}" --no-git-tag-version 77 | - run: npm publish --tag next 78 | release: 79 | <<: *defaults 80 | steps: 81 | - checkout 82 | - <<: *restore_node_modules_cache 83 | - <<: *npm_auth 84 | - run: npm publish 85 | 86 | workflows: 87 | build: 88 | jobs: 89 | - dependencies 90 | - test: 91 | name: "test-chrome-<< matrix.chrome-version >>" 92 | matrix: 93 | parameters: 94 | chrome-version: ["latest", "111.0.5563.146"] 95 | requires: 96 | - dependencies 97 | - lint: 98 | requires: 99 | - dependencies 100 | - release: 101 | requires: 102 | - test 103 | - lint 104 | filters: 105 | branches: 106 | only: 107 | - master 108 | - release_next: 109 | requires: 110 | - test 111 | - lint 112 | filters: 113 | branches: 114 | only: 115 | - develop 116 | 117 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. 4 | 5 | ## [3.3.0](https://github.com/dequelabs/puppeteer-devtools/compare/v3.2.0...v3.3.0) (2024-04-04) 6 | 7 | 8 | ### Features 9 | 10 | * add support for manifest v3 extensions and background service workers ([#81](https://github.com/dequelabs/puppeteer-devtools/issues/81)) ([0608018](https://github.com/dequelabs/puppeteer-devtools/commit/06080187a19c13bc664eeff71074ae2084cc673c)) 11 | 12 | ## [3.2.0](https://github.com/dequelabs/puppeteer-devtools/compare/v3.1.0...v3.2.0) (2024-02-05) 13 | 14 | 15 | ### Features 16 | 17 | * support changes implemented in devtools frontend api in newer versions of chrome ([#74](https://github.com/dequelabs/puppeteer-devtools/issues/74)) ([e013f8a](https://github.com/dequelabs/puppeteer-devtools/commit/e013f8aa39c0e80a183aeed350155eadf0891ecc)) 18 | 19 | ## [3.1.0](https://github.com/dequelabs/puppeteer-devtools/compare/v3.0.0...v3.1.0) (2023-07-13) 20 | 21 | ### Features 22 | 23 | - upgrade puppeteer to 14.1.1 ([#70](https://github.com/dequelabs/puppeteer-devtools/issues/70)) ([56abb8d](https://github.com/dequelabs/puppeteer-devtools/commit/56abb8d8769a37f4eca346bac15d66c34bb28ffd)) 24 | 25 | ### Bug Fixes 26 | 27 | - correct puppeteer imports ([#71](https://github.com/dequelabs/puppeteer-devtools/issues/71)) ([da93565](https://github.com/dequelabs/puppeteer-devtools/commit/da935658143d6c90dabc901ad493205346d322f3)) 28 | 29 | ## [3.0.0](https://github.com/dequelabs/puppeteer-devtools/compare/v2.0.1...v3.0.0) (2022-02-10) 30 | 31 | ### ⚠ BREAKING CHANGES 32 | 33 | - Updates internal method used to access/control extension panels, rolling to puppeteer@^9 34 | 35 | ### Features 36 | 37 | - supports getting background page ([#55](https://github.com/dequelabs/puppeteer-devtools/issues/55)) ([65881a1](https://github.com/dequelabs/puppeteer-devtools/commit/65881a1e5f891e5fe4163b574da40aa73e1fa161)) 38 | - update puppeteer to 9.1.1 ([#50](https://github.com/dequelabs/puppeteer-devtools/issues/50)) ([8390e70](https://github.com/dequelabs/puppeteer-devtools/commit/8390e70d8384cc0e3c306dae4bf0debcca85e7e9)) 39 | 40 | ### [2.0.1](https://github.com/dequelabs/puppeteer-devtools/compare/v2.0.0...v2.0.1) (2021-04-02) 41 | 42 | ### Bug Fixes 43 | 44 | - only return the execution context for the top most frame ([#37](https://github.com/dequelabs/puppeteer-devtools/issues/37)) ([cdf4945](https://github.com/dequelabs/puppeteer-devtools/commit/cdf4945d7ddead16d92249132ce859052a8c291d)) 45 | 46 | ## [2.0.0](https://github.com/dequelabs/puppeteer-devtools/compare/v1.0.1...v2.0.0) (2021-01-22) 47 | 48 | ### ⚠ BREAKING CHANGES 49 | 50 | - This functionality depends on newer versions of puppeteer (> 5.1.0) 51 | 52 | ### Features 53 | 54 | - add ability to get an extension's content script execution context ([#31](https://github.com/dequelabs/puppeteer-devtools/issues/31)) ([8147349](https://github.com/dequelabs/puppeteer-devtools/commit/81473491ffb2f79b44720ea427cf08ff483b94b5)) 55 | - set minimum node version to 12 ([#28](https://github.com/dequelabs/puppeteer-devtools/issues/28)) ([d93df4f](https://github.com/dequelabs/puppeteer-devtools/commit/d93df4f83912773a1e95b46b9dc0bf98ddd534cf)) 56 | 57 | ### [1.0.1](https://github.com/dequelabs/puppeteer-devtools/compare/v1.0.0...v1.0.1) (2020-07-15) 58 | 59 | ### Bug Fixes 60 | 61 | - fix for UI.viewManager sometimes not being ready in devtools context ([#19](https://github.com/dequelabs/puppeteer-devtools/issues/19)) ([6de63b6](https://github.com/dequelabs/puppeteer-devtools/commit/6de63b66038614d0fe40ad06fa3f0456fd3fdc41)) 62 | 63 | ## 1.0.0 (2020-04-06) 64 | 65 | ### Features 66 | 67 | - initial release ([#1](https://github.com/dequelabs/puppeteer-devtools/issues/1)) ([c8da1a7](https://github.com/dequelabs/puppeteer-devtools/commit/c8da1a7d0e4c2c751d36f247cbf077b36a22dadd)) 68 | -------------------------------------------------------------------------------- /test/test.ts: -------------------------------------------------------------------------------- 1 | import assert from 'assert' 2 | import puppeteer from 'puppeteer' 3 | import path from 'path' 4 | import fs from 'fs' 5 | import { 6 | setCaptureContentScriptExecutionContexts, 7 | getContentScriptExcecutionContext, 8 | getDevtools, 9 | getDevtoolsPanel, 10 | getBackground 11 | } from '../src' 12 | 13 | beforeEach(async function () { 14 | try { 15 | const pathToExtension = path.resolve(__dirname, 'extension') 16 | 17 | const browser = await puppeteer.launch({ 18 | args: [ 19 | `--disable-extensions-except=${pathToExtension}`, 20 | `--load-extension=${pathToExtension}` 21 | ], 22 | defaultViewport: null, 23 | devtools: true, 24 | headless: false 25 | }) 26 | 27 | const [page] = await browser.pages() 28 | 29 | // Respond to http://testpage urls with a set fixture page 30 | await page.setRequestInterception(true) 31 | page.on('request', async request => { 32 | if (request.url() === 'http://testpage.test/frame') { 33 | const body = fs.readFileSync( 34 | path.resolve(__dirname, 'fixtures/frame.html') 35 | ) 36 | return request.respond({ 37 | body, 38 | contentType: 'text/html', 39 | status: 200 40 | }) 41 | } 42 | if (request.url().startsWith('http://testpage')) { 43 | const body = fs.readFileSync( 44 | path.resolve(__dirname, 'fixtures/index.html') 45 | ) 46 | return request.respond({ 47 | body, 48 | contentType: 'text/html', 49 | status: 200 50 | }) 51 | } 52 | return request.continue() 53 | }) 54 | 55 | this.context = { 56 | browser, 57 | page 58 | } 59 | } catch (ex) { 60 | console.log(`Did not launch browser: ${(ex as Error).message}`) 61 | } 62 | }) 63 | 64 | afterEach(async function() { 65 | const { browser } = this.context 66 | if (browser) { 67 | await browser.close() 68 | } 69 | this.context = null 70 | }) 71 | 72 | describe('puppeteer-devtools', () => { 73 | 74 | it('should return devtools page', async function() { 75 | const { page } = this.context 76 | const devtools = await getDevtools(page) 77 | assert.match(await devtools.url(), /^devtools:\/\//) 78 | }) 79 | 80 | it('should return background page', async function() { 81 | const { page } = this.context 82 | const background = await getBackground(page) 83 | assert.match(await background?.url(), /_generated_background_page/) 84 | }) 85 | 86 | it('should return devtools panel', async function() { 87 | const { page } = this.context 88 | const devtools = await getDevtoolsPanel(page) 89 | const body = await devtools.$('body') 90 | const textContent = await devtools.evaluate(el => el?.textContent, body) 91 | assert.equal(textContent?.trim(), 'devtools panel') 92 | }) 93 | 94 | it('should throw with no matching strategies for showing devtools panel', async function() { 95 | const { page } = this.context 96 | const devtools = await getDevtools(page) 97 | // remove known chrome public apis to force errors 98 | await devtools.evaluate(` 99 | delete window.UI 100 | delete window.InspectorFrontendAPI 101 | `) 102 | await assert.rejects(getDevtoolsPanel(page, { timeout: 100 }), (err: Error) => { 103 | assert.match(err.message, /Unable to find view manager for browser executable/) 104 | return true 105 | }) 106 | }) 107 | 108 | it('should return extension content script execution context', async function() { 109 | const { page } = this.context 110 | await setCaptureContentScriptExecutionContexts(page) 111 | await page.goto('http://testpage.test', { waitUntil: 'networkidle2' }) 112 | const contentExecutionContext = await getContentScriptExcecutionContext(page) 113 | const mainFrameContext = await page.evaluate( 114 | () => (window as any).extension_content_script 115 | ) 116 | const contentContext = await contentExecutionContext.evaluate( 117 | () => (window as any).extension_content_script 118 | ) 119 | assert.equal(typeof mainFrameContext, 'undefined') 120 | assert(contentContext) 121 | }) 122 | 123 | it('should throw error when unable to find content script execution context', async function() { 124 | const { page } = this.context 125 | await page.goto('http://testpage.test', { waitUntil: 'networkidle2' }) 126 | assert.rejects(async () => await getContentScriptExcecutionContext(page)) 127 | }) 128 | 129 | it('should throw error when unable to find content script execution context on page without permissions', async function() { 130 | const { page } = this.context 131 | await setCaptureContentScriptExecutionContexts(page) 132 | await page.goto('http://testpage.test/that/does/not/have/permission', { 133 | waitUntil: 'networkidle2' 134 | }) 135 | assert.rejects(async () => await getContentScriptExcecutionContext(page)) 136 | }) 137 | 138 | it('should throw error when unable to find devtools panel', async function() { 139 | const { page } = this.context 140 | assert.rejects(async () => 141 | getDevtoolsPanel(page, { panelName: 'foo.html', timeout: 500 }) 142 | ) 143 | }) 144 | 145 | }) -------------------------------------------------------------------------------- /test/test-manifest-v3.ts: -------------------------------------------------------------------------------- 1 | import assert from 'assert' 2 | import puppeteer from 'puppeteer' 3 | import path from 'path' 4 | import fs from 'fs' 5 | import { 6 | setCaptureContentScriptExecutionContexts, 7 | getContentScriptExcecutionContext, 8 | getDevtools, 9 | getDevtoolsPanel, 10 | getBackground 11 | } from '../src' 12 | 13 | beforeEach(async function () { 14 | try { 15 | const pathToExtension = path.resolve(__dirname, 'extension-manifest-v3') 16 | 17 | const browser = await puppeteer.launch({ 18 | args: [ 19 | `--disable-extensions-except=${pathToExtension}`, 20 | `--load-extension=${pathToExtension}` 21 | ], 22 | defaultViewport: null, 23 | devtools: true, 24 | headless: false 25 | }) 26 | 27 | const [page] = await browser.pages() 28 | 29 | // Respond to http://testpage urls with a set fixture page 30 | await page.setRequestInterception(true) 31 | page.on('request', async request => { 32 | if (request.url() === 'http://testpage.test/frame') { 33 | const body = fs.readFileSync( 34 | path.resolve(__dirname, 'fixtures/frame.html') 35 | ) 36 | return request.respond({ 37 | body, 38 | contentType: 'text/html', 39 | status: 200 40 | }) 41 | } 42 | if (request.url().startsWith('http://testpage')) { 43 | const body = fs.readFileSync( 44 | path.resolve(__dirname, 'fixtures/index.html') 45 | ) 46 | return request.respond({ 47 | body, 48 | contentType: 'text/html', 49 | status: 200 50 | }) 51 | } 52 | return request.continue() 53 | }) 54 | 55 | this.manifestV3context = { 56 | browser, 57 | page 58 | } 59 | } catch (ex) { 60 | console.log(`Did not launch browser: ${(ex as Error).message}`) 61 | } 62 | }) 63 | 64 | afterEach(async function() { 65 | const { browser } = this.manifestV3context 66 | if (browser) { 67 | await browser.close() 68 | } 69 | this.manifestV3context = null 70 | }) 71 | 72 | describe('puppeteer-devtools (manifest v3)', () => { 73 | 74 | it('should return devtools page', async function() { 75 | const { page } = this.manifestV3context 76 | const devtools = await getDevtools(page) 77 | assert.match(await devtools.url(), /^devtools:\/\//) 78 | }) 79 | 80 | it('should return background page', async function() { 81 | const { page } = this.manifestV3context 82 | const background = await getBackground(page) 83 | assert.match(await background?.url(), /background.js$/) 84 | }) 85 | 86 | it('should return devtools panel', async function() { 87 | const { page } = this.manifestV3context 88 | const devtools = await getDevtoolsPanel(page) 89 | const body = await devtools.$('body') 90 | const textContent = await devtools.evaluate(el => el?.textContent, body) 91 | assert.equal(textContent?.trim(), 'devtools panel') 92 | }) 93 | 94 | it('should throw with no matching strategies for showing devtools panel', async function() { 95 | const { page } = this.manifestV3context 96 | const devtools = await getDevtools(page) 97 | // remove known chrome public apis to force errors 98 | await devtools.evaluate(` 99 | delete window.UI 100 | delete window.InspectorFrontendAPI 101 | `) 102 | await assert.rejects(getDevtoolsPanel(page, { timeout: 100 }), (err: Error) => { 103 | assert.match(err.message, /Unable to find view manager for browser executable/) 104 | return true 105 | }) 106 | }) 107 | 108 | it('should return extension content script execution context', async function() { 109 | const { page } = this.manifestV3context 110 | await setCaptureContentScriptExecutionContexts(page) 111 | await page.goto('http://testpage.test', { waitUntil: 'networkidle2' }) 112 | const contentExecutionContext = await getContentScriptExcecutionContext(page) 113 | const mainFrameContext = await page.evaluate( 114 | () => (window as any).extension_content_script 115 | ) 116 | const contentContext = await contentExecutionContext.evaluate( 117 | () => (window as any).extension_content_script 118 | ) 119 | assert.equal(typeof mainFrameContext, 'undefined') 120 | assert(contentContext) 121 | }) 122 | 123 | it('should throw error when unable to find content script execution context', async function() { 124 | const { page } = this.manifestV3context 125 | await page.goto('http://testpage.test', { waitUntil: 'networkidle2' }) 126 | assert.rejects(async () => await getContentScriptExcecutionContext(page)) 127 | }) 128 | 129 | it('should throw error when unable to find content script execution context on page without permissions', async function() { 130 | const { page } = this.manifestV3context 131 | await setCaptureContentScriptExecutionContexts(page) 132 | await page.goto('http://testpage.test/that/does/not/have/permission', { 133 | waitUntil: 'networkidle2' 134 | }) 135 | assert.rejects(async () => await getContentScriptExcecutionContext(page)) 136 | }) 137 | 138 | it('should throw error when unable to find devtools panel', async function() { 139 | const { page } = this.manifestV3context 140 | assert.rejects(async () => 141 | getDevtoolsPanel(page, { panelName: 'foo.html', timeout: 500 }) 142 | ) 143 | }) 144 | 145 | }) -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # puppeteer-devtools 2 | 3 | [![CircleCI](https://circleci.com/gh/dequelabs/puppeteer-devtools.svg?style=shield)](https://circleci.com/gh/dequelabs/puppeteer-devtools) 4 | [![Version](https://img.shields.io/npm/v/puppeteer-devtools.svg)](https://www.npmjs.com/package/puppeteer-devtools) 5 | 6 | Extended puppeteer methods for getting extension devtools contexts. 7 | 8 | > This package relies on using internal puppeteer methods to return the Chrome devtools panel, along with extension panels. Since it is dependent on undocumented puppeteer apis, it could break in future versions of Chrome/puppeteer so use at your own risk. 9 | 10 | ## Install 11 | 12 | `npm install --save-dev puppeteer-devtools` 13 | 14 | ## Usage 15 | 16 | ```js 17 | const puppeteer = require('puppeteer') 18 | const { 19 | getDevtoolsPanel, 20 | setCaptureContentScriptExecutionContexts, 21 | getContentScriptExcecutionContext 22 | } = require('puppeteer-devtools') 23 | const path = require('path') 24 | 25 | const extension = path.resolve('/path/to/extension') 26 | 27 | const browser = await puppeteer.launch({ 28 | args: [ 29 | `--disable-extensions-except=${extension}`, 30 | `--load-extension=${extension}` 31 | ], 32 | devtools: true, 33 | headless: false 34 | }) 35 | 36 | const [page] = await browser.pages() 37 | await setCaptureContentScriptExecutionContexts(page) 38 | 39 | await page.goto('https://google.com', { waitUntil: 'networkidle0' }) 40 | const panel = await getDevtoolsPanel(page, { panelName: 'panel.html' }) 41 | const contentScriptExecutionContext = await getContentScriptExecutionContext( 42 | page 43 | ) 44 | ``` 45 | 46 | Note: `devtools` must be enabled, and `headless` mode must be turned off. Chrome [does not currently support extensions in headless mode](https://bugs.chromium.org/p/chromium/issues/detail?id=706008). 47 | 48 | ### Using a different browser executable 49 | 50 | `puppeteer-devtools` currently is [limited to versions of puppeteer < `16.1.0`](https://github.com/dequelabs/puppeteer-devtools/issues/67#issuecomment-1629700824), meaning that in order to use versions of Chrome that are newer than the packaged version, you must use some variation of executable path: 51 | 52 | #### `browser.launch` 53 | 54 | ```ts 55 | await puppeteer.launch({ 56 | ...options, 57 | executablePath: '/path/to/chrome' 58 | }) 59 | ``` 60 | 61 | #### Env Var 62 | 63 | ```sh 64 | PUPPETEER_EXECUTABLE_PATH=/path/to/chrome npm run tests 65 | ``` 66 | 67 | ## Methods 68 | 69 | ### `async getDevtools( page, options? )` 70 | 71 | Returns the underlying Chrome `devtools://` page as a Promise<[Page](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page)>. 72 | 73 | - **`page`** - <[`Page`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page)> Puppeteer page object. 74 | - **`options`** - <`object`> 75 | - **`timeout`** - <`number | null`> Maximum time in milliseconds to wait for the devtools page to become available. Uses puppeteer's default timeout if not set. 76 | 77 | ### `async getDevtoolsPanel( page, options? )` 78 | 79 | Returns the underlying Chrome `chrome-extension://` panel as a Promise<[Frame](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-frame)>. 80 | 81 | - **`page`** - <[`Page`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page)> Puppeteer page object. 82 | - **`options`** - <`object`> 83 | - **`panelName`** - <`string`> The file name of the extension panel to find. A devtools page with `chrome.devtools.panels.create('name', 'icon.png', 'panel.html', (panel) => { ... })` would have `panel.html` as its value. 84 | - **`timeout`** - <`number | null`> Maximum time in milliseconds to wait for the chrome extension panel to become available. Uses puppeteer's default timeout if not set. 85 | 86 | ### `async getBackground( page, options? )` 87 | 88 | Returns the underlying Chrome background page as a Promise<[Page](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page)>. 89 | 90 | - **`page`** - <[`Page`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page)> Puppeteer page object. 91 | - **`options`** - <`object`> 92 | - **`timeout`** - <`number | null`> Maximum time in milliseconds to wait for the background page to become available. Uses puppeteer's default timeout if not set. 93 | 94 | ### `async setCaptureContentScriptExecutionContexts( page )` 95 | 96 | Activating capture content script execution contexts will allow for the usage of an extension's content script [`ExecutionContext`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#class-executioncontext). This must be activated before a page is navigated. 97 | 98 | - **`page`** - <[`Page`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page)> Puppeteer page object. 99 | 100 | ### `async getContentScriptExcecutionContext( page )` 101 | 102 | If `setCaptureContentScriptExecutionContexts` has been enabled for a page, this returns the extension's content script [`ExecutionContext`](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#class-executioncontext). This will error for pages that the extension does not have permissions for or for extensions that do not have content scripts. 103 | 104 | - **`page`** - <[`Page`](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-page)> Puppeteer page object. 105 | 106 | ## License 107 | 108 | [MPL 2.0](LICENSE) 109 | 110 | ## Copyright 111 | 112 | Copyright (c) 2019-2024 Deque Systems, Inc. 113 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | /*! puppeteer-devtools 2 | * Copyright (c) 2019-2021 Deque Systems, Inc. 3 | * 4 | * Your use of this Source Code Form is subject to the terms of the Mozilla Public 5 | * License, v. 2.0. If a copy of the MPL was not distributed with this 6 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. 7 | * 8 | * This entire copyright notice must appear in every copy of this file you 9 | * distribute or in any file that contains substantial portions of this source 10 | * code. 11 | */ 12 | import { Page, WebWorker, Frame, Target, errors } from 'puppeteer' 13 | import { 14 | DOMWorld, 15 | ExecutionContext, 16 | ExecutionContextDescription, 17 | CDPSession 18 | } from './puppeteer-adapter' 19 | 20 | const devtoolsUrl = 'devtools://' 21 | const extensionUrl = 'chrome-extension://' 22 | const types = { 23 | page: 'page', 24 | serviceWorker: 'service_worker' 25 | } 26 | 27 | const isDevtools = (target: Target) => { 28 | return target.url().startsWith(devtoolsUrl) 29 | } 30 | const isBackground = (target: Target) => { 31 | const url = target.url() 32 | return ( 33 | url.startsWith(extensionUrl) && (url.includes('generated_background_page') || target.type() === types.serviceWorker) 34 | ) 35 | } 36 | const isPage = (target: Page | WebWorker): target is Page => { 37 | // When $ exists, it's most likely a page... 38 | return '$' in target && typeof target.$ === 'function' 39 | } 40 | 41 | async function getContext( 42 | page: Page, 43 | isTarget: (t: Target) => boolean, 44 | options?: { timeout?: number } 45 | ): Promise { 46 | const browser = page.browser() 47 | const { timeout } = options || {} 48 | 49 | const target = await browser.waitForTarget(isTarget, { timeout }) 50 | const type = target.type() 51 | const url = target.url() 52 | 53 | if (type === types.serviceWorker) { 54 | const worker = await target.worker() 55 | if (!worker) { 56 | /* istanbul ignore next */ 57 | throw new Error(`Could not convert "${url}" target to a worker.`) 58 | } 59 | 60 | return worker 61 | } else { 62 | let contextPage: Page | null 63 | 64 | /* istanbul ignore next */ 65 | if ('asPage' in target && typeof target.asPage === 'function') { 66 | contextPage = await target.asPage() 67 | } else { 68 | // Hack to get puppeteer to allow us to access the page context 69 | ;(target as any)._targetInfo.type = types.page 70 | contextPage = await target.page() 71 | } 72 | 73 | if (!contextPage) { 74 | /* istanbul ignore next */ 75 | throw new Error(`Could not convert "${url}" target to a page.`) 76 | } 77 | 78 | await contextPage.waitForFunction( 79 | /* istanbul ignore next */ 80 | () => document.readyState === 'complete', 81 | { timeout } 82 | ) 83 | 84 | return contextPage 85 | } 86 | } 87 | 88 | async function getDevtools( 89 | page: Page, 90 | options?: { timeout?: number } 91 | ): Promise { 92 | const context = await getContext(page, isDevtools, options) 93 | 94 | if (!isPage(context)) { 95 | /* istanbul ignore next */ 96 | throw new Error(`Devtools target "${page.url()}" is not of type page.`) 97 | } 98 | 99 | return context 100 | } 101 | 102 | async function getBackground( 103 | page: Page, 104 | options?: { timeout?: number } 105 | ): Promise { 106 | return getContext(page, isBackground, options) 107 | } 108 | 109 | // Chrome has different methodologies for view management depending on the version, 110 | // we need to determine the right strategy for what's available in the current chrome executable 111 | // reference links: 112 | // - https://github.com/ChromeDevTools/devtools-frontend/blob/main/front_end/ui/legacy/ViewManager.ts 113 | // - https://github.com/ChromeDevTools/devtools-frontend/blob/main/front_end/devtools_compatibility.js 114 | const devtoolsViewManagementStrategies = [ 115 | { strategy: 'ui-viewmanager', func: `!!('UI' in window && 'viewManager' in UI && typeof UI.viewManager.showPanel === 'function')` }, 116 | { strategy: 'inspectorfrontendapi', func: `!!('InspectorFrontendAPI' in window && 'showPanel' in InspectorFrontendAPI && typeof InspectorFrontendAPI.showPanel === 'function')`} 117 | ] as const 118 | type DevtoolsViewManagementStrategies = typeof devtoolsViewManagementStrategies[number]['strategy'] 119 | 120 | async function getDevtoolsPanel( 121 | page: Page, 122 | options?: { panelName?: string; timeout?: number } 123 | ): Promise { 124 | const browser = page.browser() 125 | const { panelName = 'panel.html', timeout = 30000 } = options || {} 126 | 127 | const devtools = await getDevtools(page) 128 | 129 | let extensionPanelTarget: Target 130 | 131 | try { 132 | // Wait for one of the view management strategies to be available 133 | let strategy: DevtoolsViewManagementStrategies | void = undefined 134 | try { 135 | strategy = await Promise.race([ 136 | ...devtoolsViewManagementStrategies.map(async ({ strategy, func }) => { 137 | await devtools.waitForFunction(func, { timeout }) 138 | return strategy 139 | }) 140 | ]) 141 | } catch (err) { 142 | /* istanbul ignore next */ 143 | if (!(err instanceof errors.TimeoutError)) { 144 | throw err 145 | } 146 | } 147 | 148 | if (!strategy) { 149 | throw new Error(`[${await page.browser().version()}] Unable to find view manager for browser executable.`) 150 | } 151 | 152 | // Check that there is an available chrome-extension panel target 153 | // source: https://github.com/ChromeDevTools/devtools-frontend/blob/main/front_end/ui/legacy/ViewManager.ts 154 | await devtools.waitForFunction(`!!('UI' in window && 'panels' in UI)`, { timeout }) 155 | await devtools.waitForFunction( 156 | ` 157 | !!Object.keys(UI.panels) 158 | .find(key => key.startsWith('${extensionUrl}')) 159 | `, 160 | { timeout } 161 | ) 162 | const extensionPanelView = await devtools.evaluate( 163 | ` 164 | Object.keys(UI.panels) 165 | .find(key => key.startsWith('${extensionUrl}')) 166 | `, 167 | { timeout } 168 | ) 169 | 170 | /* istanbul ignore next */ 171 | switch(strategy) { 172 | case 'ui-viewmanager': 173 | await devtools.evaluate(`UI.viewManager.showView('${extensionPanelView}')`) 174 | break; 175 | case 'inspectorfrontendapi': 176 | await devtools.evaluate(`InspectorFrontendAPI.showPanel('${extensionPanelView}')`) 177 | break; 178 | /* istanbul ignore next */ 179 | default: { 180 | const unknownStrategy: never = strategy; 181 | throw new Error(`Unknown strategy: ${unknownStrategy}`); 182 | } 183 | } 184 | 185 | extensionPanelTarget = await browser.waitForTarget( 186 | target => { 187 | return ( 188 | target.url().startsWith(extensionUrl) && 189 | target.url().endsWith(panelName) 190 | ) 191 | }, 192 | { timeout } 193 | ) 194 | } catch (err) { 195 | if (err instanceof errors.TimeoutError) { 196 | throw new errors.TimeoutError( 197 | `Could not find "${extensionUrl}" target within timeout of ${timeout}ms` 198 | ) 199 | } 200 | 201 | throw err 202 | } 203 | 204 | let panel: Page | null 205 | /* istanbul ignore next */ 206 | if ('asPage' in extensionPanelTarget && typeof extensionPanelTarget.asPage === 'function') { 207 | panel = await extensionPanelTarget.asPage() 208 | } else { 209 | // Hack to get puppeteer to allow us to access the page context 210 | ;(extensionPanelTarget as any)._targetInfo.type = types.page 211 | panel = await extensionPanelTarget.page() 212 | } 213 | 214 | if (!panel) { 215 | /* istanbul ignore next */ 216 | throw new Error(`Could not convert "${extensionPanelTarget.url()}" target to a page.`) 217 | } 218 | 219 | // The extension panel should be the first embedded frame of the targeted page 220 | const [panelFrame] = await panel.frames() 221 | 222 | return panelFrame 223 | } 224 | 225 | const executionContexts = new Map() 226 | async function setCaptureExecutionContexts( 227 | page: Page, 228 | predicate: (context: ExecutionContextDescription) => boolean 229 | ) { 230 | const client = await page.target().createCDPSession() 231 | const onExecutionContextCreated = async ({ 232 | context 233 | }: { 234 | context: ExecutionContextDescription 235 | }) => { 236 | if (predicate(context)) { 237 | executionContexts.set(page, context) 238 | } 239 | } 240 | await client.send('Runtime.enable') 241 | client.on('Runtime.executionContextCreated', onExecutionContextCreated) 242 | } 243 | 244 | async function setCaptureContentScriptExecutionContexts(page: Page) { 245 | await setCaptureExecutionContexts( 246 | page, 247 | context => 248 | context.origin.startsWith(extensionUrl) && 249 | (page.mainFrame() as any)._id === context.auxData.frameId 250 | ) 251 | } 252 | 253 | async function getContentScriptExcecutionContext( 254 | page: Page 255 | ): Promise { 256 | const executionContext = executionContexts.get(page) 257 | 258 | if (!executionContext) { 259 | throw new Error( 260 | `Could not find "${extensionUrl}" content script execution context` 261 | ) 262 | } 263 | 264 | const client = await page.target().createCDPSession() 265 | return new ExecutionContext( 266 | client as unknown as CDPSession, 267 | executionContext, 268 | // DOMWorld is used to return the associated frame. Extension execution 269 | // contexts don't have an associated frame, so this can be safely ignored 270 | // see: https://github.com/puppeteer/puppeteer/blob/9dd1aa302d719bef29e67c33f1f4717f1c0e2b79/src/common/ExecutionContext.ts#L73-L84 271 | null as unknown as DOMWorld 272 | ) 273 | } 274 | 275 | export { 276 | getDevtools, 277 | getDevtoolsPanel, 278 | getBackground, 279 | setCaptureContentScriptExecutionContexts, 280 | getContentScriptExcecutionContext 281 | } 282 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Mozilla Public License, version 2.0 2 | 3 | 1. Definitions 4 | 5 | 1.1. "Contributor" 6 | 7 | means each individual or legal entity that creates, contributes to the 8 | creation of, or owns Covered Software. 9 | 10 | 1.2. "Contributor Version" 11 | 12 | means the combination of the Contributions of others (if any) used by a 13 | Contributor and that particular Contributor's Contribution. 14 | 15 | 1.3. "Contribution" 16 | 17 | means Covered Software of a particular Contributor. 18 | 19 | 1.4. "Covered Software" 20 | 21 | means Source Code Form to which the initial Contributor has attached the 22 | notice in Exhibit A, the Executable Form of such Source Code Form, and 23 | Modifications of such Source Code Form, in each case including portions 24 | thereof. 25 | 26 | 1.5. "Incompatible With Secondary Licenses" 27 | means 28 | 29 | a. that the initial Contributor has attached the notice described in 30 | Exhibit B to the Covered Software; or 31 | 32 | b. that the Covered Software was made available under the terms of 33 | version 1.1 or earlier of the License, but not also under the terms of 34 | a Secondary License. 35 | 36 | 1.6. "Executable Form" 37 | 38 | means any form of the work other than Source Code Form. 39 | 40 | 1.7. "Larger Work" 41 | 42 | means a work that combines Covered Software with other material, in a 43 | separate file or files, that is not Covered Software. 44 | 45 | 1.8. "License" 46 | 47 | means this document. 48 | 49 | 1.9. "Licensable" 50 | 51 | means having the right to grant, to the maximum extent possible, whether 52 | at the time of the initial grant or subsequently, any and all of the 53 | rights conveyed by this License. 54 | 55 | 1.10. "Modifications" 56 | 57 | means any of the following: 58 | 59 | a. any file in Source Code Form that results from an addition to, 60 | deletion from, or modification of the contents of Covered Software; or 61 | 62 | b. any new file in Source Code Form that contains any Covered Software. 63 | 64 | 1.11. "Patent Claims" of a Contributor 65 | 66 | means any patent claim(s), including without limitation, method, 67 | process, and apparatus claims, in any patent Licensable by such 68 | Contributor that would be infringed, but for the grant of the License, 69 | by the making, using, selling, offering for sale, having made, import, 70 | or transfer of either its Contributions or its Contributor Version. 71 | 72 | 1.12. "Secondary License" 73 | 74 | means either the GNU General Public License, Version 2.0, the GNU Lesser 75 | General Public License, Version 2.1, the GNU Affero General Public 76 | License, Version 3.0, or any later versions of those licenses. 77 | 78 | 1.13. "Source Code Form" 79 | 80 | means the form of the work preferred for making modifications. 81 | 82 | 1.14. "You" (or "Your") 83 | 84 | means an individual or a legal entity exercising rights under this 85 | License. For legal entities, "You" includes any entity that controls, is 86 | controlled by, or is under common control with You. For purposes of this 87 | definition, "control" means (a) the power, direct or indirect, to cause 88 | the direction or management of such entity, whether by contract or 89 | otherwise, or (b) ownership of more than fifty percent (50%) of the 90 | outstanding shares or beneficial ownership of such entity. 91 | 92 | 93 | 2. License Grants and Conditions 94 | 95 | 2.1. Grants 96 | 97 | Each Contributor hereby grants You a world-wide, royalty-free, 98 | non-exclusive license: 99 | 100 | a. under intellectual property rights (other than patent or trademark) 101 | Licensable by such Contributor to use, reproduce, make available, 102 | modify, display, perform, distribute, and otherwise exploit its 103 | Contributions, either on an unmodified basis, with Modifications, or 104 | as part of a Larger Work; and 105 | 106 | b. under Patent Claims of such Contributor to make, use, sell, offer for 107 | sale, have made, import, and otherwise transfer either its 108 | Contributions or its Contributor Version. 109 | 110 | 2.2. Effective Date 111 | 112 | The licenses granted in Section 2.1 with respect to any Contribution 113 | become effective for each Contribution on the date the Contributor first 114 | distributes such Contribution. 115 | 116 | 2.3. Limitations on Grant Scope 117 | 118 | The licenses granted in this Section 2 are the only rights granted under 119 | this License. No additional rights or licenses will be implied from the 120 | distribution or licensing of Covered Software under this License. 121 | Notwithstanding Section 2.1(b) above, no patent license is granted by a 122 | Contributor: 123 | 124 | a. for any code that a Contributor has removed from Covered Software; or 125 | 126 | b. for infringements caused by: (i) Your and any other third party's 127 | modifications of Covered Software, or (ii) the combination of its 128 | Contributions with other software (except as part of its Contributor 129 | Version); or 130 | 131 | c. under Patent Claims infringed by Covered Software in the absence of 132 | its Contributions. 133 | 134 | This License does not grant any rights in the trademarks, service marks, 135 | or logos of any Contributor (except as may be necessary to comply with 136 | the notice requirements in Section 3.4). 137 | 138 | 2.4. Subsequent Licenses 139 | 140 | No Contributor makes additional grants as a result of Your choice to 141 | distribute the Covered Software under a subsequent version of this 142 | License (see Section 10.2) or under the terms of a Secondary License (if 143 | permitted under the terms of Section 3.3). 144 | 145 | 2.5. Representation 146 | 147 | Each Contributor represents that the Contributor believes its 148 | Contributions are its original creation(s) or it has sufficient rights to 149 | grant the rights to its Contributions conveyed by this License. 150 | 151 | 2.6. Fair Use 152 | 153 | This License is not intended to limit any rights You have under 154 | applicable copyright doctrines of fair use, fair dealing, or other 155 | equivalents. 156 | 157 | 2.7. Conditions 158 | 159 | Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted in 160 | Section 2.1. 161 | 162 | 163 | 3. Responsibilities 164 | 165 | 3.1. Distribution of Source Form 166 | 167 | All distribution of Covered Software in Source Code Form, including any 168 | Modifications that You create or to which You contribute, must be under 169 | the terms of this License. You must inform recipients that the Source 170 | Code Form of the Covered Software is governed by the terms of this 171 | License, and how they can obtain a copy of this License. You may not 172 | attempt to alter or restrict the recipients' rights in the Source Code 173 | Form. 174 | 175 | 3.2. Distribution of Executable Form 176 | 177 | If You distribute Covered Software in Executable Form then: 178 | 179 | a. such Covered Software must also be made available in Source Code Form, 180 | as described in Section 3.1, and You must inform recipients of the 181 | Executable Form how they can obtain a copy of such Source Code Form by 182 | reasonable means in a timely manner, at a charge no more than the cost 183 | of distribution to the recipient; and 184 | 185 | b. You may distribute such Executable Form under the terms of this 186 | License, or sublicense it under different terms, provided that the 187 | license for the Executable Form does not attempt to limit or alter the 188 | recipients' rights in the Source Code Form under this License. 189 | 190 | 3.3. Distribution of a Larger Work 191 | 192 | You may create and distribute a Larger Work under terms of Your choice, 193 | provided that You also comply with the requirements of this License for 194 | the Covered Software. If the Larger Work is a combination of Covered 195 | Software with a work governed by one or more Secondary Licenses, and the 196 | Covered Software is not Incompatible With Secondary Licenses, this 197 | License permits You to additionally distribute such Covered Software 198 | under the terms of such Secondary License(s), so that the recipient of 199 | the Larger Work may, at their option, further distribute the Covered 200 | Software under the terms of either this License or such Secondary 201 | License(s). 202 | 203 | 3.4. Notices 204 | 205 | You may not remove or alter the substance of any license notices 206 | (including copyright notices, patent notices, disclaimers of warranty, or 207 | limitations of liability) contained within the Source Code Form of the 208 | Covered Software, except that You may alter any license notices to the 209 | extent required to remedy known factual inaccuracies. 210 | 211 | 3.5. Application of Additional Terms 212 | 213 | You may choose to offer, and to charge a fee for, warranty, support, 214 | indemnity or liability obligations to one or more recipients of Covered 215 | Software. However, You may do so only on Your own behalf, and not on 216 | behalf of any Contributor. You must make it absolutely clear that any 217 | such warranty, support, indemnity, or liability obligation is offered by 218 | You alone, and You hereby agree to indemnify every Contributor for any 219 | liability incurred by such Contributor as a result of warranty, support, 220 | indemnity or liability terms You offer. You may include additional 221 | disclaimers of warranty and limitations of liability specific to any 222 | jurisdiction. 223 | 224 | 4. Inability to Comply Due to Statute or Regulation 225 | 226 | If it is impossible for You to comply with any of the terms of this License 227 | with respect to some or all of the Covered Software due to statute, 228 | judicial order, or regulation then You must: (a) comply with the terms of 229 | this License to the maximum extent possible; and (b) describe the 230 | limitations and the code they affect. Such description must be placed in a 231 | text file included with all distributions of the Covered Software under 232 | this License. Except to the extent prohibited by statute or regulation, 233 | such description must be sufficiently detailed for a recipient of ordinary 234 | skill to be able to understand it. 235 | 236 | 5. Termination 237 | 238 | 5.1. The rights granted under this License will terminate automatically if You 239 | fail to comply with any of its terms. However, if You become compliant, 240 | then the rights granted under this License from a particular Contributor 241 | are reinstated (a) provisionally, unless and until such Contributor 242 | explicitly and finally terminates Your grants, and (b) on an ongoing 243 | basis, if such Contributor fails to notify You of the non-compliance by 244 | some reasonable means prior to 60 days after You have come back into 245 | compliance. Moreover, Your grants from a particular Contributor are 246 | reinstated on an ongoing basis if such Contributor notifies You of the 247 | non-compliance by some reasonable means, this is the first time You have 248 | received notice of non-compliance with this License from such 249 | Contributor, and You become compliant prior to 30 days after Your receipt 250 | of the notice. 251 | 252 | 5.2. If You initiate litigation against any entity by asserting a patent 253 | infringement claim (excluding declaratory judgment actions, 254 | counter-claims, and cross-claims) alleging that a Contributor Version 255 | directly or indirectly infringes any patent, then the rights granted to 256 | You by any and all Contributors for the Covered Software under Section 257 | 2.1 of this License shall terminate. 258 | 259 | 5.3. In the event of termination under Sections 5.1 or 5.2 above, all end user 260 | license agreements (excluding distributors and resellers) which have been 261 | validly granted by You or Your distributors under this License prior to 262 | termination shall survive termination. 263 | 264 | 6. Disclaimer of Warranty 265 | 266 | Covered Software is provided under this License on an "as is" basis, 267 | without warranty of any kind, either expressed, implied, or statutory, 268 | including, without limitation, warranties that the Covered Software is free 269 | of defects, merchantable, fit for a particular purpose or non-infringing. 270 | The entire risk as to the quality and performance of the Covered Software 271 | is with You. Should any Covered Software prove defective in any respect, 272 | You (not any Contributor) assume the cost of any necessary servicing, 273 | repair, or correction. This disclaimer of warranty constitutes an essential 274 | part of this License. No use of any Covered Software is authorized under 275 | this License except under this disclaimer. 276 | 277 | 7. Limitation of Liability 278 | 279 | Under no circumstances and under no legal theory, whether tort (including 280 | negligence), contract, or otherwise, shall any Contributor, or anyone who 281 | distributes Covered Software as permitted above, be liable to You for any 282 | direct, indirect, special, incidental, or consequential damages of any 283 | character including, without limitation, damages for lost profits, loss of 284 | goodwill, work stoppage, computer failure or malfunction, or any and all 285 | other commercial damages or losses, even if such party shall have been 286 | informed of the possibility of such damages. This limitation of liability 287 | shall not apply to liability for death or personal injury resulting from 288 | such party's negligence to the extent applicable law prohibits such 289 | limitation. Some jurisdictions do not allow the exclusion or limitation of 290 | incidental or consequential damages, so this exclusion and limitation may 291 | not apply to You. 292 | 293 | 8. Litigation 294 | 295 | Any litigation relating to this License may be brought only in the courts 296 | of a jurisdiction where the defendant maintains its principal place of 297 | business and such litigation shall be governed by laws of that 298 | jurisdiction, without reference to its conflict-of-law provisions. Nothing 299 | in this Section shall prevent a party's ability to bring cross-claims or 300 | counter-claims. 301 | 302 | 9. Miscellaneous 303 | 304 | This License represents the complete agreement concerning the subject 305 | matter hereof. If any provision of this License is held to be 306 | unenforceable, such provision shall be reformed only to the extent 307 | necessary to make it enforceable. Any law or regulation which provides that 308 | the language of a contract shall be construed against the drafter shall not 309 | be used to construe this License against a Contributor. 310 | 311 | 312 | 10. Versions of the License 313 | 314 | 10.1. New Versions 315 | 316 | Mozilla Foundation is the license steward. Except as provided in Section 317 | 10.3, no one other than the license steward has the right to modify or 318 | publish new versions of this License. Each version will be given a 319 | distinguishing version number. 320 | 321 | 10.2. Effect of New Versions 322 | 323 | You may distribute the Covered Software under the terms of the version 324 | of the License under which You originally received the Covered Software, 325 | or under the terms of any subsequent version published by the license 326 | steward. 327 | 328 | 10.3. Modified Versions 329 | 330 | If you create software not governed by this License, and you want to 331 | create a new license for such software, you may create and use a 332 | modified version of this License if you rename the license and remove 333 | any references to the name of the license steward (except to note that 334 | such modified license differs from this License). 335 | 336 | 10.4. Distributing Source Code Form that is Incompatible With Secondary 337 | Licenses If You choose to distribute Source Code Form that is 338 | Incompatible With Secondary Licenses under the terms of this version of 339 | the License, the notice described in Exhibit B of this License must be 340 | attached. 341 | 342 | Exhibit A - Source Code Form License Notice 343 | 344 | This Source Code Form is subject to the 345 | terms of the Mozilla Public License, v. 346 | 2.0. If a copy of the MPL was not 347 | distributed with this file, You can 348 | obtain one at 349 | http://mozilla.org/MPL/2.0/. 350 | 351 | If it is not possible or desirable to put the notice in a particular file, 352 | then You may include the notice in a location (such as a LICENSE file in a 353 | relevant directory) where a recipient would be likely to look for such a 354 | notice. 355 | 356 | You may add additional accurate notices of copyright ownership. 357 | 358 | Exhibit B - "Incompatible With Secondary Licenses" Notice 359 | 360 | This Source Code Form is "Incompatible 361 | With Secondary Licenses", as defined by 362 | the Mozilla Public License, v. 2.0. --------------------------------------------------------------------------------