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:

sync

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"

async

import httpx
import vedro

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

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

    async def when_user_decodes_string(self):
        async with httpx.AsyncClient() as client:
            self.response = await client.get(f"https://httpbin.org/base64/{self.encoded}")

    def then_it_should_return_decoded_string(self):
        assert self.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_encoded_string — Sets up the initial conditions for the test (in this case, the encoded string)
2. when_user_decodes_string — Performs the primary action (sending an HTTP GET request to the API)
3. then_it_should_return_decoded_string — 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 -v

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)

The -v flag increases the verbosity of the test output. In case a scenario fails, this flag provides more detailed information about the test run to help you identify and troubleshoot the issue.

Scenarios
* 
 ✗ decode base64 encoded string
   ✔ given_encoded_string
   ✔ when_user_decodes_string
   ✗ then_it_should_return_decoded_string
╭─────────────────────────────── Traceback (most recent call last) ─────────────────────────╮
│ /e2e/scenarios/decode_base64_encoded_string.py:15 in then_it_should_return_decoded_string │
│   13 │                                                                                    │
│   14 │   def then_it_should_return_decoded_string(self):                                  │
│ ❱ 15 │   │   assert self.response.text == "banana"                                        │
│   16                                                                                      │
╰───────────────────────────────────────────────────────────────────────────────────────────╯
AssertionError: assert 'banana' == ''
 +  where 'banana' = <Response [503 SERVICE UNAVAILABLE]>.text
 
# --seed 80485375-d67c-44d3-88b5-51335c5adcb7
# 3 scenarios, 0 passed, 1 failed, 0 skipped (1.52s)

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.