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 data = module.start({info:'foo'}) //start state input
    .then(res => { 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	(error:any, 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.