Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/catdad/puptron

🐶 automate your Electron application with Puppeteer
https://github.com/catdad/puptron

automation electron puppeteer test-automation testing

Last synced: about 2 months ago
JSON representation

🐶 automate your Electron application with Puppeteer

Awesome Lists containing this project

README 

        
# puptron



[![tests][test.svg]][test.link]

[![npm-downloads][npm-downloads.svg]][npm.link]

[![npm-version][npm-version.svg]][npm.link]



[test.svg]: https://github.com/catdad/puptron/workflows/test/badge.svg

[test.link]: https://github.com/catdad/puptron/actions?query=workflow%3Atest

[npm-downloads.svg]: https://img.shields.io/npm/dm/puptron.svg

[npm.link]: https://www.npmjs.com/package/puptron

[npm-version.svg]: https://img.shields.io/npm/v/puptron.svg



> 🐶 automate your [Electron](https://www.electronjs.org/) application with [Puppeteer](https://pptr.dev/)



Puptron is a handy library to bootstrap the end-to-end test automation of your Electron application. It allows you to launch your application on-demand, instrumented with an instance of `puppeteer`, allowing you to use your favorite test framework to test your application. Puptron does not place any requirements on your application. That means that your applicationd does not need to enable node integration or the remote module, it does not need to expose the `require` method, and it does not need to disable context isolation. Your application can run the same way that your end users will run it.



> 🚨 This module is in early development, but I already use it in a few of my projects. Do know that this API may change. If you find any issues or have any feedback, please [submit an issue](https://github.com/catdad/puptron/issues/new).



## Install



```bash

npm install --development puptron

```



## API



```javascript

const { launch } = require('puptron');

```



### `launch(args, [options = {}])` → `Promise`



This method launches the instrumented application. It has the following arguments:

* `args` _Array<String>_: the arguments to be passed to the Electron application. Think: the arguments that you use to launch the application from the command line. Example: `['.']`

* `[options]` _Object_: options for the Electron process being launched. This object and all its properties are optional. These include:

  * `[cwd]` _String_: The current working directory for the application. The default is the current directory of the current process.

  * `[env]` _Object_: A key-value pair of environment variables to included when launching the process. The default is all existing variables of the current process.

  * `[rendererTimeout]` _Number_: When connecting to the renderer process, the total amount of time, in milliseconds, to try to connect to the renderer. This can be useful for apps that are slow to start. Default is `2000`.

  * `[rendererInterval]` _Number_: When connecting to the renderer process, the amount of time, in milliseconds, to wait between retrying connecting. This can be useful for apps that are slow to start. Default is `5`.

  * `[execPath]` _String_: The path to the electron executable that you wish to use to start the application. This is useful if you have a custom setup, or if you would like to test the production application after it has been built. Default is `require('electron')`.



This method will return a promise that resolved to an instance of the Puppeteer [`browser`](https://pptr.dev/#?product=Puppeteer&version=v5.2.1&show=api-class-browser) object.



> 📝 _Note that some method, such as `newPage`, may not work. Use your best judgement on what you realisticaly expect a particular method to do in Electron._



## Examples



You can use any test frameworks and tools that you would like, but here are some good choices:



Using [`mocha`](https://mochajs.org/) and [`pptr-testing-library`](https://github.com/testing-library/pptr-testing-library):



```javascript

const path = require('path');

const { launch } = require('puptron');

const { getDocument, queries } = require('pptr-testing-library');



describe('my application', () => {

  let app;



  beforeEach(async () => {

    app = await launch(['.'], {

      // assuming your app is at the root / and your tests are in /test

      cwd: path.resolve(__dirname, '..'),

      env: {

        // some variable your app uses, like a custom test config file

        MY_APP_CONFIG: path.resolve('/path/to/custom/config')

      }

    });

  });



  afterEach(async () => {

    await app.close();

  });



  it('does something', async () => {

    // get the main BrowserWindow page

    const [page] = await app.pages();



    // do some testing... this part is up to you

    const $document = await getDocument(page);

    const $button = await queries.getByTestId($document, 'my-button');

    await $button.click();

  });

});

```