{"id":15828646,"url":"https://github.com/shannonmoeller/run-headless","last_synced_at":"2025-07-02T04:33:54.711Z","repository":{"id":66097228,"uuid":"118045550","full_name":"shannonmoeller/run-headless","owner":"shannonmoeller","description":"The easiest way to run code in a headless browser.","archived":false,"fork":false,"pushed_at":"2018-10-28T19:32:55.000Z","size":92,"stargazers_count":5,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-30T03:44:38.011Z","etag":null,"topics":["browser","headless","puppeteer","testing"],"latest_commit_sha":null,"homepage":"http://npm.im/run-headless","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shannonmoeller.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-18T22:25:13.000Z","updated_at":"2023-06-29T04:56:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"c49e4c8c-0076-47b5-89f7-089c8ce4eab4","html_url":"https://github.com/shannonmoeller/run-headless","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/shannonmoeller/run-headless","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shannonmoeller%2Frun-headless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shannonmoeller%2Frun-headless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shannonmoeller%2Frun-headless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shannonmoeller%2Frun-headless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shannonmoeller","download_url":"https://codeload.github.com/shannonmoeller/run-headless/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shannonmoeller%2Frun-headless/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259747054,"owners_count":22905294,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","headless","puppeteer","testing"],"created_at":"2024-10-05T10:41:42.798Z","updated_at":"2025-07-02T04:33:54.690Z","avatar_url":"https://github.com/shannonmoeller.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# run-headless\n\n[![NPM version][npm-img]][npm-url] [![Downloads][downloads-img]][npm-url] [![Build Status][travis-img]][travis-url] [![Coverage Status][coveralls-img]][coveralls-url]\n\nThe easiest way of running code in a modern [headless browser environment](http://npm.im/puppeteer).\n\n## Install\n\n```command\n$ npm install --global run-headless\n```\n\n## Usage\n\n```man\nUsage: run-headless [options]\n       rh [options]\n\nOptions:\n\n      --html          Literal HTML to execute (default: minimal skeleton)\n      --js            Literal JavaScript to execute (default: stdin)\n      --url           URL to load (overrides --html)\n  -c, --close-var     Close global function (default: `__close__`)\n  -o, --coverage-var  Coverage global variable (default: `__coverage__`)\n  -d, --out-dir       Coverage output directory (default: `.nyc_output`)\n  -f, --out-file      Coverage output file (default: `\u003cuuid\u003e.json`)\n  -h, --help          Output usage information\n  -v, --version       Output version number\n```\n\n## Examples\n\n```command\n$ echo \"console.log('hello world')\" | run-headless\nhello world\n\n$ run-headless --js \"console.log('hello world')\"\nhello world\n```\n\n```command\n$ cat index.js | run-headless\n$ rollup index.js | run-headless\n$ browserify index.js | run-headless\n$ nyc instrument index.js | run-headless \u0026\u0026 nyc report\n```\n\n```command\n$ run-headless --html \"\u003cscript\u003econsole.log('hello world');\u003c/script\u003e\"\n$ run-headless --html \"$(cat index.html)\" --js \"$(cat index.js)\"\n```\n\n```command\n$ run-headless --url \"http://localhost:3000/tests\"\n$ run-headless --url \"https://google.com\" --js \"console.log(document.title)\"\n```\n\n### CI\n\nHeadless browsers are well suited to running in CI environments. Configurations vary, but this `.travis.yml` file should get you going with [Travis](https://travis-ci.org):\n\n```yml\nsudo: required\nlanguage: node_js\naddons:\n chrome: stable\nnode_js:\n  - node\n  - '8'\n```\n\n### Browser Testing\n\nYou can use any test runner you like that works in a browser and outputs to the console. Just make sure to run `window.__close__()` (or your custom `closeVar`) when all tests have completed.\n\n```js\n// test.js\n\nconst test = require('tape');\n\ntest('should pass', t =\u003e {\n    t.pass('yay!');\n    t.end();\n});\n\ntest.onFinish(window.__close__);\n```\n\n```command\n$ browserify test.js | run-headless | tap-diff\n\n  should pass\n    ✔  yay!\n\npassed: 1  failed: 0  of 1 tests  (763ms)\n\nAll of 1 tests passed!\n```\n\n## API\n\n### `run(options): Runner`\n\n- `options` `{Object}` See [usage](#usage).\n  - `html` `{String}`\n  - `js` `{String}`\n  - `closeVar` `{String}`\n  - `coverageVar` `{String}`\n  - `outDir` `{String}`\n  - `outFile` `{String}`\n\nThe following example starts up a static file server with [express](http://npm.im/express), bundles test scripts with [rollup](http://npm.im/rollup), executes them in a [headless browser](http://npm.im/puppeteer), and prints the output to the console. (Assumes that your rollup config is generating a bundle with [nyc](http://npm.im/nyc)-compatible instrumented code).\n\n```js\n// test.js\n\nconst run = require('run-headless');\nconst express = require('express');\nconst rollup = require('rollup');\n\nconst server = express\n    .use(express.static(__dirname))\n    .listen(3000, async () =\u003e {\n        const bundle = await rollup.rollup({ ... });\n        const { code } = await bundle.generate({ ... });\n\n        await run({\n            url: 'http://localhost:3000/tests.html',\n            js: code\n        });\n\n        server.close();\n    });\n```\n\n```command\n$ nyc node test.js\n... test output ...\n... coverage output ...\n```\n\n### Runner Methods\n\n#### `.then()` and `.catch()`\n\n`Runner` is a thenable and awaitable [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) object. It resolves when the browser is closed.\n\n### Runner Properties\n\n#### `.browser` `{Browser}`\n\nA puppeteer [Browser](https://github.com/GoogleChrome/puppeteer/blob/HEAD/docs/api.md#class-browser) instance.\n\n#### `.page` `{Page}`\n\nA puppeteer [Page](https://github.com/GoogleChrome/puppeteer/blob/HEAD/docs/api.md#class-page) instance.\n\n## Acknowledgements\n\n- [browser-run](http://npm.im/browser-run)\n- [run-browser](http://npm.im/run-browser)\n- [karma](http://npm.im/karma)\n\n----\n\nMIT © [Shannon Moeller](http://shannonmoeller.com)\n\n[coveralls-img]: http://img.shields.io/coveralls/shannonmoeller/run-headless/master.svg?style=flat-square\n[coveralls-url]: https://coveralls.io/r/shannonmoeller/run-headless\n[downloads-img]: http://img.shields.io/npm/dm/run-headless.svg?style=flat-square\n[npm-img]:       http://img.shields.io/npm/v/run-headless.svg?style=flat-square\n[npm-url]:       https://npmjs.org/package/run-headless\n[travis-img]:    http://img.shields.io/travis/shannonmoeller/run-headless.svg?style=flat-square\n[travis-url]:    https://travis-ci.org/shannonmoeller/run-headless\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshannonmoeller%2Frun-headless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshannonmoeller%2Frun-headless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshannonmoeller%2Frun-headless/lists"}