Puppeteer-staircase NPM

puppeteer-staircase

Staircase framework for puppeteer

Example Use

  import Staircase from 'puppeteer-staircase';
  import { Browser } from "puppeteer";

  const step1 = new Staircase.Step('first-step', async (state: Staircase.State<{info?:string}, {res?:string}>, browser: Browser) => {

    const page = (await browser.pages())[0]; // example DOM interaction
    await page?.goto('https://github.com');

    console.log(state.data, state.result); // prints {info: 'foo'} and {res: null} as in the module initialState

    state.data = {...state.data, info: 'bar'} // state data change

    return state; // always return state for persistence
  })

  const step2 = new Staircase.Step('second-step', async (state: Staircase.State<{info?:string}, {res?:string}>, browser: Browser) => {

    console.log(state.data, state.result); // prints {info: 'bar'} and {res: null}

    state.result = {...state.result, res: 'some return'} // state result change

    return state; // return state for persistence
  })

  const module = new Staircase.Module<{info?:string}, {res:null}>('module-name', [step1, step2], undefined, {result:{res: null}})

  const result = module.start({info:'foo'}) //start state input

  console.log(result) // prints {res: 'some return'}

Definitions

Object: State \<`T`, `K`>

The data collection that is persistent through steps.

Types

Type	Description
`T`	Input data that is needed for execution, can be changed during runtime.
`K`	Output data that is returned at the end of a module, should be changed during runtime.

Object: Logger

Object that contains a pair of functions as properties. Must be filled to enable built-in behaviour logging.

Types

Type	Signature
`info`	`(message:string) => void`
`error`	`(message:string) => void`

Object: ModuleConfig\<T, K>

Object that contains the options and methods of a module's setup.

Types

Type	Signature	Description
`preSetupFn`	`(state:State<T, K>) => Promise\<{ state:State\<T, K\>, launchOptions?:Partial\<PuppeteerLaunchOptions\> }\>`	Pre browser launch setup function, state and lanchOptions returned are persisted
`PostSetupFn`	`(browser: Browser, state:State<T, K>) => Promise\<State\<T, K\>\>`	Post browser launch setup function, state returned is persisted and has access to browser instance.
`onError`	`(state:State<T, K>) => Promise<void>`	Method called on module's execution fail.
`onSccess`	`(state:State<T, K>) => Promise<void>`	Method called on module's execution succeed.
`launchOptions`	`PuppeteerLaunchOptions`	LaunchOptions for puppeteer

Class: Step \<`T`, `K`>

The cornerstone class of this framework, the base of the DOM interaction via the implementation parameter.

Types

Type	Description
`T`	Input data that is needed for execution, can be changed during runtime.
`K`	Output data that is returned at the end of a module, should be changed during runtime.

Parameters

Name	Type	Description
`id`	`string`	Unique name of a step
`implementation`	`StepFn`\<`T`, `K`>	A Function with acces to browser and state, the most basic step type and the one where should happen DOM interaction
`logger?`	`Logger`	Optional two log functions that enable loggin of internal behaviour ( recommended )
`proxy?`	`"on"` \| `"off"`	Turns on or off the use of the proxy set in the PROXY_URL env variable

Class: Action \<`T`, `K`>

A group of steps that should be executed.

Types

Type	Description
`T`	Input data that is needed for execution, can be changed during runtime.
`K`	Output data that is returned at the end of a module, should be changed during runtime.

Parameters

Name	Type	Description
`id`	`string`	Unique name of a step
`steps`	`IStep\<T, K\>[]`	Array of Steps to be executed
`logger?`	`Logger`	Optional two log functions that enable loggin of internal behaviour ( recommended )

Class: Repeat \<`T`, `K`>

A group of steps that will execute again in case of error, up to a limit of attempts.

Types

Type	Description
`T`	Input data that is needed for execution, can be changed during runtime.
`K`	Output data that is returned at the end of a module, should be changed during runtime.

Parameters

Name	Type	Description
`id`	`string`	Unique name of a step
`steps`	`IStep\<T, K\>[]`	Array of Steps to be executed
`logger?`	`Logger`	Optional two log functions that enable loggin of internal behaviour ( recommended )
`limit?`	`number`	Ammount of attempts allowed throwing the error. defaults to 3.

Class: Decision \<`T`, `K`>

A step that may execute differents steps depending on a evaluation function decisionFn.

Types

Type	Description
`T`	Input data that is needed for execution, can be changed during runtime.
`K`	Output data that is returned at the end of a module, should be changed during runtime.

Parameters

Name	Type	Description
`id`	`string`	Unique name of a step
`decisionFn`	`(state?:State<T, K>, browser?: Browser) => Promise<string>`	A function with access to browser and state that returns a string representing an avaliable key in the 'actionMap'
`actionMap`	`Record<string, IStep<T, K>[]>`	A Dictionary-like structure to map a key to an array of steps
`logger?`	`Logger`	Optional two log functions that enable loggin of internal behaviour ( recommended )

Class: Module \<`T`, `K`>

The core class that starts the state object, setup of the browser and execution of the collection of steps.

Types

Type	Description
`T`	Input data that is needed for execution, can be changed during runtime.
`K`	Output data that is returned at the end of a module, should be changed during runtime.

Parameters

Name	Type	Description
`mId`	`string`	Unique name of a module
`steps`	`IStep\<T, K\>[]`	Array of Steps to be executed
`logger?`	`Logger`	Optional two log functions that enable loggin of internal behaviour ( recommended )
`initialState?`	`Omit\<State\<T, K\>, onExec\\|success\\|startTime\>`	The state before the execution starts.
`config?`	`ModuleConfig\<T, K\>`	The state before the execution starts.