Page Transactions: A New Approach to Test Automation

Guará is the Python implementation of the design pattern Page Transactions. It is more of a programming pattern than a tool. As a pattern, it can be bound to any driver other than Selenium, including the ones used for Linux, Windows, and Mobile automation.

The intent of this pattern is to simplify test automation. It was inspired by Page Objects, App Actions, and Screenplay. Page Transactions focus on the operations (transactions) a user can perform on an application, such as Login, Logout, or Submit Forms.

This initiative was born to improve the readability, maintainability, and flexibility of automation testing code without the need for new automation tools or the necessity of many abstractions to build human-readable statements. Another concern was to avoid binding the framework to specific automation tools, like Selenium, leaving the testers free to choose their preferred ones. No new plugin nor new knowledge is required to start using Guará with Helium, Dogtail, PRA Python, Playwright or whatever tool you like or need.

It is worth to say again:

Guará is the Python implementation of the design pattern Page Transactions. It is more of a programming pattern than a tool.

Guará leverages the Command Pattern (GoF) to group user interactions, like pressing buttons or filling texts, into transactions. Although I’m calling it a framework, it is not a new tool.

Instead of focusing on UI elements like buttons, check boxes, or text areas, it emphasizes the user journey. The complexity is abstracted into these transactions, making the test statements feel like plain English. Testers also have the flexibility to extend assertions to custom ones that are not provided by the framework.

The Framework in Action

This simple implementation mimics the user switching languages in a web page:

import home
from selenium import webdriver
from guara.transaction import Application
from guara import it, setup

def test_language_switch():
    app = Application(webdriver.Chrome())
    
    # Open the application
    app.at(setup.OpenApp, url="https://example.com/")
    
    # Change language and assert
    app.at(home.ChangeToPortuguese).asserts(it.IsEqualTo, "Conteúdo em Português")
    app.at(home.ChangeToEnglish).asserts(it.IsEqualTo, "Content in English")
    
    # Close the application
    app.at(setup.CloseApp)

Each user transaction is grouped into its own class (e.g., ChangeToPortuguese) which inherits from AbstractTransaction. The tester just has to override the do method, and the framework does the work.

from guara.transaction import AbstractTransaction

class ChangeToPortuguese(AbstractTransaction):
    def do(self, **kwargs):
        self._driver.find_element(By.CSS_SELECTOR, ".btn-pt").click()
        return self._driver.find_element(By.CSS_SELECTOR, ".content").text

The tester can check the transactions and assertions in the logs after running the tests:

test_demo.py::test_language_switch 
2025-01-24 21:07:10 INFO Transaction: setup.OpenApp
2025-01-24 21:07:10 INFO  url: https://example.com/
2025-01-24 21:07:14 INFO Transaction: home.ChangeToPortuguese
2025-01-24 21:07:14 INFO Assertion: IsEqualTo
2025-01-24 21:07:14 INFO  Actual Data: Conteúdo em Português
2025-01-24 21:07:14 INFO  Expected: Conteúdo em Português
2025-01-24 21:07:14 INFO Transaction: home.ChangeToEnglish
2025-01-24 21:07:14 INFO Assertion: IsEqualTo
2025-01-24 21:07:14 INFO  Actual Data: Content in English
2025-01-24 21:07:14 INFO  Expected: Content in English
2025-01-24 21:07:14 INFO Transaction: setup.CloseApp

The tester can also use fixtures like set up and tear down to initiate and finish the tests. Remember, it is not a new tool, so you can use pytest or unit testing features without any problem.

The Pattern Explained

AbstractTransaction: This is the class from which all transactions inherit. The do method is implemented by each transaction. In this method, calls to WebDriver are placed. If the method returns something, like a string, the automation can use it for assertions.

• setup.OpenApp and setup.CloseApp are part of the framework and provide basic implementation to open and close the web application using Selenium Webdriver.

IAssertion: This is the interface implemented by all assertion classes.

• The asserts method of each subclass contains the logic to perform validations. For example, the IsEqualTo subclass compares the result with the expected value provided by the tester.
• Testers can inherit from this interface to add new sub-classes of validations that the framework does not natively support
• it is the module that contains the concrete assertions.

Application: This is the runner of the automation. It executes the do method of each transaction and validates the result using the asserts method.

• The asserts method receives a reference to an IAssertion instance. It implements the Strategy Pattern (GoF) to allow its behavior to change at runtime.
• Another important component of the application is the result property. It holds the result of the transaction, which can be used by asserts or inspected by the test using the native built-in assert method.

Why Use Guará?

Each class represents a complete user transaction, improving code re-usability. Also, the code is written in plain English, making it easier for non-technical collaborators to review and contribute.

Custom assertions can be created and shared by testers. Additionally, Guará can be integrated with any non-Selenium tool.

Page Transactions can automate REST APIs, unit tests, desktop, and mobile tests. As a side effect of the Command Pattern, the framework can even be used in product development.

Using Guará

Setting up Guará is simple:

1. Install Guará with the command:

pip install guara

2. Build your transactions using the AbstractTransaction class.

3. Invoke the transactions using the application runner and its methods at and asserts.

3. Execute tests with detailed logging with Pytest:

python -m pytest -o log_cli=1 --log-cli-level=INFO

For more examples, check out the tutorial.

Conclusion

Guará is a new way testers can organize their code, making it simple to read, maintain, and integrate with any automation driver. It improves the collaboration between testers and non-technical members. Testers can also extend it by building and sharing new assertions.

Try Guará today!