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. |