pytest-play 2.0.2

pytest-play

pytest-play is a codeless, generic, pluggable and extensible automation tool, not necessarily test automation only, based on the fantastic pytest test framework that let you define and execute YAML files containing scripts or test scenarios through actions and assertions that can be implemented and managed even by non technical users:

• automation (not necessarily test automation). You can build a set of actions on a single file (e.g, call a JSON based API endpoint, perform an action if a condition matches) or a test automation project with many test scenarios.

  For example you can create always fresh test data on demand supporting manual testing activities, build a live simulator and so on

• codeless, or better almost codeless. If you have to write assertions against action results or some conditional expressions you need a very basic knowledge of Python or Javascript expressions with a smooth learning curve (something like variables['foo'] == 'bar')

• generic. It is not yet again another automation tool for browser automation only, API only, etc. You can drive a browser, perform some API calls, make database queries and/or make assertions using the same tool for different technologies

  So there are several free or not free testing frameworks or automation tools and many times they address just one single area testing needs and they are not extensible: API testing only, UI testing only and so on. It could be fine if you are testing a web only application like a CMS but if you are dealing with a reactive IoT application you might something more, make cross actions or cross checks against different systems or build something of more complex upon pytest-play

• powerful. It is not yet again another test automation tool, it only extends the pytest framework with another paradigm and inherits a lot of good stuff (test data decoupled by test implementation that let you write once and executed many times the same scenario thanks to native parametrization support, reporting, integration with test management tools, many useful command line options, browsers and remote Selenium grids integration, etc)

• pluggable and extensible. Let’s say you need to interact with a system not yet supported by a pytest-play plugin, you can write by your own or pay someone for you. In addition there is a scaffolding tool that let you implement your own command: https://github.com/davidemoro/cookiecutter-play-plugin

• easy to use. Why YAML? Easy to read, easy to write, simple and standard syntax, easy to be validated and no parentheses hell. Despite there are no recording tools (not yet) for browser interaction or API calls, the documentation based on very common patterns let you copy, paste and edit command by command with no pain

• free software. It’s an open source project based on the large and friendly pytest community

• easy to install. The only prerequisite is Docker thanks to the davidemoro/pytest-play Docker Hub container. Or better, with docker, no installation is required: you just need to type the following command docker run -i --rm -v $(pwd):/src davidemoro/pytest-play inside your project folder See https://hub.docker.com/r/davidemoro/pytest-play

See at the bottom of the page the third party plugins that extends pytest-play:

• Third party pytest-play plugins

Python-less (pure YAML)

Here you can see the contents of a pytest-play project without any Python files inside containing a login scenario:

$ tree
.
├── env-ALPHA.yml    (OPTIONAL)
└── test_login.yml

and you might have some global variables in a settings file specific for a target environment:

$ cat env-ALPHA.yml
pytest-play:
  base_url: https://www.yoursite.com

The test scenario with action, assertions and optional metadata (play_selenium external plugin needed):

$ cat test_login.yml
---
markers:
  - login
test_data:
  - username: siteadmin
    password: siteadmin
  - username: editor
    password: editor
  - username: reader
    password: reader
---
- comment: visit base url
  type: get
  provider: selenium
  url: "$base_url"
- comment: click on login link
  locator:
    type: id
    value: personaltools-login
  type: clickElement
  provider: selenium
- comment: provide a username
  locator:
    type: id
    value: __ac_name
  text: "$username"
  type: setElementText
  provider: selenium
- comment: provide a password
  locator:
    type: id
    value: __ac_password
  text: "$password"
  type: setElementText
  provider: selenium
- comment: click on login submit button
  locator:
    type: css
    value: ".pattern-modal-buttons > input[name=submit]"
  type: clickElement
  provider: selenium
- comment: wait for page loaded
  locator:
    type: css
    value: ".icon-user"
  type: waitForElementVisible
  provider: selenium

The first optional YAML document contains some metadata with keywords aka markers so you can filter tests to be executed invoking pytest with marker expressions, decoupled test data, etc.

The same test_login.yml scenario will be executed 3 times with different decoupled test data test_data defined inside its first optional YAML document (the block between the 2 --- lines).

So write once and execute many times with different test data!

You can see a hello world example here:

• https://github.com/davidemoro/pytest-play-plone-example

As told before the metadata document is optional so you might have 1 or 2 documents in your YAML file. You can find more info about Metadata format.

Here you can see the same example without the metadata section for sake of completeness:

---
- comment: visit base url
  type: get
  provider: selenium
  url: "http://YOURSITE"
- comment: click on login link
  type: clickElement
  provider: selenium
  locator:
    type: id
    value: personaltools-login
- comment: provide a username
  type: setElementText
  provider: selenium
  locator:
    type: id
    value: __ac_name
  text: "YOURUSERNAME"
- comment: provide a password
  type: setElementText
  provider: selenium
  locator:
    type: id
    value: __ac_password
  text: "YOURPASSWORD"
- comment: click on login submit button
  type: clickElement
  provider: selenium
  locator:
    type: css
    value: ".pattern-modal-buttons > input[name=submit]"
- comment: wait for page loaded
  type: waitForElementVisible
  provider: selenium
  locator:
    type: css
    value: ".icon-user"

Programmatically

You can invoke pytest-play programmatically too.

You can define a test test_login.py like this:

def test_login(play):
    data = play.get_file_contents(
        'my', 'path', 'etc', 'login.yml')
    play.execute_raw(data, extra_variables={})

Or this programmatical approach might be used if you are implementing BDD based tests using pytest-bdd.

How to reuse steps

You can split your commands and reuse them using the include command avoiding duplication:

- provider: include
  type: include
  path: "/some-path/included-scenario.yml"

You can create a variable for the base folder where your test scripts live.

Default commands

Some commands require many verbose options you don’t want to repeat (eg: authentication headers for play_requests).

Instead of replicating all the headers information you can initialize a pytest-play with the provider name as key and as a value the default command you want to omit (this example neets the external plugin play_selenium):

- provider: python
  type: store_variable
  name: bearer
  expression: "'BEARER'"
- provider: python
  type: store_variable
  name: play_requests
  expression: "{'parameters': {'headers': {'Authorization': '$bearer'}}}"
- provider: play_requests
  type: GET
  comment: this is an authenticated request!
  url: "$base_url"

Store variables

You can store a pytest-play variables:

- provider: python
  type: store_variable
  expression: "1+1"
  name: foo

Make a Python assertion

You can make an assertion based on a Python expression:

- provider: python
  type: assert
  expression: variables['foo'] == 2

Sleep

Sleep for a given amount of seconds:

- provider: python
  type: sleep
  seconds: 2

Exec a Python expresssion

You can execute a Python expression:

- provider: python
  type: exec
  expression: "1+1"

Wait until condition

The wait_until_not command waits until the wait expression is False (this example contains a SQL query so the external plugin called play_sql is needed plus the appropriate SQL driver depending on database type):

- provider: python
  type: wait_until_not
  expression: variables['expected_id'] is not None and variables['expected_id'][0] == $id
  timeout: 5
  poll: 0.1
  subcommands:
  - provider: play_sql
    type: sql
    database_url: postgresql://$db_user:$db_pwd@$db_host/$db_name
    query: SELECT id FROM table WHERE id=$id ORDER BY id DESC;
    variable: expected_id
    expression: results.first()

assuming that the subcommand updates the execution results updating a pytest-play variable (eg: expected_id) where tipically the $id value comes from a previously executed command that causes an asynchrounous update on a relational database soon or later (eg: a play_requests command making a HTTP POST call or a MQTT message coming from a simulated IoT device with play_mqtt).

The wait command will try (and retry) to execute the subcommand with a poll frequency poll (default: 0.1 seconds) until the provided timeout expressed in seconds expires or an exception occurs.

You can use the opposite command named wait_until that waits until the wait expression is not False.

Loop commands

You can repeat a group of subcommands using a variable as a counter. Assuming you have defined a countdown variable with 10 value, the wait until command will repeat the group of commands for 10 times:

play.execute_command({
    'provider': 'python',
    'type': 'wait_until',
    'expression': 'variables["countdown"] == 0',
    'timeout': 0,
    'poll': 0,
    'sub_commands': [{
        'provider': 'python',
        'type': 'store_variable',
        'name': 'countdown',
        'expression': 'variables["countdown"] - 1'
    }]
})

or:

- provider: python
  type: wait_until
  expression: variables['countdown'] == 0
  timeout: 0
  poll: 0
  sub_commands:
  - provider: python
    type: store_variable
    name: countdown
    expression: variables['countdown'] - 1

Conditional commands (Python)

You can skip any command evaluating a Python based skip condition like the following:

- provider: include
  type: include
  path: "/some-path/assertions.yml"
  skip_condition: variables['cassandra_assertions'] is True

How to register a new command provider

Let’s suppose you want to extend pytest-play with the following command:

command = {'type': 'print', 'provider': 'newprovider', 'message': 'Hello, World!'}

You just have to implement a command provider:

from pytest_play.providers import BaseProvider

class NewProvider(BaseProvider):

    def this_is_not_a_command(self):
        """ Commands should be command_ prefixed """

    def command_print(self, command):
        print(command['message'])

    def command_yetAnotherCommand(self, command):
        print(command)

and register your new provider in your setup.py adding an entrypoint:

entry_points={
    'playcommands': [
        'print = your_package.providers:NewProvider',
    ],
},

You can define new providers also for non UI commands. For example publish MQTT messages simulating IoT device activities for integration tests.

If you want you can generate a new command provider thanks to:

• https://github.com/davidemoro/cookiecutter-play-plugin

---
markers:
  - marker1
  - marker2
test_data:
  - username: foo
  - username: bar
---
# omitted scenario steps in this example...

Changelog