ProBat Testing

Overview

ProBat is the native unit testing engine of tlppCore for creating and executing tests in TLPP programs on TOTVS Protheus. The name comes from Latin and means "proof/tests". It supports unit, functional, and integration tests, code coverage analysis, TDD workflows, and CI/CD integration.

ProBat only works with TLPP. Tests for ADVPL sources must also be written in TLPP. If the target code is .prw, the test file is still .tlpp.

Required Include

Every test file must include the ProBat header:

#include "tlpp-probat.th"

If using tlppCore features (JsonObject, REST, etc.), also include:

#include "tlpp-core.th"
#include "tlpp-probat.th"

Namespace Convention

Test namespaces follow the pattern test.<module> or custom.tests.<module>:

namespace test.financeiro
namespace custom.tests.faturamento

Annotations

All annotations below are confirmed in the official TOTVS tlpp-probat-samples repository.

@TestFixture

Marks a function or class as a test fixture. This is the only way ProBat discovers test code.

// Minimal
@TestFixture()

// With properties
@TestFixture(owner='team_name')
@TestFixture(owner='team_name', target='source_file.tlpp')
@TestFixture(owner='team_name', suite='suite_name')
@TestFixture(priority=1)
@TestFixture(runWithAll=.F.)  // Exclude from "run all" mode
@TestFixture(rwa=.F.)        // Short alias for runWithAll

@Test

Marks a method in a @TestFixture class as a test to execute. The description parameter is mandatory.

@Test('description of what is being tested')
public method myTestMethod()

If a class has @TestFixture but no methods with @Test, the result will be SKIPPED.

@OneTimeSetUp (runs once before all tests)

Marks a method to run once before all @Test methods in the class. Multiple @OneTimeSetUp methods are allowed.

@OneTimeSetUp()
public method initDatabase()

@Setup (runs before each test)

Marks a method to run before each @Test method.

@Setup()
public method resetState()

@TearDown (runs after each test)

Marks a method to run after each @Test method.

@TearDown()
public method cleanupState()

@OneTimeTearDown (runs once after all tests)

Marks a method to run once after all @Test methods in the class.

@OneTimeTearDown()
public method closeConnections()

@Skip

Skips an entire test fixture (function or class) or a specific method. Supports conditional filters.

// Skip unconditionally
@Skip()

// Skip with filters
@Skip(system="windows")
@Skip(appServerName="HARPIA")
@Skip(tlppVersion=">= 01.02.10")
@Skip(system="windows", appServerName="HARPIA", tlppVersion=">= 01.02.10")

@ErrorLog

Marks a test that is expected to produce an error. The test passes if the specified error occurs.

@Test('test that expects an error')
@ErrorLog('type mismatch')
public method testExpectedError()

SKIPASSERT (inline command)

Skips the next assertion only. Useful for conditional skipping inside a test.

SKIPASSERT
assertError('this assert will be skipped')

// With filters
SKIPASSERT TLPPVERSION ">= 01.02.10"
SKIPASSERT SYSTEM "windows"
SKIPASSERT APPSERVERNAME "HARPIA"
SKIPASSERT SYSTEM "windows" APPSERVERNAME "HARPIA" TLPPVERSION ">= 01.02.10"

Assertion Functions

All assertions belong to the tlpp.probat namespace. They can be called either by using the namespace directive or with the full qualified name.

// Option 1: using namespace
using namespace tlpp.probat
assertEquals(xValue, xExpected, 'description')

// Option 2: full qualified name
tlpp.probat.assertEquals(xValue, xExpected, 'description')

Complete Assertion Reference

Execution Lifecycle (Class-based)

Constructor (new)
  |
  +-- @OneTimeSetUp methods (once)
        |
        +-- @Setup methods (before each test)
        |     |
        |     +-- @Test method
        |     |
        |     +-- @TearDown methods (after each test)
        |
        +-- @Setup methods (before each test)
        |     |
        |     +-- @Test method
        |     |
        |     +-- @TearDown methods (after each test)
        |
        +-- @OneTimeTearDown methods (once)

Test Execution

Via REST API (programmatic)

Tests can be discovered and executed using ProBat's REST API or through the main runner. See the official tlpp-probat-samples repository for script-based execution examples.

Via VSCode Extension

TOTVS provides a VSCode extension for ProBat that integrates test discovery and execution directly into the editor.

References

• patterns-unit-tests.md - Templates and patterns for writing ProBat tests
• Official samples - TOTVS official ProBat examples repository
• TDN ProBat - Official documentation on TOTVS Developer Network
• TDN Asserts - Assertion functions reference