Skip to content

Latest commit

 

History

History
2364 lines (1347 loc) · 58.1 KB

Documentation.md

File metadata and controls

2364 lines (1347 loc) · 58.1 KB
Raw

Table of Contents

index

src/index.js:15-39

Sets up a QApe run

Parameters

  • configOverride

master

src/master/index.js:9-84

index

src/master/index.js:9-84

Initializes all QApe workers and handles their communication.

Parameters

  • cluster cluster
  • config Object

reporter

src/reporter/index.js:13-29

index

src/reporter/index.js:13-29

Initializes reporter worker. It handles all the test results and the distribution to all defined reporters.

Parameters

ConsoleReporter

src/reporter/reporter/ConsoleReporter.js:7-115

Extends EventEmitter

Console reporter

Parameters

_handleScenarioStart

src/reporter/reporter/ConsoleReporter.js:26-28

Handler for scenario:start event

Parameters

_handleScenarioEnd

src/reporter/reporter/ConsoleReporter.js:34-43

Handler for scenario:end event

Parameters

_handleError

src/reporter/reporter/ConsoleReporter.js:49-51

Handler for runner:error event

Parameters

_handleDefinedScenarioEnd

src/reporter/reporter/ConsoleReporter.js:57-70

Handler for scenario:end of type 'defined'

Parameters

  • eventData Object

    • eventData.name
    • eventData.results

_handleFailingScenarioEnd

src/reporter/reporter/ConsoleReporter.js:76-82

Handler for scenario:end of type 'failing'

Parameters

  • eventData Object

    • eventData.minified
    • eventData.scenario
    • eventData.errors

_handleRandomScenarioEnd

src/reporter/reporter/ConsoleReporter.js:88-99

Handler for scenario:end of type 'random'

Parameters

  • eventData Object

    • eventData.results

_logConsole

src/reporter/reporter/ConsoleReporter.js:107-114

Logs scenario to console

Parameters

FileReporter

src/reporter/reporter/FileReporter.js:11-104

Extends EventEmitter

Default reporter

Parameters

_handleScenarioEnd

src/reporter/reporter/FileReporter.js:29-33

Handler for scenario:end event

Parameters

_handleFailingScenarioEnd

src/reporter/reporter/FileReporter.js:39-47

Handler for scenario:end of type 'failing'

Parameters

  • eventData Object

    • eventData.minified
    • eventData.scenario
    • eventData.errors

_logFile

src/reporter/reporter/FileReporter.js:55-73

Logs scenario to file

Parameters

_getScenarioName

src/reporter/reporter/FileReporter.js:81-95

Generates scenario name from current date

Parameters

  • extension string? This string will be added to the end of the name (optional, default '')

Returns string

_isFailureReported

src/reporter/reporter/FileReporter.js:101-103

Checks if provided scenario is already reported

Parameters

  • scenario

Returns boolean

Reporter

src/reporter/reporter/Reporter.js:9-94

Extends EventEmitter

Base Reporter distributing events to all defined reporters

Parameters

init

src/reporter/reporter/Reporter.js:24-52

Initializes all reporters defined in config

emit

src/reporter/reporter/Reporter.js:60-68

Emits an event with data and propagets it to all reporters

Parameters

_initReporterFromString

src/reporter/reporter/Reporter.js:74-79

Initializes a reporter from string

Parameters

_initReporterFromClass

src/reporter/reporter/Reporter.js:85-93

Initializes a reporter from a class constructor

Parameters

  • Reporter Class

SpinnerReporter

src/reporter/reporter/SpinnerReporter.js:10-58

Extends EventEmitter

Default reporter

Parameters

_handleEvent

src/reporter/reporter/SpinnerReporter.js:38-48

Handler for events which should cause a spin

scriptwriter

src/scriptwriter/index.js:11-27

index

src/scriptwriter/index.js:11-27

Initializes a scriptwriter worker. It handles scenarios distribution to the testers.

Parameters

ScenariosHandler

src/scriptwriter/scenarios/ScenariosHandler.js:8-131

Handles scenarios execution order

Parameters

init

src/scriptwriter/scenarios/ScenariosHandler.js:26-31

Initializes default values and loads defined scenarios

init

src/tester/scenarios/ScenariosHandler.js:33-40

Initializes all dependencies

Returns ScenariosHandler

getScenario

src/scriptwriter/scenarios/ScenariosHandler.js:40-63

Returns available scenario with highest priority

  1. FailingScenario
  2. DefinedScenario
  3. RandomScenario (if allowed by config)

Returns Object

_isAllowedToStartRandomScenario

src/scriptwriter/scenarios/ScenariosHandler.js:73-83

Checks if new random scenarios are allowed based on configuration

Returns boolean

_loadDefinedScenarios

src/scriptwriter/scenarios/ScenariosHandler.js:88-101

Loads all user defined scenarios specified in config

_loadScenarioFromPath

src/scriptwriter/scenarios/ScenariosHandler.js:108-116

Loads a scenario from specified scenarioPath

Parameters

Returns Object scenario

_getRandomScenarioStartUrl

src/scriptwriter/scenarios/ScenariosHandler.js:122-130

Loads a start url for scenario from specified url paths

Returns string start url

ScenariosHandler

src/tester/scenarios/ScenariosHandler.js:10-53

Handles scenarios execution and initializes necessary dependencies

Parameters

init

src/scriptwriter/scenarios/ScenariosHandler.js:26-31

Initializes default values and loads defined scenarios

init

src/tester/scenarios/ScenariosHandler.js:33-40

Initializes all dependencies

Returns ScenariosHandler

getScenario

src/scriptwriter/scenarios/ScenariosHandler.js:40-63

Returns available scenario with highest priority

  1. FailingScenario
  2. DefinedScenario
  3. RandomScenario (if allowed by config)

Returns Object

_isAllowedToStartRandomScenario

src/scriptwriter/scenarios/ScenariosHandler.js:73-83

Checks if new random scenarios are allowed based on configuration

Returns boolean

_loadDefinedScenarios

src/scriptwriter/scenarios/ScenariosHandler.js:88-101

Loads all user defined scenarios specified in config

_loadScenarioFromPath

src/scriptwriter/scenarios/ScenariosHandler.js:108-116

Loads a scenario from specified scenarioPath

Parameters

Returns Object scenario

_getRandomScenarioStartUrl

src/scriptwriter/scenarios/ScenariosHandler.js:122-130

Loads a start url for scenario from specified url paths

Returns string start url

Config

src/shared/config/Config.js:8-67

Class that can parse configuration with default values.

load

src/shared/config/Config.js:13-31

Loads configuration with default values

Parameters

  • userConfig Object? Overrides for default config

_resolveUrl

src/shared/config/Config.js:43-53

If url is configured with url path (https://www.example.com/index.html), then this method splits the configuration into url and urlPaths.

Parameters

Examples

Following config
`{ url: 'https://www.example.com/index.html' }`
would be transformed into the following config
`{ url: 'https://www.example.com', urlPaths: ['/index.html'] }`

_setPreviewMode

src/shared/config/Config.js:59-66

Overrides preview mode configurations

Parameters

helpers

src/shared/helpers.js:9-11

getRandomElementFromArray

src/shared/helpers.js:9-11

Gets a random element from the array

Parameters

Returns any Element from the array

formatDigits

src/shared/helpers.js:20-22

Formats number to specified number of digits

Parameters

Returns string Number prefixed with ${digits} of zeros

AbstractAction

src/tester/actions/AbstractAction.js:8-257

Abstract action class which should be extended with specific action classes. Each class has to have static getter id and method action.

Parameters

evaluateAction

src/tester/actions/AbstractAction.js:49-51

Overridable method returning a promise, that should resolve when action was successfull and reject when not.

updateResults

src/tester/actions/AbstractAction.js:58-60

Override if you need to update action config, or message

Parameters

  • results Object Current results without your updates

Returns Promise<Object> Updated results with your overrides

execute

src/tester/actions/AbstractAction.js:68-91

Prepares action error handler and executes action lifecycle

Parameters

  • element puppeteer.ElementHandle
  • instance Object Browser instance

Returns Object results

action

src/tester/actions/AbstractAction.js:97-99

Override with specific action method, which is executed during AbstractAction.execute()

_executeActionLifecycle

src/tester/actions/AbstractAction.js:111-127

Executes action lifecycle:

  • Executes before action scripts (AbstractAction._beforeActionExecute)
  • Executes the action and emits 'action:error' event for any error it throws
  • Evaluates the action success
  • Executes after action scripts (AbstractAction._afterActionExecute)

Parameters

  • element puppeteer.ElementHandle
  • instance Browser

Returns Promise Resolves when lifecycle is finished

_handleExecutionError

src/tester/actions/AbstractAction.js:133-139

Distributes action execution error

Parameters

  • error Error

    • error.stack

_afterActionExecute

src/tester/actions/AbstractAction.js:154-175

Executes after action scripts

  • Executes config.beforeActionScript
  • Clears all tabs and windows except for the original one
  • If the current url is not part of the tested website, then page.goBack() is called
  • Waits for time specified in config.afterActionWaitTime so all scripts are evaluated

and no more errors will occure before next action

  • Saves afterLocation to results, which is url after the action was executed
  • Reports event 'action:end'

Parameters

  • element puppeteer.ElementHandle
  • instance Browser

Returns Promise Resolves when after action is done

_beforeActionExecute

src/tester/actions/AbstractAction.js:185-195

Executes before action scripts

  • Saves beforeLocation to results, which is url before the action was executed
  • Executes config.beforeActionScript
  • Reports event 'action:start'

Parameters

Returns Promise Resolves when before action is done

_addErrorToResults

src/tester/actions/AbstractAction.js:201-206

Adds the error to action results

Parameters

_clearTabs

src/tester/actions/AbstractAction.js:213-218

Clears all browser tabs except for the tab at index 0

Parameters

  • browser puppeteer.Browser

Returns Promise Resolves when the tabs are closed

_addEventListener

src/tester/actions/AbstractAction.js:226-230

Adds an event listener and registers it to

Parameters

_clearAllEventListeners

src/tester/actions/AbstractAction.js:235-241

Clears all registered event listeners

_logInfo

src/tester/actions/AbstractAction.js:248-256

Adds action info to the results

Parameters

  • element puppeteer.ElementHandle

Returns Promise Resolves when action info is saved

id

src/tester/actions/AbstractAction.js:12-14

Override with action identifier

isActionAvailable

src/tester/actions/AbstractAction.js:19-23

Override with method returning true, when the action should be available for the specified element

ActionsHandler

src/tester/actions/ActionsHandler.js:9-152

Actions handler which can work with specific actions.

Parameters

init

src/tester/actions/ActionsHandler.js:25-30

Initializes actions handler dependencies

Returns ActionsHandler this

execute

src/tester/actions/ActionsHandler.js:39-57

Executes specific, or random action

Parameters

Returns Promise<Object> Resolves with action results

_getAction

src/tester/actions/ActionsHandler.js:66-87

Gets random or specific action

Parameters

Returns Object { Action, element }

_initActionsHelper

src/tester/actions/ActionsHandler.js:92-94

Initializes actions helper

_loadActions

src/tester/actions/ActionsHandler.js:99-124

Loads all defined actions

_getAvailablePageActions

src/tester/actions/ActionsHandler.js:132-151

Parameters

Returns Promise<Array<Object>> Returns array of objects with keys Action and element, which are all available page actions

ActionsHelper

src/tester/actions/ActionsHelper.js:4-134

Useful helpers that can be used by any action

Parameters

waitForReadyState

src/tester/actions/ActionsHelper.js:21-41

Resolves when page readyState equals to one of specified states. If the states are not equal after specified timeout, error is thrown.

Parameters

  • page puppeteer.Page

  • options Object?

    • options.timeout number (optional, default 30000)
    • options.states Array<string> document.readyState values (optional, default [interactive,complete])
    • options.checkInterval number (optional, default 50)

getAllVisiblePageElements

src/tester/actions/ActionsHelper.js:48-68

Searches for all visible elements in DOM

Parameters

  • page puppeteer.Page

Returns Promise<Array<puppeteer.ElementHandle>> Array of elements

getElement

src/tester/actions/ActionsHelper.js:76-78

Searches for an element based on action configuration

Parameters

  • page puppeteer.Page
  • actionConfig Object (optional, default {})

Returns Promise<puppeteer.ElementHandle> element

getElementSelector

src/tester/actions/ActionsHelper.js:85-89

Creates a selector for the element

Parameters

  • element puppeteer.ElementHandle

Returns Promise<string> selector

highlightElement

src/tester/actions/ActionsHelper.js:96-114

Highlights the element in the dom by adding some styles

Parameters

  • element puppeteer.ElementHandle

Returns Promise Resolves when element highlight is started

getElementHTML

src/tester/actions/ActionsHelper.js:120-124

Parameters

  • element puppeteer.ElementHandle

Returns Promise<string> element.outerHTML

isElementVisible

src/tester/actions/ActionsHelper.js:131-133

Checks if an element is visible

Parameters

  • element puppeteer.ElementHandle

Returns Promise<boolean> true if an element is visible

BackAction

src/tester/actions/BackAction.js:9-51

Extends AbstractAction

Back action, which will click on random or specific (if actionConfig is passed) page element

action

src/tester/actions/BackAction.js:33-39

Performs the back action on document

Parameters

  • element puppeteer.ElementHandle
  • page puppeteer.Page

Returns Promise Resolves when back event is done

updateResults

src/tester/actions/BackAction.js:46-50

Adds clicked element info to the action results

Parameters

Returns Object

id

src/tester/actions/BackAction.js:13-15

Returns string 'back'

isActionAvailable

src/tester/actions/BackAction.js:21-25

Back action should be always possible

Parameters

  • element
  • page

Returns boolean true

ClickAction

src/tester/actions/ClickAction.js:8-55

Extends AbstractAction

Click action, which will click on random or specific (if actionConfig is passed) page element

action

src/tester/actions/ClickAction.js:34-43

Performs the click action with following wrappers:

  • Hover over the element

(So that in preview mode, you will see the element before click)

  • Signal click on the element (Only in headfull mode)
  • Click on the element

Parameters

  • element puppeteer.ElementHandle
  • page puppeteer.Page

Returns Promise Resolves when click is done

updateResults

src/tester/actions/ClickAction.js:50-54

Adds clicked element info to the action results

Parameters

Returns Object

id

src/tester/actions/ClickAction.js:12-14

Returns string 'click'

isActionAvailable

src/tester/actions/ClickAction.js:20-22

Click action should be always possible

Returns boolean true

TypeAction

src/tester/actions/TypeAction.js:11-88

Extends AbstractAction

Type action, which will type a random text into a random input element. Or a specific text into a specific element, when actionsConfig is specified.

action

src/tester/actions/TypeAction.js:52-63

Performs the type action with following wrappers:

  • Hover over the element

(So that in preview mode, you will see the element before typing)

  • Highlight the element (Only in headfull mode)
  • Type the configured or random text into the element

Parameters

  • element puppeteer.ElementHandle
  • page puppeteer.Page

Returns Promise Resolves when typing is done

_getText

src/tester/actions/TypeAction.js:69-75

Returns string Text from action config, or random string the list of available texts

updateResults

src/tester/actions/TypeAction.js:82-87

Adds info to the action results

Parameters

Returns Object

id

src/tester/actions/TypeAction.js:15-17

Returns string 'type'

isActionAvailable

src/tester/actions/TypeAction.js:24-40

Checks if an elements is a typable input or textarea

Parameters

  • element puppeteer.ElementHandle

Returns boolean

KNOWN_FATAL_ERROR_MESSAGES

src/tester/browser/Browser.js:8-10

These errors will not cause test run to exit as failrue

Browser

src/tester/browser/Browser.js:15-168

Browser instance

Parameters

browser

src/tester/browser/Browser.js:34-36

Returns puppeteer.Browser

page

src/tester/browser/Browser.js:41-43

Returns puppeteer.Page

pageErrorHandler

src/tester/browser/Browser.js:53-55

Page error handler recieves 'page-error' event whenever an error occures on the page. Action should add listener to this handler and listen to the 'page-error' event to see if the action caused an error on the page.

Returns Function

unknownExecutionErrorOccured

src/tester/browser/Browser.js:60-62

Test run with execution error will fail only when unknown execution error occured

initBrowser

src/tester/browser/Browser.js:68-77

Initializes browser instance

Returns Promise<Browser>

clear

src/tester/browser/Browser.js:83-87

Clears browser instance

Returns Promise Resolves when the instance is cleared

_getBrowser

src/tester/browser/Browser.js:96-110

Gets browser instance from puppeteer. If there is a config.browserWebSocketEndpoint set, it will connect to remote chrome instance, otherwise it will create new instance locally

Returns Promise<puppeteer.Browser>

_initFatalErrorHandler

src/tester/browser/Browser.js:118-134

Whenever a page error occures, there is a strong possibility, that QApe tester is in inconsistent state. So it will try to clear the instance and wait for the new test run.

_handleUnknownExecutionErrors

src/tester/browser/Browser.js:140-146

Sets unknown execution error indicator

Parameters

_initPageErrorHandler

src/tester/browser/Browser.js:153-160

Initializes pageErrorHandler, exposes it to the page instance and loads config.pageErrorHandler

Returns Promise Resolves when handler is initialized

_getEventEmitter

src/tester/browser/Browser.js:165-167

Returns EventEmitter

tester

src/tester/index.js:12-23

index

src/tester/index.js:12-23

Initializes a tester worker. It handles the test execution.

Parameters

Returns Runner

messanger

src/tester/messanger.js:9-11

report

src/tester/messanger.js:9-11

Sends a message to the reporter

Parameters

  • eventName string
  • eventData any

requestScenario

src/tester/messanger.js:19-29

Requests a scenario from the scripwriter

Returns Promise<Object> Resolves with scenario, or an empty object

sendFailingScenario

src/tester/messanger.js:36-38

Sends a failing scenario to the scripwriter

Parameters

Runner

src/tester/Runner.js:9-109

QApe runner class which sets up the whole test run.

Parameters

start

src/tester/Runner.js:26-36

Initializes all dependencies and starts all parallel instances.

Returns Promise Resolves for successful run, rejects for failure

_startInstance

src/tester/Runner.js:42-78

Starts single test instance with all dependencies

Returns Promise

_getBrowserInstance

src/tester/Runner.js:84-86

Initializes browser instance

Returns Browser instance

_init

src/tester/Runner.js:91-94

Initializes all runner dependencies

_initActionsHandler

src/tester/Runner.js:99-101

Initializes ActionsHandler instance

_initScenariosHandler

src/tester/Runner.js:106-108

Initializes ScenariosHandler instance

DefinedScenarios

src/tester/scenarios/DefinedScenarios.js:8-55

Defined scenarios are saved scenarios from previous runs, or manually created. They are executed with higher priority, than random scenarios.

Parameters

type

src/tester/scenarios/DefinedScenarios.js:23-25

Specifies scenario type name

Returns string 'defined'

runScenario

src/tester/scenarios/DefinedScenarios.js:33-54

Runs a scenario defined by the user.

Parameters

Returns Promise

FailingScenarios

src/tester/scenarios/FailingScenarios.js:8-112

FailingScenarios is initialized, when page error occured. It tries to reproduce the error and tell you the exact steps, how to do that.

Parameters

type

src/tester/scenarios/FailingScenarios.js:23-25

Specifies scenario type name

Returns string 'failing'

runScenario

src/tester/scenarios/FailingScenarios.js:35-74

Runs a scenario, which tries to reproduce an error from the random/defined scenario with minimal number of steps.

Parameters

Returns Promise

_getNumberOfRetryActions

src/tester/scenarios/FailingScenarios.js:81-87

Parameters

Returns number Allowed number of actions from history to reproduce the error based on scenario length and config.

_reduceScenarioSteps

src/tester/scenarios/FailingScenarios.js:96-111

Removes scenario actions, that are not necessary to reproduce the error

Parameters

Returns Object Minified scenario reproducing the error

RandomScenarios

src/tester/scenarios/RandomScenarios.js:8-104

Random scenarios are default types of scenarios executed whenever there is nothing else to execute. They randomly click on the website and search for errors.

Parameters

type

src/tester/scenarios/RandomScenarios.js:26-28

Specifies scenario type name

Returns string 'random'

runScenario

src/tester/scenarios/RandomScenarios.js:38-61

Executes a random scenario performing actions on random page elements and trying to produce some page errors.

Parameters

Returns Promise<Object> results

_performActions

src/tester/scenarios/RandomScenarios.js:68-103

Performs random actions on the instance

Parameters

Returns Promise<Object> results

ScenariosHelper

src/tester/scenarios/ScenariosHelper.js:4-68

Scenarios helpers

Parameters

runScenario

src/tester/scenarios/ScenariosHelper.js:21-67

Executes specified scenario

Parameters

Returns Promise<Object> Execution results