Popper: Realtime Cross-Browser Automation
The benefit of the ubiquity of the Web is also its pain point when it comes to accurate testing. It is common to see handwavy statements for browser compatibility, for example "IE9+", as if every other OS/platform combination will be just fine if IE9 "works"! For those who need more realistic data, this module makes it much easier to test code earlier on in the development lifecycle, even in realtime.
Snapshot of Test Results for Ripple v0.3 on latest Chrome, Firefox, IE, Android and iOS
- Spawn agents using BrowserStack/Sauce
- Multi-repo testing, where changing one module might affect others (e.g microlibs in utilise or modules in ripple v0.3)
- Aggregate results per-repo, per-browser and globally in realtime
- Rerun on file change
- Open your own browser tabs to act as test agents, useful for enterprise context
- Automatic OS/Browser identification and simple icons
- CLI with convenient defaults
.popper.ymlfile for persisting test config per repo
- Proxy console/error statements, making remote debugging on mobile devices a lot easier
- Force a rerun on a particular agent
- View a snapshot of the results page stream in as produced by the agent
- CI Integration by having
popperwhich will return exit cleanly if the tests pass in all defined browsers
- Increase CI Timeout by setting
POPPER_TIMEOUT=millisecondsto help investigate why a CI test is failiing (defaults to 20s)
- Optional Tunnel to allow completely disabling the tunnelling via ngrok
- Add your own remote farm
- Add your own test runner
See roadmap issues label for upcoming features/idea.
# since this uses lots and lots of tiny libs, I recommend using npm3npm i -g popper # install globallynpm i -D popper # install locally# to runpopper# to also see logs from each browser in terminal windowNODE_ENV=debug popper# if you are using browserstackexport BROWSERSTACK_USERNAME=...export BROWSERSTACK_KEY=...
Once running, open a browser tab to
localhost:1945 (or the external ngrok URL) to run the tests, and keep open
localhost:1945/dashboard to see the results as you continue to make changes. If you specified any
browsers, they will be launched on BrowserStack and pointed to the test page.
When you run
popper in a folder:
- If there is a
popper.jsfile, it will run that (example)
- If there is a
popper.ymlfile, it will use options from that (example)
- If there are any command-line arguments passed, those will take precedence in overriding the
- If there is nothing, it will default convenient options so you can just jump into most repos and run
You can set all the following options using via the CLI, YAML or JS API:
usage: popper options: -b, --browsers: browser to spawn and run tests on, defaults to none -t, --test: command to generate test bundle, defaults to "browserify test.js" -p, --port: port to run on, defaults to 1945 -w, --watch: files to watch for changes, defaults to . -n, --notunnel: disable opening tunnel, defaults to open -l, --timeout: maximum time to wait in ci mode for results, defaults to POPPER_TIMEOUT or 20000 -r, --runner: the runner to use, either mocha or tape, defatuls to mocha -f, --farm: the remote browser farm to spawn browsers in, defaults to browserstack
If any of the options are missing from the local YAML config or CLI arguments, they will default to:
- Disable Tunnel:
process.env.POPPER_TIMEOUT || 20000
# these will be added to the headglobals:- <script src="https://cdn.polyfill.io/v1/polyfill.min.js"></script>- <script src="https://cdnjs.cloudflare.com/ajax/libs/d3/3.5.5/d3.min.js" charset="utf-8"></script>- <script src="https://cdnjs.cloudflare.com/ajax/libs/chai/3.0.0/chai.min.js"></script>- <script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.10.3/moment.min.js"></script># this is the command to generate the tests bundle on startup and after a file change detectedtests: browserify ./node_modules/*/test.js-i moment-i colors-i jsdom-i chai-i d3-i ./node_modules/pause/test.js-i ./node_modules/send/test.js-i ./node_modules/file/test.js-i ./node_modules/via/test.js| sed -E "s/require\('moment'\)/window.moment/"| sed -E "s/require\('chai'\)/window.chai/"| sed -E "s/require\('d3'\)/window.d3/"| uglifyjs# browsers to spawn in browserstack/sauce# can be wd capabilities object to specify os, device, version, etc:browsers:- ie9- android- iphone- opera- safari# port to run on locallyport: 1945# glob(s) to watch for file changeswatch: ./node_modules/*/index.js
In this case, the test command will rebuild the project before bundling the tests after each file change.
globals:- <script src="https://cdn.polyfill.io/v1/polyfill.min.js"></script>- <script src="https://cdnjs.cloudflare.com/ajax/libs/chai/3.0.0/chai.min.js"></script>tests: (npm run build > /dev/null) && browserify ./test.js-i colors-i chai| sed -E "s/require\('chai'\)/window.chai/"| uglifyjswatch:- src- test.js
popper =popper =
Popper uses Ripple under the hood. The JS API is particularly useful if you need to extend the available resources. For example, for testing Ripple itself and it's server/client synchronisation module, I use the following to reset test resources before each test:
Adding a Farm
If you'd like to add a new remote browser farm, you just need to add a folder under
/farms and then you can set the
farm option (via JS, YAML or CLI) to the name of your farm. The folder should contain two things (see browserstack for an example):
browsers.json: Mapping of shorthands (e.g.
ie9) to browser capability objects. Since there is different properties across services (e.g.
browserName), you should also specify the properties
_os_versionwhere applicable, which is what will show up in the popper logs.
connect: A connect function, which will take in a
wdinstance and using the relevant environment variables, connect to the service. If it failed to connect, it should return false.
Adding a Runner
If you'd like to add a new test runner, you just need to add a folder
/client and then you can set the
runner option (via JS, YAML or CLI) to the name of your runner. The folder should contain two things (see mocha for an example):
index.html: This is the HTML file that will be run on the test agent. You will also need a script (see
client.js) that streams back the results of the test.
logs.html: A HTML file that will be used from the dashboard (when you click "View Results") to format the read-only results of the tests run on a specific agent.
Thanks to BrowserStack and SauceLabs for providing a free open source account for testing.