automation-for-humans

Converts English statements to Selenium Automation.

Architecture

Demo

How to use

See integrating-with-any-environment to see how to install the dependencies.
Install the parser. See the DSL repo for more details.

git submodule update --init
make -C dsl/ alpine

Write English statements for some flow.
- See github navigation demo for reference.
Define a suite say public-sites. Write the test cases to execute inside.

{
    "name": "public-sites",
    "platform": "web",
    "executables": [
        {
            "name": "github",
            "type": "file",
            "location": "sample-inputs/public-sites/github-nav-demo.txt"
        }
    ]
}

Add the suite to the run.json

{
    "execution-mode": "parallel",
    "runnables": [
        "suites/public-sites.json"
    ]
}

Run the code from the root directory :

python3 src/automate.py

After the code is executed, one can see the screenshots and the gif in the recordings/ folder created.

English Keywords

Keyword	Use	Example
`open`	Used to open a url/application	`open "https://github.com/"`
`click`	Used to click on an element	`click on "Issues"`
`type`	Used to type a string in some element	`type "afh-random-user" in "Pick a username"`
`wait`	Waits for a particular amount of time in seconds	`wait for "10"`
`hover`	Used to hover over an element	`hover on "Fragments"`
`assert`	Used for asserting elements are present on the screen	`assert "Milestones"`
`execjs`	Used to execute javascript inside the browser context	`execjs "localStorage.setItem('random-key', 'false');"`

That's all! We currently support only a minimum set of keywords and intend to keep to it that way. There is some advanced-searching that you can do with the same keywords, explained in advanced-keywords-use.

Core Philosophy

The core philosophy of automation-for-humans is that the automation tests should mimic the user's behavior. Then we ask ourselves the question, what all things can a user do while they are interacting with the UI that we have built. The most common actions that a user does is click, type, hover. More complex actions include drag-and-drop, click-and-drag etc. Supporting the complex actions would involve and non-trivial pixel math which automation-for-humans does not plan to support in the initial phase.

Another aspect core to automation-for-humans is that it does not store XPath's and use it as an identifier while running the tests. Instead automation-for-humans stores only the text, which is how the user sees and interacts with the page.

Integrating with any environment

Integrating with automation-for-humans is extremely simple and involves just one step, installing the dependencies.

OS support :


install-dependencies-win.bat	install-dependencies-linux.sh	install-dependencies-mac.sh	automation-for-humans/docker-image

CI-Platforms :


.circleci/config.yml	.travis.yml (For Mac)	.appveyor.yml (For Windows)

Advanced Keywords Use

Sometimes one has no choice but to use the id's, class, automation-id attributes to identify elements on the web-page. For such edge-cases, and to provide completeness to the testing framework, automation-for-humans exposes an additional feature with most keywords.

Keyword	Use	Example
`click`	Used to click on an element with id "issues-id"	`click on "issues-id" "id"`
`click if present`	Used to click on an element if its present	`click if present on "issues-id"`
`type`	Used to type a string in some element with class name `"#user-name"`	`type "afh-random-user" in "#user-name" "class"`
`assert`	Used for asserting an element with href as `"/intuit/automation-for-humans"`	`assert "/intuit/automation-for-humans" "href"`

One can search for an element with any attribute using the above syntax.

Resolving ambiguity

If multiple elements exist on the page that look alike(text-wise) then there is ambiguity by specifying the order in which they appear. Defaults to the 1st element that appears if nothing is specified.

Keyword	Use	Example
`click`	Used to click on the 2nd issue	`click on 2nd "issue"`
`type`	Used to type a string in the 4th text box named "enter text here"	`type "afh-random-user" in 4th "enter text here"`

Experimental Features

Mac OS X UI Automation

automation-for-humans also works with automating Mac OS X apps. It uses Appium For Mac as the underlying driver.

Currently it supports interaction by specifying the AXPath's. This is completely against the core-philosophy that automation should be done in a way the user would interact with the UI rather than hidden details and xpath's. Support for using it without specifying AXPath's is being worked on.

New Keywords added :

Keyword	Use	Example
`wait until`	Used to wait until the element is visible	`wait until "/AXApplication[@AXTitle='Calculator']"`

Record and Replay functionality for Mac OS X apps

automation-for-humans provides a record and replay functionality for users to records the actions and replay them. In fact the sample-inputs/mac-osx-apps/calculator.txt has been generated using the same functionality.

To records, first start Appium For Mac. Then in the terminal execute :

python3 src/action-recorder-mac.py <app-name> <output-file-path>

Press Ctrl + C to terminate the script from recording.

This will produce a file with all the commands that you have executed in a way that automation-for-humans understands. For readability, the script also adds in a comment before each line (starting with #) which attempts to be the English version of the same command.

Atom Syntax Highlights Package

automation-for-humans supports syntax highlighting for the Atom editor, which can be found at atom-syntax-highlight. Clone the folder into Atom's packages folder (~/.atom/packages for MacOS), and reload Atom to use it.