Tests

A test is composed of a series of steps. Steps may be defined directly within a test or may be defined independently and imported into a test. A test may import steps, may import page models and may import data providers.

Syntax

A test is a YAML object. The most basic test specifies a browsers collection and starting url and defines steps directly.

config:
    browsers:
        - {browser-1}
        ...
        - {browser-N}
    url: {url}

{step-name-1}:
    {step}
...
{step-name-N}
    {step}

----------------------

browser-*:
    <string>

url:
    <url>

step-name-*:
    <string>

step:
    actions:
      - {action-1}
      ...
      - {action-N}

    assertions:
      - {assertion-1}
      ...
      - {assertion-N}

action-*:
    <action>

assertion-*:
    <assertion>

A step may be defined independently of the test and imported into any number of tests. Import names are user-defined. Import paths are relative to the test.

config:
    browsers:
        - {browser-1}
        ...
        - {browser-N}
    url: {url}

imports:
    steps:
        {step-import-name}: "{import-path}"

{step-name}:
    use: {step-import-name}

-------------------------------------------

step-import-name:
    <string>

import-path:
    <string>, a path to the file to import, relative to the location of the test

browser-*:
    <string>

url:
    <url>

step-name:
    <string>

A test may both define and import steps.

config:
    browsers:
        - {browser-1}
        ...
        - {browser-N}
    url: {url}

imports:
    steps:
        {step-import-name}: "{import-path}"

{step-name-1}:
    use: {step-import-name}
...
{step-name-N}
    {step}

-------------------------------------------

step-import-name:
    <string>

import-path:
    <string>, a path to the file to import, relative to the location of the test

browser-*:
    <string>

url:
    <url>

step-name-*:
    <string>

step:
    actions:
      - {action-1}
      ...
      - {action-N}

    assertions:
      - {assertion-1}
      ...
      - {assertion-N}

action-*:
    <action>

assertion-*:
    <assertion>

Imported steps that require parameters must have the parameter values passed at usage time.

Data can be supplied via the data property of the step. The data property can define one or more data sets. Each data set provides values for the parameters as required by a step.

config:
    browsers:
        - {browser-1}
        ...
        - {browser-N}
    url: {url}

imports:
    steps:
        {step-import-name}: "{import-path}"

{step-name}:
    use: {step-import-name}
    data:
        {data-set-name-1}:
            {parameter-name-1}: {parameter-value-1}
            ...
            {parameter-name-N}: {parameter-value-N}
        ...
        {data-set-name-N}:
            {parameter-name-1}: {parameter-value-1}
            ...
            {parameter-name-N}: {parameter-value-N}

---------------------------------------------------

step-import-name:
    <string>

import-path:
    <string>, a path to the file to import, relative to the location of the test

browser-*:
    <string>

url:
    <url>

step-name:
    <string>

data-set-name-*:
    <string>

parameter-name-*:
    <string>, must match the name of a parameter as required by a step

parameter-value-*:
    <string>

Data can be supplied through the import of a data provider. A data provider is a collection of data sets defined externally to the test.

config:
    browsers:
        - {browser-1}
        ...
        - {browser-N}
    url: {url}

imports:
    steps:
        {step-import-name}: "{import-path}"
    data_providers:
        {data-provider-import-name}: "{import-path}"

{step-name}:
    use: {step-import-name}
    data: {data-provider-import-name}

----------------------------------------------------

step-import-name:
    <string>

import-path:
    <string>, a path to the file to import, relative to the location of the test

browser-*:
    <string>

url:
    <url>

data-provider-import-name:
    <string>

step-name:
    <string>

Page models can be imported and their defined page properties referenced within the test.

config:
    browsers:
        - {browser-1}
        ...
        - {browser-N}
    url: {url}

imports:
    pages:
        {page-import-name}: "{import-path}"

{step-name}:
  actions:
    - open {import_name}

  assertions:
    - {page-import-name}.elements.{element-name} {operator} [{value}]

-----------------------------------------------------------------------

page-import-name:
    <string>

import-path:
    <string>, a path to the file to import, relative to the location of the test

browser-*:
    <string>

url:
    <url>

step-name:
    <string>

element-name:
    <string>, defined within the imported page model

operator:
    <string>, operator for assertion

value:
    <string>, value for assertion

Examples

Steps With Literal Values

# examples/test/google-search-query-literal.yml
config:
  browsers:
    - chrome
  url: https://www.google.com

"verify Google is open":
  assertions:
    - $page.url is "https://www.google.com"
    - $page.title is "Google"

"query 'example'":
  actions:
    - set $".gLFyf.gsfi" to "example"
    - click $".FPdoLc.VlcLAe input[name=btnK]"

  assertions:
    - $page.title is "example - Google Search"

Parameterised Steps With Inline Data

# examples/step/assert-page-open-parameterised.yml
assertions:
  - $page.url is $data.expected_url
  - $page.title is $data.expected_title

# examples/test/google-open-parameterised.yml
config:
  browsers:
    - chrome
  url: https://www.google.com

imports:
  steps:
    assert_opened_page_step: "../step/assert-page-open-parameterised.yml"

"verify Google is open":
  use: assert_opened_page_step
  data:
    # Just a single data set needed here
    0:
      expected_url: $config.url
      expected_title: "Google"

Parameterised Steps With Provided Data

# examples/step/google-search-query-parameterised.yml
actions:
  - set $".gLFyf.gsfi" to $data.search_term
  - click $".FPdoLc.VlcLAe input[name=btnK]"

assertions:
  - $page.title is $data.expected_title

# examples/data-provider/google-search-query.yml
foo:
  search_term: "foo"
  expected_title: "foo - Google Search"

bar:
  search_term: "bar"
  expected_title: "bar - Google Search"

# examples/test/google-search-query-parameterised.yml
config:
  browsers:
    - chrome
  url: https://www.google.com

imports:
  steps:
    query_step: "../step/google-search-query-parameterised.yml"
  data_providers:
    google_search_query_data: "../data-provider/google-search-query-parameterised.yml"

"verify Google is open":
  assertions:
    - $page.title is "Google"

"query":
  use: query_step
  data: google_search_query_data

Steps Imported Into the Test With Additional Assertions

# examples/step/google-assert-open-literal.yml
assertions:
  - $page.url is "https://www.google.com"
  - $page.title is "Google"

# examples/step/google-query-example-literal.yml
actions:
  - set $".gLFyf.gsfi" to "example"
  - click $".FPdoLc.VlcLAe input[name=btnK]"

assertions:
  - $page.title is "example - Google Search"

# examples/test/google-import-assert-open-import-query-additional-assertions.yml
config:
  browsers:
    - chrome
  url: https://www.google.com

imports:
  steps:
    google_assert_open: "../step/google-assert-open-literal.yml"
    google_query_example: "../step/google-query-example-literal.yml"

"verify Google is open":
  use: google_assert_open

  assertions:
    - $page.title excludes "error"

"query 'example'":
  use: google_query_example

Imported Page Model Used Directly Within Test

# examples/page/google.com.yml
url: "https://www.google.com"
elements:
  search_input: $".gLFyf.gsfi"
  search_button: $".FPdoLc.VlcLAe input[name=btnK]"

# examples/test/google-inline-tests-with-page-model.rst
config:
  browsers:
    - chrome
  url: google_com.url

imports:
  pages:
    google_com: "../page/google.com.yml"

"verify Google is open":
  assertions:
    - $page.title is "Google"

"query 'example'":
  actions:
    - set $google_com.elements.search_input to "example"
    - click $google_com.elements.search_button

  assertions:
    - $page.title is "example - Google Search"

Imported Page Model Elements Passed To Imported Step

# examples/page/google.com.yml
url: "https://www.google.com"
elements:
  search_input: $".gLFyf.gsfi"
  search_button: $".FPdoLc.VlcLAe input[name=btnK]"

# examples/step/google-query-parameterised.yml
actions:
  - set $elements.search_input to $data.query_term
  - click $elements.search_button

assertions:
  - $page.title is $data.expected_title

# examples/test/google-imported-steps-with-page-model.yml
config:
  browsers:
    - chrome
  url: google_com.url

imports:
  pages:
    google_com: "../page/google.com.yml"
  steps:
    google_query: "../step/google-query-parameterised.yml"

"verify Google is open":
  assertions:
    - $page.title is "Google"

"query 'example'":
  use: google_query
  data:
    0:
      query_term: "foo"
      expected_title: "foo - Google Search"

  elements:
    search_input: $google_com.elements.search_input
    search_button: $google_com.elements.search_button