Quick Start

Vedro is a powerful tool for creating scenario-based tests that simulate user interactions and validate outcomes. This guide will help you get started with Vedro by demonstrating how to create a test that decodes a base64 encoded string using the httpbin.org API.

Installation

To install vedro and the httpx library, which we will use to make HTTP requests in our test, simply run the following command in your terminal:

$ pip install vedro httpx

Your First Test

Vedro framework uses scenario tests to simulate user interactions and validate outcomes (or side effects). Each scenario begins with a subject representing the user's intention and includes a series of steps:

1. Arrange steps - Prepare data for the primary action
2. Primary action (Act) - User interaction with the application, system, or component
3. Assert steps - Verify application responses or side effects against expected outcomes

Create a new file named decode_base64_encoded_string.py in the scenarios/ directory and add the following code:

Scenario-based

import httpx
import vedro

class Scenario(vedro.Scenario):
    subject = "decode base64 encoded string"

    def given_encoded_string(self):
        self.encoded = "YmFuYW5h"

    def when_user_decodes_string(self):
        self.response = httpx.get(f"https://httpbin.org/base64/{self.encoded}")

    def then_it_should_return_decoded_string(self):
        assert self.response.text == "banana"

Function-based

To use the function-based approach, install the vedro-fn plugin. For more details, refer to this article.

import httpx
# Install via: vedro plugin install vedro-fn
from vedro_fn import scenario, given, when, then

@scenario()
def decode_base64_encoded_str():
    with given:
        encoded = "YmFuYW5h"

    with when:
        response = httpx.get(f"https://httpbin.org/base64/{encoded}")

    with then:
        assert response.text == "banana"

In this test, we use the httpbin.org API to decode a base64 encoded string. We define a Scenario class with a subject representing the user's intention to decode the string and three methods:

1. given — Sets up the initial conditions for the test (in this case, the encoded string)
2. when — Performs the primary action (sending an HTTP GET request to the API)
3. then — Verifies the outcome (checking if the decoded string is "banana")

Running the Test

To run the test, execute the following command in your terminal:

$ vedro run

The command will run all the test scenarios in scenarios/ directory and display the results, indicating which tests have passed, failed, or been skipped.

Scenarios
* 
 ✔ decode base64 encoded string
 
# --seed 9d903d07-5e97-4a74-a60a-33a527bcc6d9
# 1 scenario, 1 passed, 0 failed, 0 skipped (0.73s)

Here is an example of a failed scenario:

Scenarios
* 
 ✗ decode base64 encoded str
   ✗ do
╭──────────────────── Traceback (most recent call last) ────────────────────╮
│ /e2e/scenarios/decode_base64.py:14 in decode_base64_encoded_str           │
│                                                                           │
│   12                                                                      │
│   13     with then:                                                       │
│ ❱ 14         assert response.text == "banana"                             │
│   15                                                                      │
╰───────────────────────────────────────────────────────────────────────────╯
AssertionError
>>> assert actual == expected
    - 'banana'                                                                                                                   
    + ''                                                                                                                         
 
 
# --seed ab0017dd-63ba-45c8-b9fb-b7d7bd694d4b
# 1 scenario, 0 passed, 1 failed, 0 skipped (0.68s)

Next Steps

Now that you have successfully set up Vedro and written your first test, you can continue to explore the framework and create more complex test scenarios for your application.