Serviço SFUnitTests.UnitTest

O serviço UnitTest fornece um framework para automatização de testes de unidade usando a linguagem Basic, incluindo a possibilidade de:

Agregar casos de teste em suítes de teste e testes de unidade.
Compartilhar código de preparação e finalização entre testes de caso.
Reportar os resultados dos testes usando o Console.

Tanto os testes unitários quanto o código a ser testado devem ser escritos em BASIC. O código que está sendo testado pode chamar funções escritas em outras linguagens.

O serviço UnitTest não está disponível para scripts em Python.

Definições

Test Case

Um caso de teste é a unidade individual de teste. Ele verifica uma resposta específica para um determinado conjunto de entradas.

No serviço UnitTest, um caso de teste é representado por um único Sub do BASIC cujo nome começa com um prefixo comum (o padrão é "Test_").

O caso de teste falha se um dos métodos AssertX retornar False.

Suíte de teste

Uma suite de teste é uma coleção de casos de teste que devem ser executados juntos.

Todos os casos de teste de uma suíte são armazenados num único módulo do BASIC.

Uma suíte de testes pode implementar os métodos SetUp e TearDown para preparar os casos de teste em seu módulo.

Unidade de teste

Uma unidade de teste completa consiste de um conjunto de suítes de teste na mesma biblioteca BASIC.

Invocação do serviço

Antes de usar o serviço UnitTest a biblioteca ScriptForge precisa ser carregada ou importada:

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService

Modo simples

Chame o serviço no modo simples para chamar as funções AssertX sem ter que construir a hierarquia completa de suítes de testes e casos de teste.

No modo simples, o serviço é invocado dentro do caso de teste, conforme mostrado no exemplo abaixo:


    Sub SimpleTest
        On Local Error GoTo CatchError
        Dim myTest As Variant
        myTest = CreateScriptService("UnitTest")
        ' Alguns testes fictícios
        myTest.AssertEqual(1 + 1, 2)
        myTest.AssertEqual(1 - 1, 0)
        MsgBox("Passou todos os testes")
        Exit Sub
    CatchError:
        myTest.ReportError("Um teste falhou")
    End Sub

Neste exemplo, se qualquer uma das chamadas AssertEqual falhar, o interpretador irá para o rótulo CatchError e reportará o erro chamando o método ReportError .

Modo completo

Quando invocado no modo completo, a criação do serviço é externa ao código de teste e todos os testes são organizados em casos de teste e suítes de teste dentro de uma única biblioteca.

O exemplo a seguir cria uma instância UnitTest cujos testes estão localizados dentro do documento atual (ThisComponent) na biblioteca "Tests".


    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myUnitTest As Variant
    myUnitTest = CreateScriptService("UnitTest", ThisComponent, "Tests")

Um exemplo minimalista em modo completo

Considere que um arquivo ODS possui um módulo chamado "MathUtils" em sua biblioteca "Standard" com o seguinte código:


    ' Código no módulo Standard.MathUtils
    Function Sum(a, b) As Double
        Sum = a + b
    End Function
    
    Function Multiply(a, b) As Double
        Multiply = a * b
    End Function

Para criar uma suíte de testes completa, considere que uma nova biblioteca chamada "Tests" é criada no arquivo com um único módulo "AllTests" contendo o código abaixo:


    ' Código no módulo Tests.AllTests
    Sub Main()
        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim test As Variant
        test = CreateScriptService("UnitTest", ThisComponent, "Tests")
        test.RunTest("AllTests")
        test.Dispose()
    End Sub
    
    Sub Setup(test)
        ' O código de preparação foi executado antes do primeiro caso de teste
        Dim exc As Variant
        exc = CreateScriptService("Exception")
        exc.Console(Modal := False)
    End Sub
    
    Sub TearDown(test)
        ' Código de limpeza opcional chamado após o último caso de teste
    End Sub
    
    Sub Test_Sum(test)
        On Local Error GoTo CatchError
        test.AssertEqual(Sum(1, 1), 2, "Soma dois inteiros positivos")
        test.AssertEqual(Sum(-10, 20), 10, "Soma de inteiros negativos e positivos")
        test.AssertEqual(Sum(1.5, 1), 2.5, "Soma de valores inteiros e ponto flutuante")
        Exit Sub
    CatchError:
        test.ReportError("O método Soma não funciona")
    End Sub
    
    Sub Test_Multiply(test)
        On Local Error GoTo CatchError
        test.AssertEqual(Multiply(2, 2), 4, "Multiplica dois inteiros positivos")
        test.AssertEqual(Multiply(-4, 2), -8, "Multiplica inteiros negativos e positivos")
        test.AssertEqual(Multiply(1.5, 3), 4.5, "Multiplica valores inteiro e de ponto flutuante")
        Exit Sub
    CatchError:
        test.ReportError("O método Multiplicar não funciona")
    End Sub

O suíte de testes acima consiste em dois casos de teste Test_Sum e Test_Multiply. Para executar todos os testes, basta executar o método Main do módulo "AllTests".

O Console do serviço Exception é usado como saída padrão para imprimir os resultados do teste. Após executar o exemplo acima, a seguinte saída será exibida no console:


    ' RUNTEST ENTER testsuite='Tests.AllTests', pattern='Test_*'
    '   SETUP Tests.AllTests.Setup() ENTER
    '   SETUP Tests.AllTests.Setup() EXIT
    '   TESTCASE Tests.AllTests.Test_Multiply() ENTER
    '   TESTCASE Tests.AllTests.Test_Multiply() EXIT (0,017 sec)
    '   TESTCASE Tests.AllTests.Test_Sum() ENTER
    '   TESTCASE Tests.AllTests.Test_Sum() EXIT (0,016 sec)
    '   TEARDOWN Tests.AllTests.TearDown() ENTER
    '   TEARDOWN Tests.AllTests.TearDown() EXIT
    ' RUNTEST EXIT testsuite='Tests.AllTests' (0,223 sec)

Se algum dos métodos AssertEqual falhar durante esses testes, uma mensagem de erro será adicionada ao console.

Propriedades

Nome	Só leitura	Tipo	Descrição
LongMessage	Não	Boolean	Quando definido como True (padrão), o console mostra a mensagem padrão anexada à mensagem fornecida pelo testador. Quando False, apenas a mensagem definida pelo testador é usada.
ReturnCode	Sim	Integer	Valor retornado por RunTest após a conclusão do teste de unidade. A seguir, uma lista de valores possíveis: 0 - Teste finalizado sem erros ou teste não iniciado 1 - Uma asserção dentro de um caso de teste retornou False 2 - Um SkipTest foi emitido pelo Método Setup ou por um dos casos de teste. 3 - Final de teste anormal
Verbose	Não	Boolean	Quando definido como True, todas as asserções são relatadas no console (com falha ou não). Quando False (padrão), apenas as asserções com falha são relatadas.
WhenAssertionFails	Não	Integer	Define o que é feito quando uma asserção falha. A seguir, uma lista de valores possíveis: 0 - Ignora a falha e continua executando o teste 1 - Executa na suíte de teste o método TearDown no módulo e a próxima suíte de testes é iniciada (padrão em modo completo). 2 - Para imediatamente (padrão no modo simples)

Lista de métodos no serviço UnitTest
AssertAlmostEqual AssertEqual AssertFalse AssertGreater AssertGreaterEqual AssertIn AssertIsInstance AssertIsNothing AssertLike	AssertNotRegex AssertIsNull AssertLess AssertLessEqual AssertNotAlmostEqual AssertNotEqual AssertNotIn AssertNotInstance AssertNotLike	AssertNotNothing AssertNotNull AssertRegex AssertTrue Fail Log ReportError RunTest SkipTest

Argumentos dos métodos AssertX

Todas as asserções testam uma ou duas expressões, referidas no restante desta página de ajuda como A e B. Eles são sempre os primeiros ou segundos argumentos no método AssertX.

Todos os métodos AssertX aceitam um argumento message especificando uma mensagem personalizada a ser relatada no console referente à asserção. Por padrão, utiliza uma string vazia. Este argumento está sempre na última posição da asserção.

Alguns métodos AssertX também aceitam argumentos adicionais, conforme descrito por suas sintaxes abaixo.

AssertAlmostEqual

Retorna True quando A e B são valores numéricos e são considerados próximos um do outro, dada uma tolerância relativa.

Sintaxe:

svc.AssertAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool

Esta declaração retorna True se as duas condições abaixo forem atendidas:

A e B podem ser convertidos para o tipo Double.
A diferença absoluta entre A e B dividida pelo maior valor absoluto de A ou B é menor que o valor especificado em tolerância.

AssertEqual

Retorna True quando A e B são considerados iguais.

Sintaxe:

svc.AssertEqual(a: any, b: any, message: str = ""): bool

Quando A e B são escalares, retorna True se:

Ambas as expressões têm o mesmo VarType ou são ambas numéricas.
Os valores booleanos e numéricos são comparados com o operador =.
Strings são comparadas com a função interna StrComp. A comparação diferencia maiúsculas de minúsculas.
Datas e horas são comparadas até o segundo.
Null, Empty e Nothing não são iguais, mas AssertEqual(Nothing, Nothing) retorna True.
Objetos UNO são comparados com o método interno EqualUnoObjects.
Observe que os objetos Basic nunca são iguais.

Quando A e B são matrizes, retorna True se:

Ambas as matrizes têm o mesmo número de dimensões (até 2 dimensões) e seus limites inferior e superior são idênticos para todas as dimensões.
Todos os itens em ambas as matrizes são iguais, um por um.
Duas matrizes vazias são consideradas iguais.

AssertFalse

Retorna True quando o tipo de A é Boolean e seu valor é False.

Sintaxe:

svc.AssertFalse(a: any, message: str = ""): bool

AssertGreater

Retorna True quando A é maior que B.

Sintaxe:

svc.AssertGreater(a: any, b: any, message: str = ""): bool

A comparação entre A e B assume o seguinte:

Os tipos de dados elegíveis são String, Date ou numérico.
Ambas as expressões devem ter o mesmo VarType ou ambas devem ser numéricas.
As comparações de string diferenciam maiúsculas de minúsculas.

AssertGreaterEqual

Retorna True quando A é maior ou igual a B.

Sintaxe:

svc.AssertGreaterEqual(a: any, b: any, message: str = ""): bool

A comparação entre A e B assume o seguinte:

Os tipos de dados elegíveis são String, Date ou numérico.
Ambas as expressões devem ter o mesmo VarType ou ambas devem ser numéricas.
As comparações de string diferenciam maiúsculas de minúsculas.

AssertIn

Retorna True quando A está dentro de B.

Sintaxe:

svc.AssertIn(a: any, b: any, message: str = ""): bool

Esta asserção pressupõe o seguinte:

A expressão B pode ser uma matriz unidimensional, um objeto Dictionary do ScriptForge ou uma string.
Quando a expressão B é uma matriz unidimensional, a expressão A pode ser uma data ou um valor numérico.
Quando a expressão B é um objeto Dictionary do ScriptForge, então a string A é procurada entre as chaves em B.
As comparações de string diferenciam maiúsculas de minúsculas.

AssertIsInstance

Retorna True quando A é uma instância de um tipo de objeto especificado, indicado como uma string contendo o nome do tipo.

Sintaxe:

svc.AssertIsInstance(a: any, objecttype: str, message: str = ""): bool

A expressão A pode ser uma das seguintes:

Um objeto ScriptForge. Neste caso, o argumento objecttype é uma string como "DICTIONARY", "calc", "Dialog", etc.
Um objeto UNO. Neste caso, o argumento objecttype deve ser uma string idêntica ao valor retornado pelo método SF_Session.UnoObjectType().
Uma matriz. Neste caso, espera-se que o argumento objecttype seja "array".
Qualquer outra variável (que não seja um Object ou um Array). Neste caso, objecttype é uma string que corresponde ao valor retornado pela função interna TypeName.

AssertIsNothing

Retorna True quando A é um objeto que tem o valor Nothing.

Sintaxe:

svc.AssertIsNothing(a: any, message: str = ""): bool

AssertIsNull

Retorna True quando A tem o valor Null.

Sintaxe:

svc.AssertIsNull(a: any, message: str = ""): bool

AssertLess

Retorna True quando A é menor que B.

Sintaxe:

svc.AssertLess(a: any, b: any, message: str = ""): bool

A comparação entre A e B assume o seguinte:

Os tipos de dados elegíveis são String, Date ou numérico.
Ambas as expressões devem ter o mesmo VarType ou ambas devem ser numéricas.
As comparações de string diferenciam maiúsculas de minúsculas.

AssertLessEqual

Retorna True quando A é menor ou igual a B.

Sintaxe:

svc.AssertLessEqual(a: any, b: any, message: str = ""): bool

A comparação entre A e B assume o seguinte:

Os tipos de dados elegíveis são String, Date ou numérico.
Ambas as expressões devem ter o mesmo VarType ou ambas devem ser numéricas.
As comparações de string diferenciam maiúsculas de minúsculas.

AssertLike

Retorna True se a String A corresponde a um dado padrão contendo caracteres curinga.

Sintaxe:

svc.AssertLike(a: any, pattern: str = "", message: str = ""): bool

Os seguintes caracteres curinga são aceitos:

"?" representa qualquer caractere único.
* - representa zero, um ou múltiplos caracteres.

AssertNotAlmostEqual

Retorna True quando A e B são valores numéricos e não são considerados próximos um do outro, dada uma tolerância relativa.

Sintaxe:

svc.AssertNotAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool

Esta declaração retorna True se as duas condições abaixo forem atendidas:

A e B podem ser convertidos para o tipo Double.
A diferença absoluta entre A e B dividida pelo maior valor absoluto de A ou B é maior que o valor especificado em tolerância.

AssertNotEqual

Retorna True quando A e B não são considerados iguais.

Sintaxe:

svc.AssertNotEqual(a: any, b: any, message: str = ""): bool

Este método funciona tanto para escalares quanto para matrizes. Leia as instruções em AssertEqual para obter mais informações sobre o que significa igualdade nesta asserção.

AssertNotIn

Retorna True quando A (uma string) não é encontrada em B.

Sintaxe:

svc.AssertNotIn(a: any, b: any, message: str = ""): bool

Leia as instruções em AssertIn para obter mais informações sobre as premissas deste método .

AssertNotInstance

Retorna True quando A não é uma instância de um tipo de objeto especificado.

Sintaxe:

svc.AssertNotInstance(a: any, objecttype: str, message: str = ""): bool

Consulte AssertIsInstance para obter mais informações sobre as premissas desse método .

AssertNotLike

Retorna True se a String A não corresponde a um dado padrão contendo caracteres curinga.

Sintaxe:

svc.AssertNotLike(a: any, pattern: str = "", message: str = ""): bool

Consulte AssertLike para obter mais informações sobre as premissas deste método .

AssertNotNothing

Retorna True exceto quando A é um objeto que tem o valor Nothing.

Sintaxe:

svc.AssertNotNothing(a: any, message: str = ""): bool

AssertNotNull

Retorna True exceto quando A tem o valor Null.

Sintaxe:

svc.AssertNotNull(a: any, message: str = ""): bool

AssertNotRegex

Retorna True quando A não é uma string ou não corresponde à expressão regular fornecida.

Sintaxe:

svc.AssertNotRegex(a: any, regex: str = "", message: str = ""): bool

A comparação diferencia maiúsculas de minúsculas.

AssertRegex

Retorna True se a String A corresponde a uma dada expressão regular.

Sintaxe:

svc.AssertRegex(a: any, regex: str = "", message: str = ""): bool

A comparação diferencia maiúsculas de minúsculas.

AssertTrue

Retorna True quando a expressão A é Boolean e seu valor é True.

Sintaxe:

svc.AssertTrue(a: any, message: str = ""): bool

Fail

Força um teste a falhar.

Sintaxe:

svc.Fail(message: str = "")

Uma mensagem pode ser fornecida para ser relatada no console.

Log

Grava a mensagem especificada no console.

Sintaxe:

svc.Log(message: str = "")

Uma mensagem pode ser fornecida para ser relatada no console.

ReportError

Exibe uma caixa de diálogo com uma mensagem e os valores de propriedade atuais do serviço Exception.

Este método é comumente usado na seção de tratamento de exceções de uma Sub que contém o caso de teste, que é alcançado quando uma asserção falha ou quando chamar o método Fail.

Sintaxe:

svc.ReportError(message: str = "")

Dependendo do valor da propriedade WhenAssertionFails, a execução do teste pode continuar ou ser interrompida.

Ao escrever casos de teste é recomendado incluir uma chamada para o método ReportError na seção de tratamento de exceções da Sub.

Se a propriedade LongMessage for True, a mensagem especificada será seguida pela descrição da mensagem de erro padrão. Caso contrário, apenas a mensagem será exibida.

RunTest

Executa o conjunto de testes completo implementado no módulo especificado. Cada caso de teste é executado independentemente um do outro.

A execução de um suíte de testes consiste de:

Executar o método opcional Setup presente no módulo.
Executar uma vez a cada caso de teste, sem ordem específica.
Executar o método opcional TearDown presente no módulo.

Sintaxe:

svc.RunTest(testsuite: str, testcasepattern: str = "", message: str = ""): int

O argumento testcasepattern especifica um padrão composto por "?" e curingas "*" para selecionar quais casos de teste serão executados. A comparação não diferencia maiúsculas de minúsculas.

Se fornecer uma mensagem, ela será gravada no console quando o teste for iniciado.

SkipTest

Interrompe a suíte de testes em execução sem chamar o método TearDown.

Ignorar um teste geralmente faz sentido no método Setup quando nem todas as condições para executar o teste são atendidas.

Cabe ao método Setup sair do Sub logo após a chamada SkipTest.

Se SkipTest for chamado de dentro de um caso de teste, a execução do conjunto de testes será interrompida e os casos de teste restantes não serão executados. Lembre-se de que a ordem na qual os casos de teste são executados é arbitrária em um conjunto de testes.

Sintaxe:

svc.SkipTest(message: str = "")

Se fornecer uma mensagem, ela será gravada no console.

Serviço ScriptForge.Exception