add readme and cli options

.gitignore

@@ -1,4 +1,5 @@
-*.MD
+README2.MD
 /*.html
 bin
-twist
+twist
+twist2

README.MD

@@ -0,0 +1,257 @@
+# Twist (Simple UI testing tool)
+
+<img align="right" width="209px" src="./logo/twistLogo.png">
+
+Twist is a simple UI testing CLI tool written in Go (Golang). 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. (I built this tool to test my personal projects. Use it in your own cautious)
+
+This tool is not like selenium or its alternatives, it's less advanced (has only two assertions!). It is built over [chromedp](https://github.com/chromedp/chromedp) which built over DevTools Protocol (can not test firefox).
+
+## Contents
+
+- [Twist](#twist-simple-ui-testing-tool)
+  - [Contents](#contents)
+  - [Installation](#installation)
+  - [Quick start](#quick-start)
+  - [The Structure](#the-structure)
+  - [Config file options](#config-file-options)
+    - [execute](#execute)
+    - [timeout](#timeout)
+    - [output](#output)
+    - [order](#order)
+  - [Story file options](#story-file-options)
+    - [start](#start)
+    - [timeout](#timeout)
+    - [headless](#headless)
+    - [instructions](#instructions)
+  - [instructions](#instructions)
+  - [assertions](#assertions)
+
+## Installation
+
+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](https://golang.org/) installed (**version 1.13+ is required**), then you can use the below Go command to install Twist.
+
+```sh
+$ git clone https://github.com/youssefsiam38/twist.git
+```
+
+2. make it available everywhere in your machine:
+
+```sh
+$ cd twist
+$ go install
+```
+
+## Quick start
+
+```sh
+# this will make a twist folder for you in the current directory with config file and stories folder with the initial values
+$ twist init
+```
+```sh
+$ twist
+```
+
+## The Structure
+
+The tool read from two types of yml files and writes only to the `twist/report`. 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 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
+
+```yaml
+execute: in order # in parallel support will be added soon
+```
+
+### timeout
+
+```yaml
+timeout: 30m # the timeout of the context of all stories
+```
+
+### output
+
+```yaml
+output: stdout # file reporting will be added soon
+```
+
+### order
+
+```yaml
+# 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
+
+```yaml
+start: https://youssefsiam.me # the url that the story will begin from
+```
+
+### timeout
+
+```yaml
+timeout: 2m # the timeout of the this specific story
+```
+
+### headless
+
+```yaml
+headless: false # choose the mode of the user story test (default: false)
+```
+
+### instructions
+
+```yaml
+# The list of instructions and assertions in order
+instructions:
+- waitFor: 
+    selector: "#about"
+- click: "#about"
+- asserPathIs: /about
+```
+## instructions
+
+### **click**
+
+```yaml
+instructions:
+- click: 
+    selector: "#about"
+```
+or, since *selector* is the only paramater
+```yaml
+instructions:
+- click: "#about"
+```
+
+### **doubleClick**
+
+```yaml
+instructions:
+- doubleClick: 
+	selector: "#home"
+```
+or
+```yaml
+instructions:
+- doubleClick: "#home"
+```
+
+### **rightClick**
+
+```yaml
+instructions:
+- rightClick: 
+	selector: "#home"
+```
+or
+```yaml
+instructions:
+- rightClick: "#home"
+```
+
+### **navigate**
+
+```yaml
+instructions:
+- navigate: "https://youssefsiam.me"
+- assertPathIs: "https://youssefsiam.me/"
+```
+
+### **refresh**
+
+```yaml
+instructions:
+- do: "refresh"
+```
+
+### **saveScreenshotTo**
+
+```yaml
+instructions:
+# give it the name of the file that you like to save to in the twist/report folder
+- saveScreenshotTo: about 
+```
+
+### **submit**
+
+```yaml
+instructions:
+- submit: 
+	selector: "#home"
+```
+or
+```yaml
+instructions:
+- submit: "#home"
+```
+
+### **type**
+
+```yaml
+instructions:
+- type:
+    selector: "input[type=\"email\"]"
+    text: [email protected]
+- submit: "input[type=\"email\"]"
+```
+
+### **waitFor**
+
+```yaml
+instructions:
+- waitFor: 
+    selector: "#about"
+```
+or, since *selector* is the only paramater
+```yaml
+instructions:
+- waitFor: "#about"
+```
+
+### **waitUntilMissing**
+
+```yaml
+instructions:
+- waitUntilMissing: 
+    selector: "#about"
+```
+or, since *selector* is the only paramater
+```yaml
+instructions:
+- waitUntilMissing: "#about"
+```
+
+## assertions
+
+### **assertPathIs**
+
+```yaml
+instructions:
+- assertPathis: 
+	name: "Blog home page assertion"
+    expect: "https://youssefsiam.me"
+```
+or
+```yaml
+instructions:
+- assertPathis: "https://youssefsiam.me"
+```
+this way the assertion name will be assertPathIs
+
+### **assertText**
+
+```yaml
+instructions:
+- assertText: 
+	name: "The text is `about` assertion"
+    expect: "about"
+	selector: "button#about"
+```

cmd/author.go

@@ -0,0 +1,16 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+var authorCmd = &cobra.Command{
+	Use:   "author",
+	Short:   "Prints the author name",
+	// Long:  ``,
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Println("© Youssef Siam (https://github.com/youssefsiam38)")
+	},
+}

cmd/init.go

@@ -0,0 +1,50 @@
+package cmd
+
+import (
+	"fmt"
+	"io/ioutil"
+	"os"
+
+	"github.com/spf13/cobra"
+	"github.com/youssefsiam38/twist/src/utils"
+)
+
+var initCmd = &cobra.Command{
+	Use:   "init",
+	Short:   "Creates the twist folder with the defaults",
+	Long:  `Creates the twist folder with the default values for you`,
+	Run: func(cmd *cobra.Command, args []string) {
+		if utils.FolderExist("twist") {
+			fmt.Println("twist folder is already exist")
+		} else {
+			err := os.Mkdir("twist", 0755)
+			if err != nil {
+				fmt.Println(err)
+			}
+			err = os.Mkdir("twist/stories", 0755)
+			if err != nil {
+				fmt.Println(err)
+			}
+
+			configBuf := []byte("execute: in order # or in parallel, if in parallel no need to specify the order\ntimeout: 70m\noutput: stdout # or filename\norder: \n- blog")
+
+
+			err = ioutil.WriteFile("twist/config.yml", configBuf, 0755)
+			if err != nil {
+				fmt.Println(err)
+			}
+
+			storyBuf := []byte(`execute: in order # or in parallel, if in parallel no need to specify the order
+			timeout: 70m
+			output: stdout # or filename
+			order: 
+			- blog
+			`)
+
+			err = ioutil.WriteFile("twist/stories/blog.story.yml", storyBuf, 0755)
+			if err != nil {
+				fmt.Println(err)
+			}
+		}
+	},
+}

cmd/main.go

@@ -10,15 +10,14 @@ import (
 
 func init() {
 	rootCmd.AddCommand(versionCmd)
-	rootCmd.Flags().StringVarP(&Verbose, "verbose", "v", "", "verbose output")
-	// rootCmd.MarkFlagRequired("verbose")
+	rootCmd.AddCommand(initCmd)
+	rootCmd.AddCommand(authorCmd)
+	// rootCmd.Flags().StringVarP(&Verbose, "version", "v", "", "Twist version")
 }
 
-var Verbose string
-
 var rootCmd = &cobra.Command{
-	Use:   "twist",
-	Short: "Twist is a convenient automated UI testing tool",
+	Use:   "run the test flow",
+	Short: "Twist is a Simple UI testing tool",
 	Long:  `A fast easy to read and write automation testing tool.Complete documentation is available at https://github.com/youssefsiam38/twist`,
 	Run: func(cmd *cobra.Command, args []string) {
 		if err := handle.Handle(); err != nil {

cmd/version.go

@@ -8,9 +8,8 @@ import (
 
 var versionCmd = &cobra.Command{
 	Use:   "version",
-	Short: "Print the version number of Twist",
-	Long:  `All software has versions. This is Twist's`,
+	Short:  `Print the version of Twist`,
 	Run: func(cmd *cobra.Command, args []string) {
-		fmt.Println("Twist automation testing tool v0.1")
+		fmt.Println("Twist v0.1")
 	},
 }

go.mod

@@ -5,8 +5,19 @@ go 1.16
 require (
 	github.com/chromedp/cdproto v0.0.0-20210823203301-2c0adcc9edc4
 	github.com/chromedp/chromedp v0.7.4
+	github.com/gobuffalo/envy v1.9.0 // indirect
+	github.com/gobuffalo/logger v1.0.4 // indirect
+	github.com/gobuffalo/packr v1.30.1 // indirect
+	github.com/gobuffalo/packr/v2 v2.8.1 // indirect
+	github.com/karrick/godirwalk v1.16.1 // indirect
+	github.com/konsorten/go-windows-terminal-sequences v1.0.3 // indirect
 	github.com/logrusorgru/aurora/v3 v3.0.0
+	github.com/rogpeppe/go-internal v1.8.0 // indirect
+	github.com/sirupsen/logrus v1.8.1 // indirect
 	github.com/spf13/cobra v1.2.1
+	golang.org/x/crypto v0.0.0-20210817164053-32db794688a5 // indirect
 	golang.org/x/sys v0.0.0-20210823070655-63515b42dcdf // indirect
+	golang.org/x/term v0.0.0-20210615171337-6886f2dfbf5b // indirect
+	golang.org/x/tools v0.1.5 // indirect
 	gopkg.in/yaml.v2 v2.4.0
 )