Introduction

@shareflex/puppeteer-engine is a simple to use TestRunner for End2End-Testing powered by puppeteer.

Table of content

• Getting Started
• How to use
  • Example usage
  • Scripts
  • babelrc
  • Debugging
  • Config
• Support
• Contribute

Getting Started

npm install @shareflex/puppeteer-engine --save-dev

How to use:

Find an Example in "YourProjectPath/node_modules/@shareflex/puppeteer-engine/dist/Example".

Example usage:

//Import the Engine
import { Engine } from '@shareflex/puppeteer-engine';

//Import your config --Optional
//The config-object is passed as an argument to every executed testcase/testfunction. This allows you to access all properties from the given config such as "Headless" for example. 
//If you pass your own config, both configs (your's and internal) will be merged and your config-properties overwrite the internal config-properties.
//If you don't pass your own config, the engine will use it's internal config. See chapter "Config".

//CAUTION: Not passing your own config results to the fact, that tests in a pipeline cannot be executed in any other way than on your local machine.
import { Config } from './puppeteer.config';

//Import your TestCases
import { googleSomething } from './tests/googleSomething.test';
import { takeOneScreenshot } from './tests/takeOneScreenshot.test';

//Setup the Testsuites
const testSuite1 = [ googleSomething ]; //Add as much testcases/functions as you want
const testSuite2 = [ takeOneScreenshot ]; //Add as much testcases/functions as you want

//Setup a name for each Testsuite --Optional
testSuite1.name = "TestSuiteNumber1";

//Insert all Testsuites into one Array
const AllTests = [testSuite1, testSuite2];

//Create your own puppeteer-launch-config --Optional
//If you don't pass your own puppeteer-launch-config, the engine will use it's internal puppeteer-launch-config
//If you pass your own puppeteer-launch-config, that config will be used - no merge between internal puppeteer-launch-config and yours.
//See: https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#puppeteerlaunchoptions
const puppeteerLaunchOptions = {
  defaultViewport: null,
  args: [
    "--incognito", //Open the browser in incognito-mode, so we can be sure, that there's no caching (for login and/or js/css - files)
    "--ignore-certificate-errors", //Ignore possible certificate-errors
    "--start-maximized" //Open the browser maximized
  ], 
};

//3...2...1...GO!
(async () => {
  const engine = await Engine(Config);
  engine.Run(AllTests, puppeteerLaunchOptions);
})();

Scripts

Add these scripts to your package.json in order to run the above sample file:

• "test": "babel-node ./tests/Puppeteer/index.js" //run the above sample file
• "test-watch": "nodemon --exec babel-node ./tests/Puppeteer/index.js" //run the above sample file - watching*
• "test-watch-and-debug": "nodemon --inspect --exec babel-node ./tests/Puppeteer/index.js" //run the above sample file - watching* & enables Debbuging --start via VS Code-debugger only as described in Debugging

watching: Test script runs/starts automatically whenever the Engine notice a change in your code. Triggered via save (ctrl+s)

babelrc

Add a .babelrc to your root-folder:

{   
  "presets": [
    "@babel/preset-env"   
  ] 
}

Debugging

• Add a .vscode -folder to your project root.
• Add a launch.json -file inside of the new folder with this content:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "attach",
            "name": "chooseShownName", //will be shown in "RUN AND DEBUG" in vs code
            "restart": true,
            "localRoot": "${workspaceRoot}",
            "remoteRoot": "${workspaceRoot}",
            "preLaunchTask": "Start Tests",
            "postDebugTask": "Kill Terminal"
          }
    ]
}

• Add a tasks.json -file inside of the new folder with this content:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Start Tests",
            "type": "npm",
            "script": "test-watch-and-debug", //script in the package.json
            "isBackground": true,
            "problemMatcher": [
              {
                "pattern": [
                  {
                    "regexp": ".",
                    "file": 1,
                    "location": 2,
                    "message": 3
                  }
                ],
                "background": {
                  "activeOnStart": true,
                  "beginsPattern": ".",
                  "endsPattern": "."
                }
              }
            ]
          },
          {
            "label": "Kill Terminal",
            "type": "process",
            "command":[
               "${command:workbench.action.terminal.kill}"
            ],
         },
    ]
}

• Add Breakpoints
• Debug your tests by Start Debbuging (F5) in VS Code.

Config

The current config, the engine uses:

{
  "writeAllLogs": true,
  "Headless": false, //Displays Chrome
  "ResultDir": "/results", //Dir for test results xml -files - independet from "ScreenshotDir"
  "ScreenshotDir": "/results/screenshots", //Dir for screenshots - independet from "ResultDir"
  "TakeScreenshots": true,
  "WriteTestResults": true,
  "Attempts": 3 //Amount of attempts, the engine will make. Test fails, if the second rerun (three runs in total) fails 
}

Support

In case of experiencing an issue with @shareflex/puppeteer-engine, please contact us at [email protected].

Contribute

Contributions to @shareflex/puppeteer-engine are welcome. Here is how you can contribute:

• Submit pull requests
• Submit bugs & feature requests, and help verify fixes