Web Cog

This is a Crank Cog for basic web interactions, providing steps and assertions for you to run against your website. This Cog leverages Chrome (via Puppeteer) to interact with websites. Puppeteer is configured in a headful manner in order to ensure the highest likelihood possible that websites behave in the same way they do for real humans.

• Installation
• Usage
• Development and Contributing

Installation

Ensure you have the crank CLI and docker installed and running locally, then run the following.

$ crank cog:install automatoninc/web

Usage

Authentication

This Cog does not require any authentication details.

Steps

Check current page info

• Expression: the (?<field>status|text|url) of the current page should (?<operator>contain|not contain|be) (?<expectation>.+)
• Expected Data:
  • field: Page Detail (status, text, or url)
  • operator: Check Logic (contain, not contain, or be)
  • expectation: Expected Value
• Step ID: CheckCurrentPageInfo

Check current page meta tag

• Expression: the (?<metaName>.+) meta tag on the current page should (?<operator>be|contain|not contain|not be longer than|exist) ?(?<expectation>.+)?
• Expected Data:
  • metaName: Meta Tag name
  • operator: Check Logic (be, contain, not contain, not be longer than, exist)
  • expectation: Expected Value
• Step ID: CheckCurrentPageMetaTag

Fill out a form field

• Expression: fill out (?<domQuerySelector>.+) with (?<value>.+)
• Expected Data:
  • domQuerySelector: Button's DOM Query Selector
  • value: Field Value
• Step ID: EnterValueIntoField

Navigate to a webpage

• Expression: navigate to (?<webPageUrl>.+)
• Expected Data:
  • webPageUrl: Page URL
• Step ID: NavigateToPage

Submit a form by clicking a button

• Expression: submit the form by clicking (?<domQuerySelector>.+)
• Expected Data:
  • domQuerySelector: Button's DOM Query Selector
• Step ID: SubmitFormByClickingButton

Development and Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to add or update tests as appropriate.

Setup

1. Install node.js (v10.x+ recommended)
2. Clone this repository.
3. Install dependencies via npm install
4. Run npm start to validate the Cog works locally (ctrl+c to kill it)
5. Run crank cog:install --source=local --local-start-command="npm start" to register your local instance of this Cog. You may need to append a --force flag or run crank cog:uninstall automatoninc/web if you've already installed the distributed version of this Cog.

Adding/Modifying Steps

Modify code in src/steps and validate your changes by running crank cog:step automatoninc/web and selecting your step.

To add new steps, create new step classes in src/steps. Use existing steps as a starting point for your new step(s). Note that you will need to run crank registry:rebuild in order for your new steps to be recognized.

Always add tests for your steps in the test/steps folder. Use existing tests as a guide.

Modifying the API Client or Authentication Details

Modify the ClientWrapper class at src/client/client-wrapper.ts.

• If you need to add or modify authentication details, see the expectedAuthFields static property.
• If you need to expose additional logic from the wrapped API client, add a new ublic method to the wrapper class, which can then be called in any step.
• It's also possible to swap out the wrapped API client completely. You should only have to modify code within this clase to achieve that.

Note that you will need to run crank registry:rebuild in order for any changes to authentication fields to be reflected. Afterward, you can re-authenticate this Cog by running crank cog:auth automatoninc/web

Tests and Housekeeping

Tests can be found in the test directory and run like this: npm test. Ensure your code meets standards by running npm run lint.