Estrutura UnitTest - API Doctest

A API doctest gira em torno das duas classes de contêiner a seguir, usadas para armazenar exemplos interativos de docstrings -

  • Example - Uma única instrução Python, emparelhada com sua saída esperada.

  • DocTest - Uma coleção de exemplos, normalmente extraídos de uma única docstring ou de um arquivo de texto.

As seguintes classes de processamento adicionais são definidas para localizar, analisar, executar e verificar exemplos de doctest -

  • DocTestFinder - Encontra todas as docstrings em um determinado módulo e usa um DocTestParser para criar um DocTest de cada docstring que contém exemplos interativos.

  • DocTestParser - Cria um objeto doctest a partir de uma string (como a docstring de um objeto).

  • DocTestRunner - Executa os exemplos em um doctest e usa um OutputChecker para verificar sua saída.

  • OutputChecker - Compara a saída real de um exemplo doctest com a saída esperada e decide se eles correspondem.

Classe DocTestFinder

É uma classe de processamento usada para extrair os doctests que são relevantes para um determinado objeto, de seu docstring e os docstrings de seus objetos contidos. Atualmente, os doctests podem ser extraídos dos seguintes tipos de objeto - módulos, funções, classes, métodos, métodos estáticos, métodos de classe e propriedades.

Esta classe define o método find (). Ele retorna uma lista de DocTests que são definidos pela docstring do objeto , ou por qualquer uma das docstrings de seus objetos contidos.

Classe DocTestParser

É uma classe de processamento usada para extrair exemplos interativos de uma string e usá-los para criar um objeto DocTest. Esta classe define os seguintes métodos -

  • get_doctest() - Extraia todos os exemplos de doctest da string fornecida e colete-os em um DocTest objeto.

  • get_examples(string[, name]) - Extraia todos os exemplos de doctest da string fornecida e retorne-os como uma lista de Exampleobjetos. Os números das linhas são baseados em 0. O nome do argumento opcional é um nome que identifica esta string e é usado apenas para mensagens de erro.

  • parse(string[, name]) - Divida a string dada em exemplos e textos intermediários e retorne-os como uma lista de Examplese cordas. Números de linha para oExamplessão baseados em 0. O nome do argumento opcional é um nome que identifica esta string e é usado apenas para mensagens de erro.

Classe DocTestRunner

Esta é uma classe de processamento usada para executar e verificar os exemplos interativos em um DocTest. Os seguintes métodos são definidos nele -

report_start ()

Relate que o executor de teste está prestes a processar o exemplo fornecido. Este método é fornecido para permitir subclasses deDocTestRunnerpara personalizar sua saída; não deve ser chamado diretamente

report_success ()

Relate que o exemplo fornecido foi executado com sucesso. Este método é fornecido para permitir que subclasses de DocTestRunner personalizem sua saída; ele não deve ser chamado diretamente.

report_failure ()

Relate que o exemplo fornecido falhou. Este método é fornecido para permitir subclasses deDocTestRunnerpara personalizar sua saída; ele não deve ser chamado diretamente.

report_unexpected_exception ()

Relate que o exemplo fornecido gerou uma exceção inesperada. Este método é fornecido para permitir que subclasses de DocTestRunner personalizem sua saída; ele não deve ser chamado diretamente.

teste de corrida)

Execute os exemplos em teste (um objeto DocTest) e exiba os resultados usando a função de gravação de saída .

resumir ([detalhado])

Imprima um resumo de todos os casos de teste que foram executados por este DocTestRunner e retorne uma tupla nomeada TestResults (falhou, tentou). O argumento detalhado opcional controla o quão detalhado é o resumo. Se a verbosidade não for especificada, a verbosidade do DocTestRunner é usada.

Classe OutputChecker

Esta classe é usada para verificar se a saída real de um exemplo doctest corresponde à saída esperada.

Os seguintes métodos são definidos nesta classe -

check_output ()

Retorna Truese a saída real de um exemplo ( obtido ) corresponder à saída esperada ( desejado ). Essas strings são sempre consideradas correspondentes se forem idênticas; mas dependendo de quais sinalizadores de opção o executor de teste está usando, vários tipos de correspondência não exata também são possíveis. Consulte a seção Sinalizadores de opção e diretivas para obter mais informações sobre sinalizadores de opção.

output_difference ()

Retorne uma string que descreve as diferenças entre a saída esperada para um determinado exemplo ( exemplo ) e a saída real ( obtida ).

Integração DocTest com Unittest

O módulo doctest fornece duas funções que podem ser usadas para criar suites de teste de unidade a partir de módulos e arquivos de texto contendo doctests. Para integrar com a descoberta de teste unittest, inclua uma função load_tests () em seu módulo de teste -

import unittest
import doctest
import doctestexample

def load_tests(loader, tests, ignore):
   tests.addTests(doctest.DocTestSuite(doctestexample))
   return tests

Um TestSuite combinado de testes de unittest e doctest será formado e agora pode ser executado pelo método main () ou pelo método run () do módulo unittest.

A seguir estão as duas funções principais para criar unittest.TestSuite instâncias de arquivos de texto e módulos com os doctests -

doctest.DocFileSuite ()

É usado para converter testes doctest de um ou mais arquivos de texto para um unittest.TestSuite. O unittest.TestSuite retornado deve ser executado pela estrutura unittest e executa os exemplos interativos em cada arquivo. Se algum dos exemplos em um arquivo falhar, o teste de unidade sintetizada falhará e umfailureException exceção é levantada mostrando o nome do arquivo que contém o teste e um número de linha (às vezes aproximado).

doctest.DocTestSuite ()

É usado para converter testes doctest de um módulo para um unittest.TestSuite.

O unittest.TestSuite retornado deve ser executado pela estrutura unittest e executa cada doctest no módulo. Se algum dos testes de documentos falhar, o teste de unidade sintetizado falhará e umfailureException exceção é levantada mostrando o nome do arquivo que contém o teste e um número de linha (às vezes aproximado)

Nos bastidores, DocTestSuite () cria um unittest.TestSuite fora das instâncias doctest.DocTestCase, e DocTestCase é uma subclasse de unittest.TestCase.

Da mesma forma, DocFileSuite () cria um unittest.TestSuite fora das instâncias doctest.DocFileCase e DocFileCase é uma subclasse de DocTestCase.

Portanto, as duas maneiras de criar um unittest.TestSuite executam instâncias de DocTestCase. Quando você mesmo executa as funções doctest, pode controlar as opções doctest em uso diretamente, passando sinalizadores de opção para funções doctest.

No entanto, se você estiver escrevendo uma estrutura de teste de unidade, o teste de unidade controla quando e como os testes são executados. O autor do framework normalmente deseja controlar as opções de relatório do doctest (talvez, por exemplo, especificadas por opções de linha de comando), mas não há como passar as opções de teste de unidade para executores de teste de doctest.