bs-puppeteer

BuckleScript bindings to Puppeteer (the Headless Chrome Node API) written in ReasonML. This allows programmatic control of an instance of the Chrome or Chromium browser from BuckleScript or Reason.

Status

These bindings are a work in progress. Most bindings for navigation and interaction with web pages have been implemented. There may be some minor breaking changes as we refine the API. Bindings to the page events API are planned for a future version. See examples and the test suite for examples of usage. Features of the Puppeteer API are implemented as we need or get to them. We do our best to track upstream API changes. If you would like to add or fix some bindings, see Contributing.

Changes are documented in HISTORY.md.

Creating a project using bs-puppeteer

Create a new BuckleScript project if you have not already:

bsb -init my-project -theme basic-reason
cd my-project

See the BuckleScript documentation for more information about starting a project.

Add bs-puppeteer as a dependency. This will install the currently supported version of Puppeteer.

yarn
yarn add bs-puppeteer

Edit your bsconfig.json file to add bs-puppeteer to bs-dependencies:

  "bs-dependencies" : [
    "bs-puppeteer",
  ],

Now run:

yarn start

While the start command is running, it will attempt to recompile your code each time you save it. One-off builds can be done with yarn build.

The BsPuppeteer module should now be available in your source files. You can launch a new browser instance using BsPuppeteer.Puppeteer.launch(). See the examples for a more detailed demonstration.

For interacting with the DOM on pages you navigate to we recommend using bs-webapi.

Contributing

Contributions are welcome. Get started by cloning the respository and starting the compiler in watch mode. We recommend using yarn, but npm should also work.

Basic development workflow

git clone https://github.com/zploskey/bs-puppeteer.git
cd bs-puppeteer
yarn
yarn start

Any changes should pass the test suite (yarn test). One great way to contribute is by writing tests for features that don't yet have them. Tests can be found in the __tests__ directory. A git hook will automatically run refmt on your code and run the test suite each time you commit.

Snapshot diffs

If you would like to see a diff of the compiled javascript code from your changes, you can take a snapshot of the built JS you would like to compare to with our snap and snap-diff package commands. A typical workflow might look like this:

git checkout master # you may want to stash any changes with git stash
yarn snap # snapshot the built JS to the snap/ directory
# edit the code to make whatever changes
yarn snap-diff

This should rebuild and display git diff --no-index output comparing lib/js and snap/js. This can be handy in making sure that the right code is being generated.

References

Good references for contributing to this library are:

• BuckleScript Interop Cheatsheet
• Puppeteer API Docs

Projects using bs-puppeteer

• Hamilton Lottery
• lux-pos-web-wallet-e2e