Framework UnitTest - API Doctest

L'API doctest ruota attorno alle seguenti due classi container utilizzate per memorizzare esempi interattivi da docstrings:

  • Example - Una singola istruzione Python, abbinata al suo output atteso.

  • DocTest - Una raccolta di esempi, tipicamente estratti da una singola docstring o da un file di testo.

Le seguenti classi di elaborazione aggiuntive sono definite per trovare, analizzare, eseguire e controllare esempi di doctest:

  • DocTestFinder - Trova tutte le docstring in un dato modulo e utilizza un DocTestParser per creare un DocTest da ogni docstring che contiene esempi interattivi.

  • DocTestParser - Crea un oggetto doctest da una stringa (come la docstring di un oggetto).

  • DocTestRunner - Esegue gli esempi in un doctest e utilizza un OutputChecker per verificarne l'output.

  • OutputChecker - Confronta l'output effettivo di un esempio doctest con l'output previsto e decide se corrispondono.

Classe DocTestFinder

È una classe di elaborazione usata per estrarre i doctest rilevanti per un dato oggetto, dalla sua docstring e dalle docstring dei suoi oggetti contenuti. Doctests può attualmente essere estratto dai seguenti tipi di oggetti: moduli, funzioni, classi, metodi, metodi statici, metodi di classe e proprietà.

Questa classe definisce il metodo find (). Restituisce un elenco dei DocTest definiti dalla docstring dell'oggetto o da una qualsiasi delle docstring degli oggetti contenuti.

DocTestParser Class

È una classe di elaborazione utilizzata per estrarre esempi interattivi da una stringa e utilizzarli per creare un oggetto DocTest. Questa classe definisce i seguenti metodi:

  • get_doctest() - Estrai tutti gli esempi di doctest dalla stringa data e raccoglili in un file DocTest oggetto.

  • get_examples(string[, name]) - Estrai tutti gli esempi di doctest dalla stringa data e restituiscili come un elenco di file Exampleoggetti. I numeri di riga sono in base 0. Il nome dell'argomento facoltativo è un nome che identifica questa stringa e viene utilizzato solo per i messaggi di errore.

  • parse(string[, name]) - Dividi la stringa data in esempi e testo intermedio e restituiscili come un elenco di alternanze Examplese archi. Numeri di riga perExamplessono a base 0. Il nome dell'argomento facoltativo è un nome che identifica questa stringa e viene utilizzato solo per i messaggi di errore.

DocTestRunner Class

Questa è una classe di elaborazione utilizzata per eseguire e verificare gli esempi interattivi in ​​un DocTest. I seguenti metodi sono definiti in esso:

report_start ()

Segnala che il test runner sta per elaborare l'esempio fornito. Questo metodo viene fornito per consentire le sottoclassi diDocTestRunnerpersonalizzarne l'output; non dovrebbe essere chiamato direttamente

report_success ()

Segnala che l'esempio fornito è stato eseguito correttamente. Questo metodo viene fornito per consentire alle sottoclassi di DocTestRunner di personalizzare il proprio output; non dovrebbe essere chiamato direttamente.

report_failure ()

Segnala che l'esempio fornito non è riuscito. Questo metodo viene fornito per consentire le sottoclassi diDocTestRunnerpersonalizzarne l'output; non dovrebbe essere chiamato direttamente.

report_unexpected_exception ()

Segnala che l'esempio fornito ha sollevato un'eccezione imprevista. Questo metodo viene fornito per consentire alle sottoclassi di DocTestRunner di personalizzare il proprio output; non dovrebbe essere chiamato direttamente.

eseguire (test)

Eseguire gli esempi in test (un oggetto DocTest) e visualizzare i risultati utilizzando la funzione writer out .

riassumere ([verbose])

Stampa un riepilogo di tutti i casi di test che sono stati eseguiti da questo DocTestRunner e restituisci una tupla TestResults con nome (fallito, tentato). L' argomento dettagliato facoltativo controlla il livello di dettaglio del riepilogo. Se la verbosità non è specificata, viene utilizzata la verbosità del DocTestRunner.

Classe OutputChecker

Questa classe viene utilizzata per verificare se l'output effettivo di un esempio doctest corrisponde all'output atteso.

I seguenti metodi sono definiti in questa classe:

check_output ()

Ritorno Truese l'output effettivo di un esempio ( got ) corrisponde all'output atteso ( want ). Queste stringhe sono sempre considerate corrispondenti se sono identiche; ma a seconda dell'opzione flag utilizzata dal test runner, sono possibili anche diversi tipi di corrispondenza non esatta. Vedere la sezione Flag di opzione e direttive per ulteriori informazioni sui flag di opzione.

output_difference ()

Restituisce una stringa che descrive le differenze tra l'output previsto per un dato esempio ( esempio ) e l'output effettivo ( got ).

Integrazione di DocTest con Unittest

Il modulo doctest fornisce due funzioni che possono essere utilizzate per creare suite di test unittest da moduli e file di testo contenenti doctest. Per l'integrazione con unittest test discovery, includi una funzione load_tests () nel tuo modulo di test -

import unittest
import doctest
import doctestexample

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

Verrà formata una TestSuite combinata di test da unittest e doctest e ora può essere eseguita dal metodo main () del modulo unittest o dal metodo run ().

Le seguenti sono le due funzioni principali per la creazione unittest.TestSuite istanze da file di testo e moduli con i doctests -

doctest.DocFileSuite ()

Viene utilizzato per convertire i test doctest da uno o più file di testo in un file unittest.TestSuite. Unittest.TestSuite restituito deve essere eseguito dal framework unittest ed esegue gli esempi interattivi in ​​ogni file. Se uno qualsiasi degli esempi in un file fallisce, lo unit test sintetizzato fallisce e afailureException viene sollevata un'eccezione che mostra il nome del file contenente il test e un numero di riga (a volte approssimativo).

doctest.DocTestSuite ()

Viene utilizzato per convertire i test doctest per un modulo in un file unittest.TestSuite.

Unittest.TestSuite restituito deve essere eseguito dal framework unittest ed esegue ogni doctest nel modulo. Se uno qualsiasi dei doctest fallisce, lo unit test sintetizzato fallisce e afailureException viene sollevata un'eccezione che mostra il nome del file contenente il test e un numero di riga (a volte approssimativo)

Sotto le coperte, DocTestSuite () crea un file unittest.TestSuite di istanze di doctest.DocTestCase e DocTestCase è una sottoclasse di unittest.TestCase.

Allo stesso modo, DocFileSuite () crea un unittest.TestSuite dalle istanze di doctest.DocFileCase e DocFileCase è una sottoclasse di DocTestCase.

Quindi entrambi i modi per creare un unittest.TestSuite eseguono istanze di DocTestCase. Quando esegui tu stesso le funzioni doctest, puoi controllare le opzioni doctest in uso direttamente, passando flag di opzione alle funzioni doctest.

Tuttavia, se stai scrivendo un framework unittest, unittest alla fine controlla quando e come vengono eseguiti i test. L'autore del framework in genere vuole controllare le opzioni di reporting di doctest (forse, ad esempio, specificato dalle opzioni della riga di comando), ma non c'è modo di passare le opzioni da unittest a doctest test runner.