puptron v0.0.8

puptron

🐶 automate your Electron application with Puppeteer

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.

Install

npm install --development puptron

API

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 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 and pptr-testing-library:

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();
  });
});