# browser-run > Transform stream that executes JavaScript it receives in a real browser and outputs console output Latest version **12.0.0** (published 2023-09-09) · MIT license · 0 weekly downloads ## Install ```sh npm install browser-run pnpm add browser-run yarn add browser-run bun add browser-run ``` Provides the command `browser-run`. ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 12.0.0 | | Published | 2023-09-09 | | First published | 2013-03-22 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >=14 | | Dependencies | 12 | | Unpacked size | 422.9 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 464 | | Author | Julian Gruber | | Maintainers | juliangruber | | Keywords | browser, stream, test, headless, duplex | ## Links - npm: https://www.npmjs.com/package/browser-run - Repository: https://github.com/juliangruber/browser-run - Issues: https://github.com/juliangruber/browser-run/issues - npm.io page: https://npm.io/package/browser-run ## Dependencies (12) - [xtend](https://npm.io/package/xtend.md) ^4.0.1 - [yargs](https://npm.io/package/yargs.md) ^16.2.0 - [enstore](https://npm.io/package/enstore.md) ^1.0.1 - [through](https://npm.io/package/through.md) ^2.3.8 - [duplexer](https://npm.io/package/duplexer.md) ^0.1.1 - [ecstatic](https://npm.io/package/ecstatic.md) ^4.1.2 - [server-destroy](https://npm.io/package/server-destroy.md) ^1.0.1 - [electron-stream](https://npm.io/package/electron-stream.md) ^11.0.0 - [browser-launcher](https://npm.io/package/browser-launcher.md) ^3.0.1 - [xhr-write-stream](https://npm.io/package/xhr-write-stream.md) ^0.1.2 - [html-inject-script](https://npm.io/package/html-inject-script.md) ^2.0.0 - [source-map-support](https://npm.io/package/source-map-support.md) ^0.4.0 ## Alternatives - [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads - [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads - [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads - [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads - [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads ## Recent versions - 12.0.0 (latest) — 2023-09-09 - 11.0.0 — 2022-05-04 - 10.1.0 — 2021-04-09 - 10.0.0 — 2021-04-06 - 9.0.0 — 2021-01-15 - 8.0.0 — 2020-07-22 - 7.0.2 — 2020-05-06 - 7.0.1 — 2020-04-06 - 7.0.0 — 2019-12-19 - 6.0.0 — 2019-05-02 - 5.0.2 — 2019-05-02 - 5.0.1 — 2018-12-13 - 5.0.0 — 2018-03-27 - 4.1.3 — 2018-02-10 - 4.1.2 — 2018-02-09 - … 58 more at https://npm.io/package/browser-run/versions ## README # browser-run The easiest way of running code in a browser environment. Bundles `electronjs` by default! [![CI](https://github.com/juliangruber/browser-run/actions/workflows/ci.yml/badge.svg)](https://github.com/juliangruber/browser-run/actions/workflows/ci.yml) [![downloads](https://img.shields.io/npm/dm/browser-run.svg)](https://www.npmjs.org/package/browser-run) ## Usage ```bash $ echo "console.log('Hey from ' + location); window.close()" | browser-run Hey from http://localhost:53227/ $ ``` Or use `browser-run` programmatically: ```js var run = require('browser-run'); var browser = run(); browser.pipe(process.stdout); browser.end('console.log(location); window.close()'); ``` ## Example with browserify ```bash $ browserify main.js | browser-run ``` or ```js var browserify = require('browserify'); var browser = require('browser-run'); browserify('main.js').bundle().pipe(browser()).pipe(process.stdout); ``` ## CLI ```bash $ browser-run --help Run JavaScript in a browser. Write code to stdin and receive console output on stdout. Usage: browser-run [OPTIONS] Options: --version Show version number [boolean] -b, --browser Browser to use. Always available: electron. Available if installed: chrome, firefox, ie, safari [default: "electron"] --sandbox Enable electron sandbox [boolean] [default: true] --basedir Set this if you need to require node modules in node mode -h, --help Print help [boolean] -p, --port Starts listening on that port and waits for you to open a browser -s, --static Serve static assets from this directory -m, --mock Path to code to handle requests for mocking a dynamic back-end -i, --input Input type. Defaults to 'javascript', can be set to 'html'. -n, --node Enable nodejs apis in electron ``` ## Custom html file By using `--input html` or `{ input: 'html' }` you can provide a custom html file for browser-run to use. Keep in mind though that it always needs to have `` above other script tags so browser-run is able to properly forward your `console.log`s etc to the terminal. ## Dynamic back-end mock By using `--mock mock.js` or `{ mock: 'mock.js'}` you can provide a custom server-side implementation and handle all requests that are sent to paths beginning with `/mock` mock.js needs to export a function that accepts `req` and `res` arguments for handling requests. Example: ```js module.exports = function(req,res){ if (req.url === '/mock/echo') { req.pipe(res) } } ``` ## API ### run([opts]) Returns a duplex stream and starts a webserver. `opts` can be: * `port`: If speficied, no browser will be started, so you can point one yourself to `http://localhost/` * `browser`: Browser to use. Defaults to `electron`. Available if installed: * `chrome` * `firefox` * `ie` * `safari` * `static`: Serve static files from this directory * `mock`: Path to code to handle requests for mocking a dynamic back-end * `input`: Input type. Defaults to `javascript`, can be set to `html`. * `node`: Enable nodejs integration in electron * `sandbox`: Enable electron sandbox. Default: `true`. * `basedir`: Set this if you need to require node modules in `node` mode If only an empty string is written to it, an error will be thrown as there is nothing to execute. If you call `window.close()` inside the script, the browser will exit. ### run#stop() Stop the underlying webserver. ## Headless testing In environments without a screen, you can use `Xvfb` to simulate one. ### GitHub Actions This is a full example to run `npm test`. Refer to the last 2 lines in the YAML config: ```yml on: - pull_request - push jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - run: npm install - run: sudo apt-get install xvfb - run: xvfb-run --auto-servernum npm test ``` ### Travis Add this to your travis.yml: ```yml addons: apt: packages: - xvfb install: - export DISPLAY=':99.0' - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 & - npm install ``` [Full example](https://github.com/rhysd/Shiba/blob/055a11a0a2b4f727577fe61371a88d8db9277de5/.travis.yml). ### Any gnu/linux box ```bash $ sudo apt-get install xvfb # or equivalent $ export DISPLAY=':99.0' $ Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 & $ browser-run ... ``` ### Docker There is also an example [Docker image](https://hub.docker.com/r/kipparker/docker-tape-run). [Source](https://github.com/fraserxu/docker-tape-run) ## Installation With [npm](http://npmjs.org) do ```bash $ npm install browser-run # for library $ npm install -g browser-run # for cli ``` ## Sponsors This module is proudly supported by my [Sponsors](https://github.com/juliangruber/sponsors)! Do you want to support modules like this to improve their quality, stability and weigh in on new features? Then please consider donating to my [Patreon](https://www.patreon.com/juliangruber). Not sure how much of my modules you're using? Try [feross/thanks](https://github.com/feross/thanks)! ## License (MIT) --- _Source: https://npm.io/package/browser-run · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._