Πώς να γράψετε και να χρησιμοποιήσετε το doctest για να γράψετε κώδικα δοκιμών σε docstrings στην Python.

Επιχείρηση

Η Python διαθέτει μια τυπική ενότητα doctest που ελέγχει τα περιεχόμενα ενός docstring, διευκολύνοντας τη συγγραφή παραδειγμάτων εισόδου και εξόδου στο docstring και καθιστώντας την τεκμηρίωση πιο κατανοητή.

Οι ακόλουθες πληροφορίες παρέχονται εδώ.

  • Ένα απλό παράδειγμα ελέγχου με το doctest
    • Εάν δεν υπάρχει σφάλμα
    • Εάν υπάρχει σφάλμα
  • Έλεγχος αποτελεσμάτων εξόδου με επιλογές και ορίσματα
    • -vΕπιλογή
    • verboseόρισμα (π.χ. συνάρτηση, πρόγραμμα, πρόγραμμα)
  • Εκτελέστε την ενότητα doctest από τη γραμμή εντολών
  • Συγγραφή δοκιμών σε ένα εξωτερικό αρχείο κειμένου
    • Πώς να γράψετε ένα αρχείο κειμένου
    • Καλείται από το αρχείο py
    • Άμεση εκτέλεση ενός αρχείου κειμένου

Ένα απλό παράδειγμα ελέγχου με το doctest

Ένα docstring είναι μια συμβολοσειρά που περικλείεται σε ένα από τα ακόλουθα: (1) το όνομα της συνάρτησης που πρόκειται να δοκιμαστεί, (2) το όνομα της συνάρτησης που πρόκειται να δοκιμαστεί και (3) η αναμενόμενη τιμή εξόδου στη διαδραστική λειτουργία της Python.

  • """
  • '''

Εάν δεν υπάρχει σφάλμα

Βεβαιωθείτε ότι ο κώδικας είναι σωστός στη συνάρτηση και στα περιεχόμενα του docstring.

def add(a, b):
    '''
    >>> add(1, 2)
    3
    >>> add(5, 10)
    15
    '''

    return a + b


if __name__ == '__main__':
    import doctest
    doctest.testmod()

Εκτελέστε αυτό το αρχείο.

$ python3 doctest_example.py

Εάν δεν υπάρχουν σφάλματα, δεν θα εξάγεται τίποτα.

if __name__ == '__main__'Αυτό σημαίνει «Εκτέλεση μεταγενέστερης επεξεργασίας μόνο όταν εκτελείται το αντίστοιχο αρχείο δέσμης ενεργειών από τη γραμμή εντολών.

Εάν υπάρχει σφάλμα

Αν δημιουργήσετε και εκτελέσετε τον ακόλουθο λανθασμένο κώδικα, θα εμφανιστεί σφάλμα.

def add(a, b):
    '''
    >>> add(1, 2)
    3
    >>> add(5, 10)
    10
    '''

    return a * b


if __name__ == '__main__':
    import doctest
    doctest.testmod()

$ python3 doctest_example_error.py
**********************************************************************
File "doctest_example_error.py", line 3, in __main__.add
Failed example:
    add(1, 2)
Expected:
    3
Got:
    2
**********************************************************************
File "doctest_example_error.py", line 5, in __main__.add
Failed example:
    add(5, 10)
Expected:
    10
Got:
    50
**********************************************************************
1 items had failures:
   2 of   2 in __main__.add
***Test Failed*** 2 failures.

Παρουσιάζεται ως εξής.

Αναμενόμενες τιμές εξόδου γραμμένες στο doctest.Expected
Πραγματική τιμή εξόδουGot

Έλεγχος αποτελεσμάτων εξόδου με επιλογές και ορίσματα

-vΕπιλογή

Αν θέλετε να εμφανίζονται τα αποτελέσματα εξόδου ακόμη και όταν δεν υπάρχουν σφάλματα, εκτελέστε την εντολή με την επιλογή -v στη γραμμή εντολών.

$ python3 doctest_example.py -v
Trying:
    add(1, 2)
Expecting:
    3
ok
Trying:
    add(5, 10)
Expecting:
    15
ok
1 items had no tests:
    __main__
1 items passed all tests:
   2 tests in __main__.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

verboseόρισμα (π.χ. συνάρτηση, πρόγραμμα, πρόγραμμα)

Αν θέλετε να εμφανίζονται πάντα τα αποτελέσματα εξόδου, καθορίστε το όρισμα verbose=True στην doctest.testmod() στο αρχείο py.

if __name__ == '__main__':
    import doctest
    doctest.testmod(verbose=True)

Τα αποτελέσματα εξόδου θα εμφανίζονται πάντα χωρίς την επιλογή -v κατά την εκτέλεση.

$ python3 doctest_example_verbose.py
Trying:
    add(1, 2)
Expecting:
    3
ok
Trying:
    add(5, 10)
Expecting:
    15
ok
1 items had no tests:
    __main__
1 items passed all tests:
   2 tests in __main__.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

Εκτελέστε την ενότητα doctest από τη γραμμή εντολών

if __name__ == '__main__'Αν θέλετε να κάνετε κάτι άλλο σε αυτό, μπορείτε να εκτελέσετε την ενότητα doctest απευθείας από τη γραμμή εντολών χωρίς να καλέσετε την doctest.testmod() στο αρχείο py.

Για παράδειγμα, στις ακόλουθες περιπτώσεις

def add(a, b):
    '''
    >>> add(1, 2)
    3
    >>> add(5, 10)
    15
    '''

    return a + b


if __name__ == '__main__':
    import sys
    result = add(int(sys.argv[1]), int(sys.argv[2]))
    print(result)

Μπορεί να λαμβάνει ορίσματα γραμμής εντολών και να εκτελεί τη διαδικασία ως συνήθως.

$ python3 doctest_example_without_import.py 3 4
7

Εάν εκτελέσετε το doctest ως δέσμη ενεργειών με την επιλογή -m, η δοκιμή θα εκτελεστεί έναντι της συνάρτησης στην οποία είναι γραμμένο το doctest. Αν θέλετε να εμφανίσετε τα αποτελέσματα της εξόδου, προσθέστε την επιλογή -v όπως προηγουμένως.

$ python3 -m doctest doctest_example_without_import.py

$ python3 -m doctest -v doctest_example_without_import.py
Trying:
    add(1, 2)
Expecting:
    3
ok
Trying:
    add(5, 10)
Expecting:
    15
ok
1 items had no tests:
    doctest_example_without_import
1 items passed all tests:
   2 tests in doctest_example_without_import.add
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

Συγγραφή δοκιμών σε ένα εξωτερικό αρχείο κειμένου

Μπορείτε επίσης να γράψετε τον κώδικα δοκιμής σε ένα εξωτερικό αρχείο κειμένου αντί για το docstring.

Πώς να γράψετε ένα αρχείο κειμένου

Γράψτε σε μορφή διαδραστικής λειτουργίας Python, όπως περιγράφεται στο docstring. Είναι απαραίτητη η εισαγωγή των συναρτήσεων που θα χρησιμοποιηθούν.

Αν θέλετε να τοποθετήσετε το αρχείο κειμένου στον ίδιο κατάλογο με το αρχείο .py που πρόκειται να δοκιμαστεί, απλά εισάγετε το ως εξής.

>>> from doctest_example import add
>>> add(1, 2)
3
>>> add(5, 10)
15

Καλείται από το αρχείο py

Καλέστε την doctest.testfile() σε ένα άλλο αρχείο .py για δοκιμές.

Καθορίστε τη διαδρομή του αρχείου κειμένου όπου γράφεται ο κώδικας δοκιμής ως όρισμα της doctest.testfile().

import doctest
doctest.testfile('doctest_text.txt')

Εκτελέστε αυτό το αρχείο py.

$ python3 doctest_example_testfile.py -v
Trying:
    from doctest_example import add
Expecting nothing
ok
Trying:
    add(1, 2)
Expecting:
    3
ok
Trying:
    add(5, 10)
Expecting:
    15
ok
1 items passed all tests:
   3 tests in doctest_text.txt
3 tests in 1 items.
3 passed and 0 failed.
Test passed.

Άμεση εκτέλεση ενός αρχείου κειμένου

Ακόμη και αν δεν έχετε το αρχείο py, μπορείτε να διαβάσετε το αρχείο κειμένου απευθείας από τη γραμμή εντολών και να εκτελέσετε τις δοκιμές.

Εκτελέστε την εντολή Python με την επιλογή -m για να εκτελέσετε το doctest ως δέσμη ενεργειών. Μπορείτε να καθορίσετε τη διαδρομή του αρχείου κειμένου ως όρισμα γραμμής εντολών.

$ python3 -m doctest -v doctest_text.txt
Trying:
    from doctest_example import add
Expecting nothing
ok
Trying:
    add(1, 2)
Expecting:
    3
ok
Trying:
    add(5, 10)
Expecting:
    15
ok
1 items passed all tests:
   3 tests in doctest_text.txt
3 tests in 1 items.
3 passed and 0 failed.
Test passed.
Copied title and URL