gedex / simflow

Simply define and run your flows in Chrome.

simflow

Simply define and run your flows in Chrome.

Install

npm i -g simflow

Usage

simflow <flows...> [options...]

Flows are defined in JSON config file.

Example

This example demonstrates a simple flow of searching GitHub project and take a sreenshot of search results.

• Create example-gh-simflow.json:

  {
    "url": "https://github.com",
    "references": {
      "searchField": "[name='q']",
      "searchButton": "[type='submit']"
    },
    "flows": {
      "search": [
        "Goto '/search'",
        "See searchField",
        "Type in searchField 'simflow'",
        "See searchButton",
        "Click searchButton",
        "Wait page { to: 'reload' }",
        "Save screenshot as 'search-results.png'",
        "Save page as 'search-results.html'"
      ]
    }
  } 

• Run search flow from example-gh-simflow.json config file:

  simflow search -c ./example-gh-simflow.json
  

Config

This is under heavy development and structure may changes.

Key	Type	Description
url	string	Required. Base URL. New page opens this URL. Defined path (i.e., Goto /path) in steps section uses this base URL.
references	object	List of references to be used in steps of a flow.
flows	objects	Required. Flow names mapped to array of steps. Named flows are passed to simflow as args.

Step

Step is a string with grammar defined in a PEG file lib/step.pegjs.

Some example of steps:

// Use reference.
Click namedSelector
Click namedSelector@frameName

// Use literal string for selector.
Click '.header h1'@'frameName'

Type into namedSelector "hello world"

Press 'Enter'

// Step arguments.
Press 'Enter' { delay: 1000 }
Save screenshot as './screenshots/filename.png' { fullPage: true }
Save page as './pages/index.pdf' { output: 'pdf' }

simflow's Issues

Remove template config

Unnecessary extra in code base. Example in real usage or in README should be enough.

Merge users, frame, and selectors into one member (references)

collapse args for Listr is buggy when scrolling

Add step select

https://pptr.dev/#?product=Puppeteer&version=v1.11.0&show=api-pageselectselector-values

Example steps

Select namedSelector 'val1, val1'
Select 'css-selector'@'frame-name' 'val1, val2'

Added CI

Define step grammar and use parser based on grammar

Currently step parsing is quite hacky.

Config unit test

Remember thing

Proposed step definition:

"steps": {
  "Remember text in selectorName as variableName", // store variableName as reference
  "See selectorName(variableName)" // assert reference later with dynamic selector (#7)
}

Add wait request / response steps

Remove states (inputState, outputState, and initialState)

It's only used to make sure passed flow orgs are in order based on input / output state. Seem useless if we know already what to run.

Use regex pattern for inputState and outputState

This would allow multiple values in state like:

hasCard|loggedIn

Support dynamic selector and XPath selector

By dynamic, it allows us to define named selector which accepts arguments and replaced with dynamic value during running-flow.

Proposed solution for XPath support

"frames": {
  "sidebar": "sidebarFrame__.*"
},
"selectors": {
  "selectorName": {
    "type": "xpath", // default to "css".
    "selector": "//button[text()=\"Submit\"]"
  }
}

and use it in steps as usual:

"steps": [
  "See selectorName", 
  "See selectorName@sidebar", // With frame
  "Click selectorName"
]

Proposed solution for dynamic selector

"frames": {
  "sidebar": "sidebarFrame__.*"
},
"selectors": {
  "selectorName1": "#posts-list $1[@title='$2']", // default to "css".
  "selectorName2": {
    "type": "xpath",
    "selector": "//button[text()=\"$1\"]"
  }
},

and use it in steps:

"steps": [
  "See selectorName1('a.title', 'title to pass')]", 
  "See selectorName1@sidebar('a.title', 'title to pass')", // With frame
  "Click selectorName2('Submit')"
]

Allow to check text in selector in a step definition

Proposed step:

"See selectorName with text equal to blabla", // use `===` (trimmed on input)
"See selectorName with text like blabla", // use `.match()`
"See selectorName with text includes blabla", // use `.includes()`
"Click selectorName with text like blabla", 

Add linter in npm scripts

Add frames in config

This would allow looking for selectors in frames other than main frame.

Proposed frames config:

frames: {
  "frameName": "regex pattern"
}

Specifying selector in specific iframe inside steps:

"steps": [
  "See button@frameName",
]

if no @frameName it defaults to main frame.

simflow arg to specify defautViewport

Currently use the default 800x600. By default it should be disabled unless specified via arg.