{"id":13448607,"url":"https://github.com/andywer/puppet-run","last_synced_at":"2025-08-22T19:16:25.073Z","repository":{"id":53474608,"uuid":"159552779","full_name":"andywer/puppet-run","owner":"andywer","description":"🤖 Run anything JavaScript in a headless Chrome from your command line","archived":false,"fork":false,"pushed_at":"2021-03-29T18:37:42.000Z","size":974,"stargazers_count":56,"open_issues_count":6,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T19:44:58.553Z","etag":null,"topics":["chrome","cli","headless","puppeteer","scripting","testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/andywer.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}},"created_at":"2018-11-28T19:20:38.000Z","updated_at":"2024-11-23T13:22:17.000Z","dependencies_parsed_at":"2022-08-31T17:21:03.916Z","dependency_job_id":null,"html_url":"https://github.com/andywer/puppet-run","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpuppet-run","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpuppet-run/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpuppet-run/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andywer%2Fpuppet-run/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andywer","download_url":"https://codeload.github.com/andywer/puppet-run/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249067756,"owners_count":21207395,"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":["chrome","cli","headless","puppeteer","scripting","testing"],"created_at":"2024-07-31T05:01:50.315Z","updated_at":"2025-04-15T11:52:45.398Z","avatar_url":"https://github.com/andywer.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003e🤖\u0026nbsp;\u0026nbsp;puppet-run\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/puppet-run\" target=\"_blank\"\u003e\u003cimg alt=\"npm (tag)\" src=\"https://img.shields.io/npm/v/puppet-run.svg?style=flat-square\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nRun any JavaScript / TypeScript code in a headless browser using [Puppeteer](https://github.com/GoogleChrome/puppeteer) and pipe its output to your terminal 🔥\n\nTransparently bundles input files, so you can use `require()` and ES module imports. You can even simulate connectivity issues and serve static files. Great for testing client-side code in an actual browser!\n\nHow does it relate to [Karma](https://karma-runner.github.io)? It's everything that Karma is not: It's small, it's fast and trivial to set up.\n\n🚀\u0026nbsp;\u0026nbsp;Runs any script in a headless Chrome browser\u003cbr /\u003e\n📦\u0026nbsp;\u0026nbsp;Zero-config transparent bundling\u003cbr /\u003e\n💡\u0026nbsp;\u0026nbsp;Supports TypeScript, ES modules \u0026amp; JSX out of the box\u003cbr /\u003e\n🖥\u0026nbsp;\u0026nbsp;Pipes console output and errors to host shell\u003cbr /\u003e\n⚙️\u0026nbsp;\u0026nbsp;Uses custom Babel, TypeScript, ... config if present\u003cbr /\u003e\n\n\n## Installation\n\n```sh\nnpm install puppet-run\n```\n\n## Usage\n\n### Basics\n\nRunning `puppet-run` from the command line is simple. We can use npm's [npx tool](https://blog.npmjs.org/post/162869356040/introducing-npx-an-npm-package-runner) for convenience.\n\n```sh\nnpx puppet-run [\u003carguments\u003e]\n\n# without npx\nnode ./node_modules/.bin/puppet-run [\u003carguments\u003e]\n```\n\nPass any JavaScript or TypeScript file to `puppet-run` as an entrypoint. It will be transpiled by Babel and bundled using `browserify`. It normally works out-of-the-box with zero configuration.\n\n```sh\nnpx puppet-run [...puppet-run options] ./path/to/script.js [...script options]\n```\n\n### Run mocha tests\n\n```sh\nnpm install puppet-run-plugin-mocha\nnpx puppet-run --plugin=mocha [...mocha options] ./path/to/*.test.js\n```\n\n### Print help texts\n\n```sh\nnpx puppet-run --help\n```\n\nTo print a plugin's help text:\n\n```sh\nnpx puppet-run --plugin=mocha --help\n```\n\n\n## Example\n\n```js\n// sample.js\n\n// Everything logged here will be piped to your host terminal\nconsole.log(`I am being run in a browser: ${navigator.userAgent}`)\n\n// Explicitly terminate the script when you are done\npuppet.exit()\n```\n\nDon't forget to call `puppet.exit()` when the script is done, so `puppet-run` knows that the script has finished. You can also exit with a non-zero exit code using `puppet.exit(statusCode: number)`.\n\nCheck out the  \"Scripting API\" section below if you want to learn more about the globally available `puppet` object.\n\nLet's run the sample script!\n\n```sh\nnpx puppet-run ./sample.js\n```\n\nYou should now see the output of the script on your terminal:\n\n```\nI am being run in a browser: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36\n```\n\nHave fun!\n\n\n## Plugins\n\nPlugins make it easy to integrate your script with testing frameworks.\n\nCheck out the 👉 [plugins repository](https://github.com/andywer/puppet-run-plugins) to see what's on offer.\n\n\n## Scripting API\n\nThe script runner will inject a `puppet` object into the browser window's global scope. It contains a couple of useful functions.\n\n#### `puppet.argv: string[]`\n\nContains all the command line arguments and options passed to `puppet-run` after the script file path.\n\n#### `puppet.exit(exitCode?: number = 0)`\n\nCauses the script to end. The `puppet-run` process will exit with the exit code you pass here.\n\nThe exit code defaults to zero.\n\n#### `puppet.setOfflineMode(takeOffline: boolean = true)`\n\nPuts the browser in offline mode and closes all active connections if called with `true` or no arguments. Call it with `false` to bring the browser back online.\n\n\n## More features\n\n### Environment variables\n\nYou can access all environment variables of the host shell in your scripts as `process.env.*`.\n\n### Source Maps\n\nIf an error is thrown, you will see the error and stack trace in your host shell. The stack trace will reference your source file lines, not the line in the bundle file that is actually served to the browser under the hood.\n\n\n## Samples\n\nHave a look at the samples in the [`sample`](./sample) directory:\n\n- [Simple Testing](./sample/basic)\n- [Simple Mocha Test](./sample/mocha)\n- [React / Enzyme Test](./sample/mocha-enzyme)\n- [Tape Test](./sample/tape)\n\n\n## Test framework support\n\nIf you want to run tests in the browser using puppet-run, check out this list first:\n\n#### ✅ Mocha\n\nWorks like a charm, see [`sample/mocha`](./sample/mocha) or [`sample/mocha-enzyme`](./sample/mocha-enzyme). They use the [Mocha Plugin](https://github.com/andywer/puppet-run-plugins/tree/master/packages/puppet-run-plugin-mocha).\n\n#### ✅ Tape\n\nWorks like a charm, see [`sample/tape`](./sample/tape).\n\n#### ❌ AVA\n\nCurrently not possible, since it's testing library and test runner code are too tightly coupled.\n\n#### ❔ Jest\n\nDidn't try yet.\n\n\n## License\n\nMIT\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandywer%2Fpuppet-run","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandywer%2Fpuppet-run","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandywer%2Fpuppet-run/lists"}