Annotations δοκιμών

Οι annotations καθορίζουν πώς θα χειριστεί τις δοκιμές ο εκτελεστής δοκιμών από τη γραμμή εντολών. Γράφονται στην αρχή του αρχείου με τη δοκιμή.

Στις annotations δεν λαμβάνεται υπόψη η διάκριση πεζών-κεφαλαίων. Επίσης, δεν έχουν καμία επίδραση εάν η δοκιμή εκτελεστεί χειροκίνητα ως ένα συνηθισμένο PHP script.

Παράδειγμα:

/**
 * TEST: Basic database query test.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 5.5
 */

require __DIR__ . '/../bootstrap.php';

TEST

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

@skip

Η δοκιμή παραλείπεται. Είναι χρήσιμο για την προσωρινή απενεργοποίηση δοκιμών.

@phpVersion

Η δοκιμή παραλείπεται εάν δεν εκτελείται με την αντίστοιχη έκδοση PHP. Την annotation την γράφουμε ως @phpVersion [operator] version. Τον τελεστή μπορούμε να τον παραλείψουμε, η προεπιλογή είναι >=. Παραδείγματα:

/**
 * @phpVersion 5.3.3
 * @phpVersion < 5.5
 * @phpVersion != 5.4.5
 */

@phpExtension

Η δοκιμή παραλείπεται εάν δεν έχουν φορτωθεί όλες οι αναφερόμενες επεκτάσεις PHP. Περισσότερες επεκτάσεις μπορούμε να αναφέρουμε σε μία annotation ή να την χρησιμοποιήσουμε πολλές φορές.

/**
 * @phpExtension pdo, pdo_pgsql, pdo_mysql
 * @phpExtension json
 */

@dataProvider

Αν θέλουμε να εκτελέσουμε το αρχείο δοκιμής πολλές φορές, αλλά με διαφορετικά δεδομένα εισόδου, αυτή η annotation είναι χρήσιμη. (Μην τη συγχέετε με την ομώνυμη annotation για το TestCase.)

Τη γράφουμε ως @dataProvider file.ini, η διαδρομή προς το αρχείο λαμβάνεται σχετικά με το αρχείο της δοκιμής. Η δοκιμή θα εκτελεστεί τόσες φορές όσες είναι οι ενότητες στο αρχείο INI. Ας υποθέσουμε το αρχείο INI databases.ini:

[mysql]
dsn = "mysql:host=127.0.0.1"
user = root
password = ******

[postgresql]
dsn = "pgsql:host=127.0.0.1;dbname=test"
user = postgres
password = ******

[sqlite]
dsn = "sqlite::memory:"

και στον ίδιο κατάλογο τη δοκιμή database.phpt:

/**
 * @dataProvider databases.ini
 */

$args = Tester\Environment::loadData();

Η δοκιμή θα εκτελεστεί τρεις φορές και το $args θα περιέχει πάντα τις τιμές από την ενότητα mysql, postgresql ή sqlite.

Υπάρχει ακόμα μια παραλλαγή, όπου γράφουμε την annotation με ερωτηματικό ως @dataProvider? file.ini. Σε αυτήν την περίπτωση, η δοκιμή παραλείπεται εάν το αρχείο INI δεν υπάρχει.

Με αυτό οι δυνατότητες της annotation δεν τελειώνουν. Μετά το όνομα του αρχείου INI μπορούμε να καθορίσουμε συνθήκες υπό τις οποίες θα εκτελεστεί η δοκιμή για τη δεδομένη ενότητα. Θα επεκτείνουμε το αρχείο INI:

[mysql]
dsn = "mysql:host=127.0.0.1"
user = root
password = ******

[postgresql 8.4]
dsn = "pgsql:host=127.0.0.1;dbname=test"
user = postgres
password = ******

[postgresql 9.1]
dsn = "pgsql:host=127.0.0.1;dbname=test;port=5433"
user = postgres
password = ******

[sqlite]
dsn = "sqlite::memory:"

και θα χρησιμοποιήσουμε την annotation με συνθήκη:

/**
 * @dataProvider  databases.ini  postgresql, >=9.0
 */

Η δοκιμή θα εκτελεστεί μόνο μία φορά και αυτό για την ενότητα postgresql 9.1. Οι υπόλοιπες ενότητες δεν περνούν από το φίλτρο της συνθήκης.

Παρόμοια, αντί για αρχείο INI μπορούμε να παραπέμψουμε σε ένα PHP script. Αυτό πρέπει να επιστρέψει έναν πίνακα ή Traversable. Αρχείο databases.php:

return [
	'postgresql 8.4' => [
		'dsn' => '...',
		'user' => '...',
	],

	'postgresql 9.1' => [
		'dsn' => '...',
		'user' => '...',
	],
];

@multiple

Γράφουμε ως @multiple N, όπου N είναι ένας ακέραιος αριθμός. Η δοκιμή θα εκτελεστεί ακριβώς N φορές.

@testCase

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

@exitCode

Γράφουμε ως @exitCode N, όπου N είναι ο κωδικός επιστροφής της εκτελεσμένης δοκιμής. Εάν στη δοκιμή καλείται για παράδειγμα exit(10), την annotation την γράφουμε ως @exitCode 10 και εάν η δοκιμή τελειώσει με διαφορετικό κωδικό, θεωρείται αποτυχία. Εάν δεν αναφέρουμε την annotation, επαληθεύεται ο κωδικός επιστροφής 0 (μηδέν).

@httpCode

Η annotation εφαρμόζεται μόνο εάν το PHP binary είναι CGI. Διαφορετικά αγνοείται. Γράφουμε ως @httpCode NNN όπου NNN είναι ο αναμενόμενος κωδικός HTTP. Εάν δεν αναφέρουμε την annotation, επαληθεύεται ο κωδικός HTTP 200. Εάν το NNN το γράψουμε ως συμβολοσειρά που αξιολογείται σε μηδέν, για παράδειγμα any, ο κωδικός HTTP δεν επαληθεύεται.

@outputMatch και @outputMatchFile

Η λειτουργία των annotations είναι πανομοιότυπη με τις assertions Assert::match() και Assert::matchFile(). Το πρότυπο (pattern) όμως αναζητείται στο κείμενο που η δοκιμή έστειλε στην τυπική της έξοδο. Βρίσκει εφαρμογή εάν υποθέτουμε ότι η δοκιμή θα τελειώσει με fatal error και χρειαζόμαστε να επαληθεύσουμε την έξοδό της.

@phpIni

Για τη δοκιμή ορίζει τιμές διαμόρφωσης INI. Γράφουμε για παράδειγμα ως @phpIni precision=20 και λειτουργεί το ίδιο σαν να είχαμε δώσει την τιμή από τη γραμμή εντολών μέσω της παραμέτρου -d precision=20.