Skip to content

intuit/automation-for-humans

Repository files navigation

automation-for-humans

circle-ci Build Status Build status Codacy Badge All Contributors

Converts English statements to Selenium Automation.

Architecture

Demo

How to use

git submodule update --init
make -C dsl/ alpine
  • Write English statements for some flow.
  • 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"
        }
    ]
}
{
    "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 :

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
Rohith R

πŸ’»
Alan Yee
Alan Yee

πŸ’»
Vishwa
Vishwa

πŸ’»
jdfalko
jdfalko

πŸ“–
Rocio Montes
Rocio Montes

πŸ“–

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