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.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Rohith R 💻

Alan Yee 💻

Vishwa 💻

jdfalko 📖

Rocio Montes 📖

This project follows the all-contributors specification. Contributions of any kind welcome!