Forem: Douglas Cardoso

Page Transactions and Page Object Model

Douglas Cardoso — Wed, 05 Feb 2025 02:49:15 +0000

Recently I wrote Page Transactions as a new way to organize your testing automation, focusing on simplicity, readability and flexibility. Now, I present a structured comparison of Page Transactions (PT) and Page Objects Model (POM) explaining the pros and cons of each pattern. At the end I give some tips to migrate from POM to PT in simple steps.

To whom that is not familiar with POM, in a nutshell, it is a design pattern used in testing automation where the objects on a UI page are represented as methods in a class and where each class represents the UI page itself.

The comparison takes into account aspects like maintainability, reusability, readability and simplicity. Lets start with POM which is a popular pattern in test automation.

Page Objects Model

Code maintainability

✅ Separates locators from tests ✅ Easy to update elements

❌ Still tightly coupled with page structure ❌ If UI changes, all affected pages must be updated

Reusability

✅ Page classes can be reused across multiple tests

❌ Interactions are page-specific, not user-flow based

Readability and Simplicity

✅ Test cases look clean with method calls

❌ Requires writing multiple classes for different pages, which can add complexity

Scalability

✅ Works well for large projects with many pages

❌ Harder to manage when dealing with workflows spanning multiple pages

Test maintenance effort

✅ If a locator changes, it only needs to be updated in one place

❌ If the user workflow changes, tests might need significant updates

Suitability for UI testing

✅ Well-suited for UI automation with Selenium and similar tools

❌ Not ideal for non-UI scenarios (e.g., REST API testing)

Page Transactions

Code maintainability

✅ Transactions focus on user actions rather than elements, reducing maintenance

❌ Requires a different mindset for those used to POM

Reusability

✅ Highly reusable since transactions are user-action based

❌ If UI structure changes drastically, transactions might need updates

Readability & Simplicity

✅ Tests read like human instructions, improving clarity ✅ Reduces WebDriver calls in test script

❌ Requires defining multiple transaction classes for different actions

Scalability

✅ Works well for large applications, especially where user flows span multiple pages

❌ Slightly more setup is needed compared to POM

Test maintenance effort

✅ Less maintenance required since tests are written based on actions rather than UI elements

❌ If a transaction is reused across many tests, fixing one issue could impact multiple tests

Suitability for UI testing

✅ Works for UI, API, and asynchronous testing

❌ Less common in traditional UI automation frameworks

Analysis

PT focuses on user workflows, making it more maintainable and scalable. It allows for better test organization and is more suitable for different types of automation (Web UI, API, Desktop UI). Tests written in PT are more readable, making them accessible to non-technical stakeholders. If your project involves complex user workflows across multiple pages, Page Transactions is the better approach.

POM is still a great choice for teams already familiar with traditional UI testing methods, and it provides a structured way to manage page elements. If you need simple UI structure representation, POM works well.

So, no pattern is best or worst. It depends on the characteristics of a given project. However, if the project fits better with PT pattern, but is already implemented in POM, it is possible to migrate from POM to PT following these tips.

Tips for Migrating from POM to PT

Moving from POM to PT requires shifting from page-centric automation to user action-centric automation. Below are key steps and examples to help with the transition.

1 Identify User Transactions: In POM, page objects represent pages. In PT, it focus on transactions like Login, Logout, Submit Form, Change Language, Navigate to a Page. Instead of writing separate methods for every element on a page, create classes for each transaction.

2 Convert POM Methods to PT Transactions: Check bellow a POM Example (Before Migration). The test login to a page, informs the user and password of a user and checks if the Dashboard page is displayed. There is a LoginPage class which hosts the methods to interact with the components of the page, like username field.

from selenium.webdriver.common.by import By

class LoginPage:
    def __init__(self, driver):
        self.driver = driver
        self.username = (By.ID, "username")
        self.password = (By.ID, "password")
        self.login_button = (By.ID, "login")

    def enter_username(self, user):
        self.driver.find_element(*self.username).send_keys(user)

    def enter_password(self, pwd):
        self.driver.find_element(*self.password).send_keys(pwd)

    def click_login(self):
        self.driver.find_element(*self.login_button).click()

def test_login():
    driver = webdriver.Chrome()
    login_page = LoginPage(driver)

    login_page.enter_username("user1")
    login_page.enter_password("password1")
    login_page.click_login()

    assert "Dashboard" in driver.title

PT Example (After Migration). Now, the LoginTransaction class represents the whole login action which adds the user name, password and submit them.

from guara.transaction import AbstractTransaction

class LoginTransaction(AbstractTransaction):
    def __init__(self, driver):
        super().__init__(driver)

    def do(self, username, password):
        self._driver.find_element(By.ID, "username").send_keys(username)
        self._driver.find_element(By.ID, "password").send_keys(password)
        self._driver.find_element(By.ID, "login").click()
        return self._driver.title

from guara.transaction import Application
from guara import it
from selenium import webdriver

def test_login():
    driver = webdriver.Chrome()
    app = Application(driver)

    app.at(LoginTransaction, username="user1", password="password1").asserts(
      it.Contains, "Dashboard"
    )

Benefits of the PT Approach

Less boilerplate code as no needs for page-specific methods in tests
Readable test cases once tests describe actions in plain English
Easier maintenance as UI changes don’t break all related test methods

3 Additional Refactoring for Other Pages: for example changing Language Transaction, instead of:

class HomePage:
    def click_language_button(self):
        self.driver.find_element(By.ID, "language").click()

Use

class ChangeLanguageTransaction(AbstractTransaction):
    def __init__(self, driver):
        super().__init__(driver)

    def do(self, language):
        self._driver.find_element(By.ID, f"lang-{language}").click()
        return self._driver.find_element(By.TAG_NAME, "body").text

Test case:

app.at(ChangeLanguageTransaction, language="pt").asserts(
  it.Contains, "Página inicial"
)

4 Gradual Migration Strategy:

Start with frequently changing tests
Convert one transaction at a time
Keep old POM code until full migration is complete

Conclusion

PT is a new pattern, but demonstrates good qualities when compared against POM that is a widely used pattern in test automation. It in some situations PT fits better and can be used as an alternative to POM.

Page Transactions as a new way to organize your testing automation

Douglas Cardoso — Sat, 25 Jan 2025 01:01:55 +0000

Photo by Mateus Campos Felipe

Scarlet ibis (Guará)
The scarlet ibis, sometimes called red ibis (Eudocimus ruber), is a species of ibis in the bird family Threskiornithidae. It inhabits tropical South America and part of the Caribbean. In form, it resembles most of the other twenty-seven extant species of ibis, but its remarkably brilliant scarlet coloration makes it unmistakable. It is one of the two national birds of Trinidad and Tobago, and its Tupi–Guarani name, guará, is part of the name of several municipalities along the coast of Brazil.

The pattern

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 to Linux, Window 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, RPA 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. Despite 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 feels 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:

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

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 the transactions and assertions in the logs after run 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 setup and tear down to initiate and finish the tests. Remember, it is not a new tool, so you can use pytest or unittesting features without any problem.

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:

Install Guará with the command

pip install guara

Build your transactions using the AbstractTransaction class.
Invoke the transactions using the Application runner and its methods at and asserts.
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 building and sharing new assertions.

Try Guará today!

Python: Refactoring to Patterns

Douglas Cardoso — Wed, 15 Jan 2025 18:39:10 +0000

Photo by Patric Ho

I’ll keep this brief to save your time — here’s the TL;DR:

This table in Python contains a list of code smells and the design patterns that address them.

class CodeSmells:
    Duplicated_Code = [
        form_template_method,
        introduce_polymorphic_creation_with_factory_method,
        chain_constructors,
        replace_one__many_distinctions_with_composite,
        extract_composite,
        unify_interfaces_with_adapter,
        introduce_null_object,
    ]
    Long_Method = [
        compose_method,
        move_accumulation_to_collecting_parameter,
        replace_conditional_dispatcher_with_command,
        move_accumulation_to_visitor,
        replace_conditional_logic_with_strategy,
    ]
    Conditional_Complexity = [  # Complicated conditonal logic
        replace_conditional_logic_with_strategy,
        move_emblishment_to_decorator,
        replace_state_altering_conditionals_with_state,
        introduce_null_object,
    ]
    Primitive_Obssession = [
        replace_type_code_with_class,
        replace_state_altering_conditionals_with_state,
        replace_conditional_logic_with_strategy,
        replace_implict_tree_with_composite,
        replace_implicit_language_with_interpreter,
        move_emblishment_to_decorator,
        encapsulate_composite_with_builder,
    ]
    # Lack of "information hiding" [Parnas]
    Indecent_Exposure = [encapsulate_classes_with_factory]
    # The logic/responsibility is sprawled in multiple places
    # (classes, methods)
    Solution_Sprawl = [move_creation_knowledge_to_factory]
    # [Fowler and Beck] Interfaces of classes different,
    # but classes are similar
    Alternative_Classes_with_Different_Interfaces = unify_interfaces_with_adapter
    # [Fowler and Beck] A class the doesn't do enough to pay itself
    Lazy_Class = [inline_singleton]
    Large_Class = [
        replace_conditional_dispatcher_with_command,
        replace_state_altering_conditionals_with_state,
        replace_implict_tree_with_composite,
    ]
    Switch_Statements = [  # Complicated switches
        replace_conditional_dispatcher_with_command,
        move_accumulation_to_visitor,
    ]
    # Code that do the same with different types or quantity of data
    # (similar to duplication)
    Combination_Explostion = [replace_implicit_language_with_interpreter]
    # The same problem being solved in many ways in the system
    # (similar to duplication)
    Oddball_Solutions = [unify_interfaces_with_adapter]

Refactorings

After nearly a year of effort, I’ve finally completed my self-imposed goal of writing all the refactoring examples from the book Refactoring to Patterns by Joshua Kerievsky in Python. This book broadened my understanding of how to apply design patterns in production code.

Each example includes a brief explanation of the original code and its context, followed by the refactored code and the benefits gained through the refactoring. For instance, the refactoring to “Compose Method” transforms difficult-to-read code into a simple, streamlined implementation.

Lets get this example and examine the original code.

# Original code
# It is not easy to understand the code
def add(element):
    readonly = False
    size = 0
    elements = []
    if not readonly:
        new_size = size + 1
        if new_size > len(elements):
            new_elements = []
            for i in range(size):
                new_elements[i] = elements[i]
            elements = new_elements
        size += 1
        elements[size] = element

It is possible to see that the code is not easy to understand. It has many nested conditions and loops. Now lets go to the refactored code.

# Code Refactored
# The new code has meaningfull names for blocks of code and is not nested.
# The Compose Method is a refactoring to simplificate the code
def at_capacity(new_size, elements):
    new_size > len(elements)


def grow(size):
    new_elements = []
    for i in range(size):
        new_elements[i] = elements[i]
    elements = new_elements


def add_elements(elements, element, size):
    size += 1
    elements[size] = element


def add_refac(element):
    readonly = False
    if readonly:
        return
    if at_capacity:
        grow()
    add_elements(element)

The idea of the refactoring is reduce the complication with meaningful methods and remove the nested branches. Notice it was necessary to extract blocks of code to methods.

While working through the book and writing the examples, I had to interpret UML diagrams and understand the mechanics in detail. This required intense focus and mental effort. Many times, I had to rebuild the examples from scratch because converting code from Java to Python is not straightforward. Native Python doesn’t support cyclic imports, constructor overloads, or interfaces well, so some adaptations were necessary. I added comments to these areas to help future consultation of the code.

Through this process, I realized my previous understanding of design patterns was mostly theoretical and limited to trivial scenarios. For example, while I understood that “Polymorphism” addresses development problems, the book showed its application in test automation by abstracting the setup phase and reusing the remaining test implementation.

Here are both versions of the code. The difference between the original and new code is the setup of the test.

# Original code
# Similar methods differs from the object instantiation.
# All the rest is the same
class TestCase:
    pass


class DOMBuilder:
    def __init__(self, orders) -> None:
        pass

    def calc(self):
        return 42


class XMLBuilder:
    def __init__(self, orders) -> None:
        pass

    def calc(self):
        return 42


class DOMTest(TestCase):
    def run_dom_test(self):
        expected = 42
        builder = DOMBuilder("orders")  # different object created
        assert builder.calc() == expected


class XMLTest(TestCase):
    def run_xml_test(self):
        expected = 42
        builder = XMLBuilder("orders")  # different object created
        assert builder.calc() == expected


# Code refactored
# The instantiation of the DOMBuilder or XMLBuilder is the only difference
# in both tests.
# It was created an OutputBuilder like an interface for both classes
# (it is not necessary given that Python uses duck type).
# In TestCase a new method called "create_builder" was introduced to be
# implemented by the children classes.
# This is the step executed in runtime for each type of test. This is the
# polymorphism. When both tests (DOMTest and XMLTest) are executed,
# the instance returned from the "create_builder" depends on the
# implementation. Is can be DOMBuilder or XMLBuilder.
class OutputBuilder:
    def calc(self):
        raise NotImplementedError()


class DOMBuilderRefac(OutputBuilder):
    def calc(self):
        return 42


class XMLBuilderRefac(OutputBuilder):
    def calc(self):
        return 42


class TestCaseRefac:
    def create_builder(self):
        raise NotImplementedError()

    def run_test(self):
        expected = 42
        builder = self.create_builder()  # different object created
        assert builder.calc() == expected


class DOMTestRefac(TestCaseRefac):
    def create_builder(self) -> OutputBuilder:
        return DOMBuilderRefac()


class XMLTestRefac(TestCaseRefac):
    def create_builder(self):
        return XMLBuilderRefac()


def run():
    dom_tc = DOMTestRefac()
    dom_tc.run_test()

    xml_tc = XMLTestRefac()
    xml_tc.run_test()

The “Visitor” pattern was the most difficult for me to understand. I read about the pattern in the Design Patterns book before attempting the refactoring. It was only after seeing the original (unrefactored) code being transformed into the new version that I realized the pattern isn’t as complex as it initially seems. Essentially, the pattern decouples classes from their methods. Again, both codes for comparison. The implementation of the pattern is “by the book”.

# Original code
# The TextExtractor has lots of conditons to handle Nodes, like StringNode
# The idea ofthe rectoring is distribute the logic into Visitor classes


# Interface
class Node:
    pass


class LinkTag(Node):
    pass


class Tag(Node):
    pass


class StringNode(Node):
    pass


class TextExtractor:
    def extract_text(self, nodes: list[Node]):
        result = []
        for node in nodes:
            if isinstance(node, StringNode):
                result.append("string")
            elif isinstance(node, LinkTag):
                result.append("linktag")
            elif isinstance(node, Tag):
                result.append("tag")
            else:
                result.append("other")
        return result


# Code refactored
# Interface (the visitor)
class NodeVisitorRefac:
    def visit_link_tag(self, node):
        return "linktag"

    def visit_tag(self, node):
        return "tag"

    def visit_string_node(self, node: object):
        return "string"


class NodeRefac:
    def accept(self, node: NodeVisitorRefac):
        pass


class LinkTagRefac(NodeRefac):
    def accept(self, node: NodeVisitorRefac):
        return node.visit_link_tag(self)


class TagRefac(NodeRefac):
    def accept(self, node: NodeVisitorRefac):
        return node.visit_tag(self)


class StringNodeRefac(NodeRefac):
    def accept(self, node: NodeVisitorRefac):
        return node.visit_string_node(self)


# The concret visitor
class TextExtractorVisitorRefac(NodeVisitorRefac):
    def extract_text(self, nodes: list[NodeRefac]):
        result = []
        for node in nodes:
            result.append(node.accept(self))
        return result


def run_refac():
    # The original object calling its method
    result1 = TextExtractor().extract_text([StringNode()])
    # The new object accepting visitors
    result2 = TextExtractorVisitorRefac().extract_text([StringNodeRefac()])
    return result1, result2

Conclusion

I highly recommend the book to everyone. The first time I read it, I found it boring and difficult to grasp the concepts just by following static code examples. However, when you actively write the code, the ideas gradually come to life. Errors will occur, and addressing them requires understanding the underlying concepts. This process transforms theory into practice and solidifies your knowledge.