Dancing-yaml NPM

Write, test and repeat using YAML syntax

Highlights

No programming
Very simple installation steps
Automated tests in plain Yaml
Visual regression tests in minutes
Browser compatibility checks
Designed for test engineers, product teams

Installation

IMPORTANT: Given this package is a node project, let's ensure to install node and npm as pre-requisites before setting up the project. For further info.

npx setup-dance-studio demo-project

Running the above command automatically sets up project structure, along with example files. This section provides the details on how the project resources are organised.

In order to run the tests, the following command does the job:

cd demo-project
npm run test

Quick Start

Step 1 : The src folder under the project is going to be a root directory for all testing stuff, and the most of the project contents will be inside resources directory.
Step 2 : Under resources folder, let's create tests folder which will contain test files in a plain YAML format. Note that, this package dancing-yaml identifies a file as a test file only if it ends in *test.yaml. More on how to write tests?
Step 3 : Many a times, CSS and XPath values used to identify html elements will be used in several places across test files. To keep all such values in centralized place, the folder elements needs to be created within resources. Just like test files, the element files need to be ending in *element.yaml The following snippet shows some example element yaml.
```
	```yaml
		### Login page elements' xpath and css

		login_email: "[name='email']"
		login_password: "[name='password']"
		login_button: "//button[normalize-space()='Login']"
		home_logo: "a[href*='home']"
	```
```
Step 4 : The next step is, the folders extracted-contents and snapshots need to be created to save all contents extracted during testing to external files and to keep golden copies of screenshots that will be verified against app under tests during testing respectively.
Step 5 : All common configurations such as browser, env etc will have to be in the file: config.yaml under config folder. The following snippet shows some examples.

```yaml
	browser: chrome
	headless: false
	device: Desktop Chrome
	url: https://github.com/5v1988/dancing-yaml
```

— Step 6 : Lastly, to run all tests, the test runner runMe.js needs to be created in the project as follows:

  import runMe from 'dancing-yaml'
  runMe();

Now execute tests using node src/runMe.js ( or npm run test) from command line. Note that, not necessarily that the runner method must always be named as runMe; Once all setup is complete, the below is the expected project structure

.
├── README.md
├── node_modules
├── package-lock.json
├── package.json
└── src
    ├── resources
    │   ├── config
    │   │   └── config.yaml
    │   ├── elements
    │   │   └── todo-element.yaml
    │   ├── reports
    │   │   ├── results.html
    │   │   └── results.json
    │   ├── snapshots
    │   │   ├── original-screenshot-1.png
    │   │   └── reference-screenshot-1.png
    │   └── tests
    │       └── todo-test.yaml
    └── runMe.js

Write Tests

— Tests are expected to be written in Yaml files, otherwise known as test files while using this package. Each of these tests should have to be written using well known testing format: Arrange-Act-Assert

description: Some tests on cypress todo demo site
tests:
 - name: Set and delete todo lists
   exclude: false

   arrange:
     - name: openUrl
       url: url

   act:
     - name: Add the first item
       id: 10001
       role: textbox
       text: What needs to be done?
       action: type
       value: Schedule doctor appointment

     - name: Press Enter
       pause: 1
       action: press
       value: Enter

     - name: Add the second item
       locator: .new-todo
       action: type
       value: Prepare a blog content

     - name: Press Enter
       pause: 1
       action: press
       value: Enter

     - name: Add the third item
       refId: 10001
       value: Fix the air conditioner

     - name: Press Enter
       pause: 1
       action: press
       value: Enter

     - name: Screenshot after adding all items
       pause: 1
       action: snapshot
       path: "src/example/resources/snapshots/original-screenshot-1.png"    

     - name: Hover to the first item
       text: Schedule doctor appointment
       action: hover

     - name: Delete the first item
       pause: 2
       locator: "//div[normalize-space()='Schedule doctor appointment']//button"
       action: click

     - name: Hover to the second item
       text: Prepare a blog content
       action: hover

     - name: Delete the second item
       pause: 2
       locator: "//div[normalize-space()='Prepare a blog content']//button"
       action: click

     - name: Hover to the third item
       text: Fix the air conditioner
       action: hover

     - name: Delete the third item
       pause: 2
       locator: "//div[normalize-space()='Fix the air conditioner']//button"
       action: click

     - name: Screenshot after deleting all items
       pause: 1
       action: snapshot
       path: "src/example/resources/snapshots/original-screenshot-2.png"     

   assert:
     - name: Verify if the first item deleted
       pause: 2
       type: standard
       text: Schedule doctor appointment
       state: invisible

     - name: Verify if the second item deleted
       pause: 2
       type: standard
       text: Prepare a blog content
       state: visible

     - name: Verify if the third item deleted
       pause: 2
       type: standard
       text: Fix the air conditioner
       state: invisible

     - name: Compare screenshot after all items added
       type: snapshot
       original: "src/example/resources/snapshots/original-screenshot-1.png"
       reference: "src/example/resources/snapshots/reference-screenshot-1.png"

     - name: Compare screenshot after all items deleted
       type: snapshot
       original: "src/example/resources/snapshots/original-screenshot-2.png"
       reference: "src/example/resources/snapshots/reference-screenshot-2.png"

— A test file can have more than one test, however, our recommendation is to have a few of them, organized by some commonalities

— A test folder tests can contain several test files; No limits

— The high-level blocks — Arrange, Act and Assert, contain a sequence of steps to perform certain actions during testing.

Arrange Reference

Act Reference

Assert Reference

Roadmap

— X Browser — X Summary report — O Parameterized tests — O API — O Mobile

Contributing

We really appreciate and value the work that you do for this project. Needless to say, contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Code of Conduct

See the Code of Conduct for details. Basically it comes down to:

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.