Tir Test Generator

⚠️ O TIR não é a forma oficial de testar neste plugin — ele não tem visão computacional. A engine oficial de E2E é o Playwright (/protheus:test-web, com screenshots e validação visual). Use esta skill apenas para gerar suíte de regressão CI re-executável sem LLM, derivada de uma sessão Playwright já validada (ver /protheus:qa).

Protheus TIR Test Generator

Overview

Generate end-to-end interface test scripts in Python for the TOTVS Protheus ERP using the TIR (TOTVS Interface Robot) framework. TIR automates Protheus screens through the SmartClient/Webapp interface, validating complete user workflows including screen navigation, field interaction, grid manipulation, button clicks, and result assertions.

TIR tests use Python's unittest framework combined with the tir.Webapp class to:

1. Connect to a running Protheus Webapp environment
2. Navigate to specific routines via Program()
3. Interact with screen elements (fields, grids, buttons, folders)
4. Assert field values, screen states, and data integrity
5. Tear down the session cleanly

When to Use

Use this skill when:

• Creating end-to-end UI tests for Protheus screens (CRUD, workflows)
• Testing MVC-generated screens via the SmartClient/Webapp interface → use Webapp class
• Validating critical user journeys (complete business flows)
• Testing screen navigation, menu access, and dialog handling
• Validating field interactions (fill, check, read values)
• Testing grid operations (add rows, edit cells, scroll, select)
• Validating reports via parameter screens
• Needing visual/interface-level regression tests

When NOT to Use

• TLPP unit tests → Use ProBat (@TestFixture)

Which TIR Class to Use?

TIR Three-File Architecture (MANDATORY)

Every TIR test project requires three files:

Without config.json in the same directory, TIR cannot connect to Protheus.

{test_directory}/
├── {ROUTINE}TESTCASE.py    ← test class
├── {ROUTINE}TESTSUITE.py   ← runner (CI/CD entry point)
└── config.json             ← environment config (REQUIRED)

config.json — Webapp (MVC/Legacy)

{
    "Url": "http://{server}:{port}/",
    "Browser": "Chrome",
    "Environment": "{environment_name}",
    "User": "{username}",
    "Password": "{password}",
    "Language": "pt-br"
}

For the complete config.json parameter reference (all sections: Required, Additional, Logging, Database, Chrome), see tir-setup-and-best-practices.md.

Complete File Templates

TESTCASE Template — Webapp (MVC/Legacy)

from tir import Webapp
import unittest

class {ROUTINE}(unittest.TestCase):
    """
    TIR E2E Tests for {ROUTINE} - {Description}
    Module: {MODULE}
    Tables: {TABLE_ALIASES}
    """

    @classmethod
    def setUpClass(inst):
        """Setup: Initialize Webapp, configure environment, open routine"""
        inst.oHelper = Webapp()
        inst.oHelper.Setup('{MODULE}', '{DATE}', 'T1', '{BRANCH}')
        inst.oHelper.Program('{ROUTINE}')

    def test_{ROUTINE}_CT001(self):
        """CT001 — Include record with required fields"""
        self.oHelper.SetButton('Incluir')
        self.oHelper.SetBranch('{BRANCH}')
        self.oHelper.SetValue('{Field Label 1}', '{value1}')
        self.oHelper.SetValue('{Field Label 2}', '{value2}')
        self.oHelper.SetButton('Salvar')
        self.oHelper.SearchBrowse(f'{BRANCH}{search_key}', key='Filial+{Search Column}')
        self.oHelper.SetButton('Visualizar')
        self.oHelper.CheckResult('{FIELD_NAME}', '{expected_value}')
        self.oHelper.SetButton('Cancelar')
        self.oHelper.AssertTrue()

    def test_{ROUTINE}_CT002(self):
        """CT002 — Edit existing record"""
        self.oHelper.SearchBrowse(f'{BRANCH}{search_key}', key='Filial+{Search Column}')
        self.oHelper.SetButton('Alterar')
        self.oHelper.SetValue('{Field Label}', '{new_value}')
        self.oHelper.SetButton('Salvar')
        self.oHelper.AssertTrue()

    def test_{ROUTINE}_CT003(self):
        """CT003 — Delete record"""
        self.oHelper.SearchBrowse(f'{BRANCH}{search_key}', key='Filial+{Search Column}')
        self.oHelper.SetButton('Outras Ações', sub_item='Excluir')
        self.oHelper.SetButton('Confirmar')
        self.oHelper.AssertTrue()

    def test_{ROUTINE}_CT004(self):
        """CT004 — Validate required field rule (negative)"""
        self.oHelper.SetButton('Incluir')
        self.oHelper.SetButton('Salvar')
        self.oHelper.CheckHelp(text_help='{HELP_ID}', button='Fechar')
        self.oHelper.SetButton('Cancelar')
        self.oHelper.AssertFalse()

    @classmethod
    def tearDownClass(inst):
        """Teardown: Close session and collect results"""
        inst.oHelper.TearDown()

if __name__ == '__main__':
    unittest.main()

TESTSUITE Template

import unittest

from {ROUTINE}TESTCASE import {ROUTINE}

suite = unittest.TestSuite()

suite.addTest({ROUTINE}('test_{ROUTINE}_CT001'))
suite.addTest({ROUTINE}('test_{ROUTINE}_CT002'))
suite.addTest({ROUTINE}('test_{ROUTINE}_CT003'))
suite.addTest({ROUTINE}('test_{ROUTINE}_CT004'))

runner = unittest.TextTestRunner(verbosity=2)
runner.run(suite)

TIR Webapp Key Methods Reference

For the complete TIR Webapp API reference (Setup & Lifecycle, Field Interaction, Browse & Navigation, Grid Operations, Assertions & Validation, Dialog Handling, Parameters & Configuration), see tir-webapp-methods-reference.md.

Test Script Patterns

For all complete test script templates (Standard CRUD, Master-Detail with Grid, Tabs/Folders, View/Validate, Validation Error, Other Actions Menu, Report with Parameters, Grid Checkbox Selection), see tir-test-patterns.md.

Step-by-Step Process

When generating TIR test scripts, follow this process:

1. Identify the Screen Type

2. Map Screen Elements

For each test, identify:

• Field labels as they appear on screen (used by SetValue)
• Field technical names (used by CheckResult, e.g., 'A1_COD', 'B1_DESC')
• Button labels (e.g., 'Incluir', 'Alterar', 'Salvar', 'Cancelar')
• Grid columns and their headers
• Tab/folder names
• Search key format for SearchBrowse — see UI Conventions & Pitfalls below for the right rule

UI Conventions & Pitfalls (LEARNED FROM REAL RUNS)

These are the details that separate a TIR script that runs from a script that fails at the first click. They are not negotiable — they came from running against real Protheus environments.

SearchBrowse — key name and padding

The key= argument must match the browse column header as rendered on screen, not a generic pattern. Two common headers in MVC routines:

Rule of thumb: the browse header is the source of truth. If in doubt, open the browse in a real session and read the sort-selector label. Do not invent 'Filial+codigo + Loja' for a routine that browses only by code — SearchBrowse will scroll past the record and never find it.

Sub-menus with multiple levels

When "Outras Ações" opens a sub-menu that opens another sub-menu (e.g., Outras Ações → Oportunidades → Nova Oportunidade), TIR requires pipe-separated sub-items:

# Correct — nested sub-menu with pipe
self.oHelper.SetButton('Outras Ações', sub_item='Oportunidades|Nova Oportunidade')

# Wrong — loses the intermediate level, click never registers
self.oHelper.SetButton('Outras Ações', sub_item='Nova Oportunidade')

If the spec path has → X → Y (two arrows after the main menu), use sub_item='X|Y'.

Close buttons — Cancelar vs Fechar vs Sair

Different screens use different close labels. The convention in Protheus MVC is:

Never use 'Sair' unless you have verified on the real screen. 'Sair' is rare in modern MVC and most of the time produces a ghost click that TIR reports as success while nothing happened.

CheckResult — technical name vs label

Do not guess technical names for related screens. If the spec only gives a label and the routine alias is different (UA_*, AE_*, etc.), use the label. A wrong technical name fails silently or — worse — matches a different field with the same prefix.

Validation of "screen opened"

Validating that a related screen opened is best done by asserting content, not just presence:

# Weak — asserts something appeared but doesn't prove it's the right thing
self.oHelper.WaitShow('Subclientes')

# Strong — confirms the expected child record is listed
self.oHelper.SearchBrowse(f'D MG 01{filho+loja}', key='Filial+codigo + Loja')

Use WaitShow as a safety net before the content assertion, not as a replacement for it.

Setup branch padding

The Setup() branch string and the SearchBrowse branch prefix must be character-for-character identical, including trailing spaces. 'D MG 01' (no space) and 'D MG 01 ' (trailing space) are different keys in the browse. Match what the live environment renders.

3. Define Test Scenarios

4. Handle Common Screen Interactions

5. Build the TESTSUITE

After generating the TESTCASE, always generate the TESTSUITE that:

1. Imports the test class from the TESTCASE file
2. Creates a unittest.TestSuite()
3. Adds each test method with suite.addTest()
4. Runs with unittest.TextTestRunner(verbosity=2)

Rationalization Guard

The moments the generator is most tempted to cut corners — and what actually happens.

Setup Requirements & Best Practices

For environment setup (Python, Webapp, tir.json configuration) and best practices (test independence, naming conventions, screen interactions, assertions, environment isolation), see tir-setup-and-best-practices.md.

Checklist

Before finalizing generated TIR test scripts, verify:

config.json:

• File present in the same directory as the test scripts
• Url, Browser, Environment, User, Password, Language all set
• No placeholder values like {server}, {username} remaining

TESTCASE file ({ROUTINE}TESTCASE.py):

• File named {ROUTINE}TESTCASE.py
• Class named {ROUTINE} inheriting from unittest.TestCase
• Correct class imported: from tir import Webapp
• setUpClass(inst) contains the correct class instantiation, Setup(), and Program() calls
• tearDownClass(inst) contains TearDown() call
• Setup() has correct module, date, group, and branch (4 args — 5th module is optional)
• Each test method starts with test_ prefix and has a docstring
• Positive tests end with self.oHelper.AssertTrue() — NO parameters
• Negative tests end with self.oHelper.AssertFalse() — NO parameters

Webapp-specific (MVC/Legacy):

• SetBranch() called after SetButton('Incluir') when needed
• SearchBrowse(term, key=...) uses key= kwarg with branch-prefixed term
• key= value matches the real browse header — single-key routines use 'Filial+codigo', composite-key routines use 'Filial+codigo + Loja' (verify, don't assume)
• Branch padding in Setup() matches exactly the branch padding in SearchBrowse (trailing space matters)
• Sub-menus with 2+ levels use pipe: sub_item='Level1\|Level2'
• Close buttons: 'Cancelar' for Visualizar/Alterar/Incluir forms; 'Fechar' for related-action sub-windows; 'Concluir'/'Finalizar' for wizard endings; never 'Sair' without verifying on the real screen
• CheckResult uses technical names ('A1_COD') only for the routine's own form; uses screen labels ('Cliente', 'Nome') for secondary screens whose model alias is unknown — do NOT guess aliases
• When a test validates "screen X opened", assert content (child record via SearchBrowse, specific field via CheckResult) — WaitShow alone is not enough
• CheckHelp(text_help=..., button=...) for error dialogs
• LoadGrid() called after grid SetValue operations

TESTSUITE file ({ROUTINE}TESTSUITE.py):

• File named {ROUTINE}TESTSUITE.py
• import unittest present
• from {ROUTINE}TESTCASE import {ROUTINE} present
• suite = unittest.TestSuite() created
• suite.addTest({ROUTINE}('test_{ROUTINE}_CT00N')) for each test method
• runner = unittest.TextTestRunner(verbosity=2) present
• runner.run(suite) present

Both files:

• No placeholder tokens like {ROUTINE}, {VALUE}, {FIELD} remaining
• No AssertTrue(value, msg) with parameters — TIR does not accept parameters

Related Skills