Twist (Simple UI testing tool)

Twist is a simple UI testing CLI tool written in Go. Its main purpose is to help developers write simple and easy read & write YAML-based instructions and assertions to drive the browser in no time. (It still under development. Use it in your own cautious)

This tool is not like selenium or its alternatives, it's less advanced. It is built over chromedp which is built over DevTools Protocol (can not test firefox).

Contents

• Twist
  • Contents
  • Installation
  • Quick start
  • The Structure
  • Config file options
    • execute
    • timeout
    • output
    • order
  • Story file options
    • start
    • timeout
    • headless
    • instructions
  • instructions
  • assertions

Installation

Using Go

To install Twist package, you need to install Go and set your Go workspace first. (the compiled binaries will be added to this repo later)

1. The first need Go installed (version 1.13+ is required), then you can use the below Go command to install Twist.

$ git clone https://github.com/youssefsiam38/twist.git

2. make it available everywhere in your machine:

$ cd twist
$ go install

Download The binaries

twist is available as downloadable binaries from the releases page.

Quick start

# this will make a twist folder for you in the current directory with config file and stories folder with the initial values
$ twist init

$ twist

The Structure

The tool reads from config.yml and {your story name}.story.yml then writes to the twist/report(currently screenshots only). The twist/config.yml file which you can provide configurations about the entire flow of the tests (e.g timeout of the flow and the order of the user stories in which twist should follow), and the twist/stories/{your story name}.story.yml include configurations, instructions and assertions for each user story in your application

Config file options

execute

execute: in order # in parallel support will be added soon

timeout

timeout: 30m # the timeout of the context of all stories

output

output: stdout # file reporting will be added soon

order

# The order in which the tests will be executed, the name you put here is the first level extention of the file in the stories folder. e.g blog here will execute {blog}.story.yml
order: 
- blog 
- documentation

Story file options

start

start: https://youssefsiam.me # the url that the story will begin from

timeout

timeout: 2m # the timeout of the this specific story

headless

headless: false # choose the mode of the user story test (default: false)

instructions

# The list of instructions and assertions in order
instructions:
- waitFor: 
    selector: "#about"
- click: "#about"
- asserPathIs: /about

instructions

click

instructions:
- click: 
    selector: "#about"

or, since selector is the only paramater

instructions:
- click: "#about"

doubleClick

instructions:
- doubleClick: 
    selector: "#home"

or

instructions:
- doubleClick: "#home"

rightClick

instructions:
- rightClick: 
    selector: "#home"

or

instructions:
- rightClick: "#home"

navigate

instructions:
- navigate: "https://youssefsiam.me"
- assertPathIs: "https://youssefsiam.me/"

refresh

instructions:
- do: "refresh"

saveScreenshotTo

instructions:
# give it the name of the file that you like to save to in the twist/report folder
- saveScreenshotTo: about 

submit

instructions:
- submit: 
    selector: "#home"

or

instructions:
- submit: "#home"

type

instructions:
- type:
    selector: "input[type=\"email\"]"
    text: [email protected]
- submit: "input[type=\"email\"]"

waitFor

instructions:
- waitFor: 
    selector: "#about"

or, since selector is the only paramater

instructions:
- waitFor: "#about"

waitUntilMissing

instructions:
- waitUntilMissing: 
    selector: "#about"

or, since selector is the only paramater

instructions:
- waitUntilMissing: "#about"

assertions

assertPathIs

instructions:
- assertPathis: 
    name: "Blog home page assertion"
    expect: "https://youssefsiam.me"

or

instructions:
- assertPathis: "https://youssefsiam.me"

this way the assertion name will be assertPathIs

assertText

instructions:
- assertText: 
    name: "The text is `about` assertion"
    expect: "about"
    selector: "button#about"