0.1.5 • Published 1 year ago

puppeteer-staircase v0.1.5

Weekly downloads
-
License
GPL-3.0-only
Repository
github
Last release
1 year ago

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

TypeDescription
TInput data that is needed for execution, can be changed during runtime.
KOutput 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

TypeSignature
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

TypeSignatureDescription
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.
launchOptionsPuppeteerLaunchOptionsLaunchOptions for puppeteer

Class: Step \<T, K>

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

Types

TypeDescription
TInput data that is needed for execution, can be changed during runtime.
KOutput data that is returned at the end of a module, should be changed during runtime.

Parameters

NameTypeDescription
idstringUnique name of a step
implementationStepFn\<T, K>A Function with acces to browser and state, the most basic step type and the one where should happen DOM interaction
logger?LoggerOptional 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

TypeDescription
TInput data that is needed for execution, can be changed during runtime.
KOutput data that is returned at the end of a module, should be changed during runtime.

Parameters

NameTypeDescription
idstringUnique name of a step
stepsIStep\<T, K\>[]Array of Steps to be executed
logger?LoggerOptional 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

TypeDescription
TInput data that is needed for execution, can be changed during runtime.
KOutput data that is returned at the end of a module, should be changed during runtime.

Parameters

NameTypeDescription
idstringUnique name of a step
stepsIStep\<T, K\>[]Array of Steps to be executed
logger?LoggerOptional two log functions that enable loggin of internal behaviour ( recommended )
limit?numberAmmount 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

TypeDescription
TInput data that is needed for execution, can be changed during runtime.
KOutput data that is returned at the end of a module, should be changed during runtime.

Parameters

NameTypeDescription
idstringUnique 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'
actionMapRecord<string, IStep<T, K>[]>A Dictionary-like structure to map a key to an array of steps
logger?LoggerOptional 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

TypeDescription
TInput data that is needed for execution, can be changed during runtime.
KOutput data that is returned at the end of a module, should be changed during runtime.

Parameters

NameTypeDescription
mIdstringUnique name of a module
stepsIStep\<T, K\>[]Array of Steps to be executed
logger?LoggerOptional 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.