Best Practices

Git Repository

We’re using two branches for development, main and develop.

• main is the branch that production scenarios are deployed from. This branch is protected and can be merged to it only through a merge request.

• develop is the branch used for running scenarios in test environment, or during their development.

Before deploying scenarios into production we advice asking your colleagues to review your code. This can be done by creating a merge request from develop to main branch.

We setup a GitLab CI pipeline that runs with every commit. It runs basic checks, such as syntax formatting, linting, etc. We use tools as black, pycln, isort, flake8, pylint and pre-commit to ensure that our code is formatted correctly and follows our best practices.

You can run these checks also locally by running:

$ pre-commit run --all-files

Aiviro Commands

Get, See, Wait-For

The distinction between the get(), see() and wait_for() commands lies in their behavior when searching for elements.

• Get returns the desired element or None if it’s not found, making it suitable when you need to make a decision.

• On the other hand, See returns the desired element or raises a CheckCommandError if it’s not found, making it ideal for scenarios where obtaining the element is critical, ensuring a 100% success rate.

• Wait-For waits for the element to appear for a given amount of time before raising a SearchObjectError.

# using get command
if r.get(aiviro.Text("Save ?"), ignore_exception=True):
    r.click(aiviro.Button("Yes"))

# using see command
r.see(aiviro.Button("Submit"))

# using wait-for command
if r.wait_for(
    aiviro.Text("Select year period"),
    timeout=15,
    ignore_timeout_exception=True,  # ignores raising SearchObjectError
):
    current_year = datetime.now().strftime("%Y")
    r.click(aiviro.Text(current_year))

Working area & Masks

The distinction between using a working area and applying masks is essential.

A working area defines a designated region for the user’s interactions, ensuring that subsequent commands operate within this specified area. This limitation enhances the precision and clarity of element identification, reducing potential confusion with similarly named elements.

On the other hand, masks involve overlaying a screen with a cover, selectively blocking out specific sections. Masks are particularly valuable when there’s a need to disregard certain screen portions, allowing the user to focus solely on the relevant elements, and effectively excluding distractions.

Check out the set_working_area() and add_mask() methods for more information.

Static Robot

When something is not recognized correctly in a production scenario, it can be challenging to rectify. In such cases, we can utilize the StaticRobot to verify the correct recognition of specific elements within an image.

See the example below, where we will use an image from the logs to identify the desired object.

import aiviro
from aiviro.core.utils import file_utils

if __name__ == '__main__':
    aiviro.init_logging()
    img = file_utils.load_image("2022-02-11_15-22-44-51_aivirocore.services.FindService_INFO.png")

    r = aiviro.create_static_robot()
    r.set_image(img)
    boxes = r.get(aiviro.Text("Object to find"))
    print(boxes)

Production vs Testing

When defining flows, we set the environment variable AIVIRO_DEBUG_KEY, which determines whether the scenario is executed in a testing or production environment.

• AIVIRO_DEBUG_VALUE == 1 - signifies the testing environment.

• AIVIRO_DEBUG_VALUE == 0 - designates the production environment.

See the example below, where we define different values for the same variables, depending on the environment.

from aiviro import AIVIRO_DEBUG_VALUE

INVOICE_FOLDER = "C:\\Documents" if AIVIRO_DEBUG_VALUE else "Z:\\Prijate faktury"
DB_CATEGORY = "Cvicne DB" if AIVIRO_DEBUG_VALUE else "Produkcni DB"
DB_NAME = "Skoleni" if AIVIRO_DEBUG_VALUE else "Ostra"

Clean code

Re-using elements

There is a big difference between passing Search Objects as parameters and passing Area or BoundBox as parameters.

• Search Objects defines a way to search for an element, but it doesn’t contain any information about the element itself.

• Bound Boxes are the result of a search, and they contain information as element’s coordinates, text, etc.

import aiviro

# simple element
box = r.get(aiviro.Button("OK"))
if box:
    r.click(box)

# element with parameters
element = aiviro.OnTheRight(
    aiviro.Text("Projects", aiviro.text_find_methods.EQUAL),
    aiviro.Text("Dashboards", aiviro.text_find_methods.EQUAL),
)
box = r.wait_for(element)
r.click(box)
# OR
r.click(r.wait_for(element))

# several elements
elements = [
    aiviro.Input("App Title"),
    aiviro.Input("Username"),
    aiviro.Input("Password"),
]
r.wait_for(*elements, timeout=15)

Using OR

When using OR, the first element that is found is returned, see Or for more information.

import aiviro

# NOT preferred way to do it
try:
    pass_input = r.wait_for(aiviro.Input("Heslo"))
except aiviro.SearchObjectError:
    pass_input = r.wait_for(aiviro.Input("Heslc"))

# preferred way to do it, using OR
password_input = r.wait_for(
    aiviro.Or(
        aiviro.Input("Heslo"),
        aiviro.Input("Heslc")
    )
)

# you can access or_index variable to see which element was found
print(password_input.or_index)
1  # 'Heslc' was found

Split the code

Split the code into logical sections or methods. It’s more readable and easier to maintain.

import aiviro

# NOT preferred way to do it
r.add_working_area_checkpoint("desktop")
r.right_click(aiviro.Icon("Helios", element_index=-1))
run_as_admin = r.wait_for(aiviro.Text("Run as administrator"))
r.click(run_as_admin)
r.wait_for(aiviro.Text("User Account Control"))
r.clear_and_type(aiviro.Input("User name"), "user-name")
r.clear_and_type(aiviro.Input("Password"), "password")
r.click(aiviro.Button("Yes"))
with r.set_working_area_by_checkpoint("desktop"):
    pass

# preferred way to do it
checkpoint_name = "desktop"
r.add_working_area_checkpoint(checkpoint_name)

r.right_click(aiviro.Icon("Helios", element_index=-1))
run_as_admin = r.wait_for(aiviro.Text("Run as administrator"))
r.click(run_as_admin)
r.wait_for(aiviro.Text("User Account Control"))

r.clear_and_type(aiviro.Input("User name"), "user-name")
r.clear_and_type(aiviro.Input("Password"), "password")
r.click(aiviro.Button("Yes"))

with r.set_working_area_by_checkpoint(checkpoint_name):
    pass

Python

• Python Best Practices - https://gist.github.com/sloria/7001839

• Python Anti-Patterns - https://docs.quantifiedcode.com/python-anti-patterns/index.html

• Typing & Type hints - https://docs.python.org/3.11/library/typing.html

Hard-coded values

The practice of hard-coding values into a script, especially when the same value is used in multiple places, is not a recommended approach. This is because when the value needs to be changed, it must be updated at all occurrences, which is prone to oversight.

A better practice is to define the value as a constant at the beginning of the script or block and then use this constant throughout.

# discouraged approach
for i in range(10):
    print(f"Processing [{i}/10]")

# recommended approach
N_TIMES = 10
for i in range(N_TIMES):
    print(f"Processing [{i}/{N_TIMES}]")

Constants

Our goal is to define constants that have a common association. For instance, let’s consider a folder structure in an email directory with a top-level folder named Invoices which further contains two subfolders, processed and manual.

# discouraged approach
INVOICES = "INBOX.Invoices"
INVOICES_MANUAL = "INBOX.Invoices.manual"
INVOICES_PROCESSED = "INBOX.Invoices.processed"

# recommended approach
class EmailFolders:
    POSTFIX_MANUAL = "manual"
    POSTFIX_PROCESSED = "processed"

    INVOICES = "INBOX.Invoices"
    INVOICES_MANUAL = f"{INVOICES}.{POSTFIX_MANUAL}"
    INVOICES_PROCESSED = f"{INVOICES}.{POSTFIX_PROCESSED}"

    TESTING = "INBOX.Testing"
    TESTING_MANUAL = f"{TESTING}.{POSTFIX_MANUAL}"
    TESTING_PROCESSED = f"{TESTING}.{POSTFIX_PROCESSED}"

Exception handling

When handling exceptions, it’s important to be as specific as possible. This is because if a general exception is used, it can be difficult to determine the cause of the error.

# discouraged approach
try:
    r.click(aiviro.Button("OK"))
except Exception:
    print("Something went wrong")

# recommended approach
try:
    r.click(aiviro.Button("OK"))
except aiviro.SearchObjectError:
    print("Button OK not found")

try:
    # raise different exceptions
except aiviro.SearchObjectError:
    # handle SearchObjectError
except (ValueError, KeyError):
    # handle ValueError and KeyError
except RuntimeError:
    # handle RuntimeError

If-else statement

It is advisable to avoid using the else keyword when not necessary, as it can make the code cleaner and more concise.

# discouraged approach
if condition:
    return result
else:
    return None

# recommended approach
if condition:
    return result
return None

Code Indentation

It’s recommended to aim for reduced indentation levels to enhance code readability.

# discouraged approach
if condition:
   calc = get_value()
   if calc > 42:
       calc2 = get_value2()
       if calc2 == 100:
           return "success"
       else:
           return "calc2 failed"
   else:
       return "calc1 failed:"
return None

# recommended approach
if not condition:
    return None

calc = get_value()
if calc <= 42:
    return "calc1 failed"

calc2 = get_value2()
if calc2 != 100:
    return "calc2 failed"

return "success"

Floating point

When working with floating-point numbers, it’s recommended to use the decimal module to avoid rounding errors.

from decimal import Decimal

a = Decimal(1)  # integer
b = Decimal(1.2)  # float
c = Decimal((0, (1, 2), -1))  # piecewise float = sign, digits, exponent ->   +  12 * 10^-1
d = Decimal("1")  # integer as a string
e = Decimal("1.2")  # float as a string

When working with decimal numbers, it’s recommended to always create a Decimal object from a string because it preserves the value as intended. When you specify a Decimal from an integer or a float, the entire binary representation of the number is copied.

from decimal import Decimal

>>> Decimal(1.1)  # float
Decimal('1.100000000000000088817841970012523233890533447265625')
>>> Decimal("1.1")  # string
Decimal('1.1')

>>> Decimal(0.1 + 0.2)
Decimal('0.3000000000000000444089209850062616169452667236328125')
>>> Decimal(0.1) + Decimal(0.2)
Decimal('0.3000000000000000166533453694')
>>> Decimal("0.1") + Decimal("0.2")
Decimal('0.3')

In the example below, we can see how to round number to two decimal places using standard rounding, rounding down (floor) and rounding up (ceiling).

from decimal import Decimal, ROUND_UP, ROUND_DOWN

# Standard rounding (nearest number rounding)
>>> Decimal("1.455").quantize(Decimal("0.01"))
Decimal('1.46')
>>> Decimal("1.454").quantize(Decimal("1e-2"))
Decimal('1.45')

# Round down (floor)
>>> Decimal("1.455").quantize(Decimal("0.01"), ROUND_DOWN)
Decimal('1.45')
>>> Decimal("1.454").quantize(Decimal("1e-2"), ROUND_DOWN)
Decimal('1.45')

# Round up (ceiling)
>>> Decimal("1.455").quantize(Decimal("0.01"), ROUND_UP)
Decimal('1.46')
>>> Decimal("1.454").quantize(Decimal("1e-2"), ROUND_UP)
Decimal('1.46')

Dataclasses and Immutability

Dataclasses provide a convenient way to define classes for storing data with minimal boilerplate. They automatically generate special methods like __init__(), __repr__(), and __eq__().

When defining a dataclass, you can use the frozen=True parameter to make instances of the class immutable. This means that once an instance is created, its fields cannot be modified. It provides several benefits:

1. Safety: Immutability ensures that the data cannot be accidentally changed, which can prevent bugs.

2. Hashability: Frozen dataclasses can be used as dictionary keys or added to sets, as they implement __hash__().

from dataclasses import dataclass

@dataclass(frozen=True)
class User:
    id: int
    name: str
    email: str

When dealing with optional values in dataclasses, it’s best to set them to None by default. This clearly indicates that the field is optional and not required during the creation of an instance.

from dataclasses import dataclass
from typing import Optional

@dataclass(frozen=True)
class UserProfile:
    id: int
    username: str
    bio: Optional[str] = None
    website: Optional[str] = None

If you need to use a default mutable value, such as a list or dictionary, use the field function from the dataclasses module with a default factory. This ensures that each instance of the dataclass gets its own separate copy of the mutable object.

from dataclasses import dataclass, field
from typing import List

@dataclass(frozen=True)
class UserSettings:
    id: int
    preferences: List[str] = field(default_factory=list)

Required values should not have a default value. This ensures that they must be provided when creating an instance of the dataclass. By omitting the default value, you make it clear which fields are mandatory.

from dataclasses import dataclass

@dataclass(frozen=True)
class Product:
    id: int
    name: str
    price: float
    description: str = "No description available"

Pathlib instead of OS library

The pathlib library, provides an object-oriented approach to handling filesystem paths. It is a more intuitive and flexible alternative to the traditional os and os.path modules.

Benefits of using pathlib over os:

1. Readability: pathlib makes code more readable by using objects to represent paths, which allows for more expressive and chainable methods.

2. Cross-Platform Compatibility: pathlib handles different path formats across operating systems, reducing the need for platform-specific code.

3. Conciseness: Many common file operations can be performed in fewer lines of code compared to the os module.

4. Integration: pathlib integrates well with other Python libraries and functions that accept path-like objects.

You can easily create and manipulate path objects:

from pathlib import Path

# Create a Path object
path = Path('/home/user/documents')

# Join paths
new_path = path / 'myfile.txt'

# Get the parent directory
parent = path.parent

It provides methods for common file operations:

from pathlib import Path

path = Path('/home/user/documents/myfile.txt')

# Check if a path exists
if path.exists():
    print(f"{path} exists")

dir_path = Path('/home/user/documents')

# Create a new directory
dir_path.mkdir(parents=True, exist_ok=True)

# List all files in a directory
for file in dir_path.iterdir():
    print(file)

# Recursively list all PDF files in a directory
for file in dir_path.glob('*.[pP][dD][fF]'):
    print(file)