Σημειώσεις δοκιμής
******************

.[perex]
Οι επισημειώσεις καθορίζουν τον τρόπο με τον οποίο οι δοκιμές θα αντιμετωπίζονται από τον [εκτελεστή δοκιμών γραμμής εντολών |running-tests]. Γράφονται στην αρχή του αρχείου δοκιμής.

Οι σημειώσεις δεν επηρεάζουν την πεζότητα. Επίσης, δεν έχουν καμία επίδραση αν η δοκιμή εκτελεστεί χειροκίνητα ως κανονικό σενάριο PHP.

Παράδειγμα:

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

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


TEST .[filter]
--------------
Στην πραγματικότητα δεν πρόκειται για σχολιασμό. Ορίζει μόνο τον τίτλο της δοκιμής που εκτυπώνεται στην αποτυχία ή στα αρχεία καταγραφής.


@skip .[filter]
---------------
Η δοκιμή παραλείπεται. Είναι χρήσιμο για την προσωρινή απενεργοποίηση δοκιμών.


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

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


@phpExtension .[filter]
-----------------------
Η δοκιμή παραλείπεται εάν δεν έχουν φορτωθεί όλες οι αναφερόμενες επεκτάσεις PHP. Πολλαπλές επεκτάσεις μπορούν να γραφτούν σε ένα μόνο σχόλιο ή μπορούμε να χρησιμοποιήσουμε το σχόλιο πολλές φορές.

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


@dataProvider .[filter]
-----------------------
Αυτός ο σχολιασμός ταιριάζει όταν θέλουμε να εκτελέσουμε τη δοκιμή πολλές φορές αλλά με διαφορετικά δεδομένα. (Δεν πρέπει να συγχέεται με τον ομώνυμο σχολιασμό για [το TestCase |TestCase#dataProvider]).

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

```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` στον ίδιο κατάλογο:

```php
/**
 * @dataProvider databases.ini
 */

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

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

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

Οι δυνατότητες σχολιασμού δεν έχουν αναφερθεί ακόμη όλες. Μπορούμε να γράψουμε συνθήκες μετά το αρχείο INI. Η δοκιμή εκτελείται για το συγκεκριμένο τμήμα μόνο εάν όλες οι συνθήκες ταιριάζουν. Ας επεκτείνουμε το αρχείο 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:"
```

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

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

Η δοκιμή εκτελείται μόνο μία φορά για το τμήμα `postgresql 9.1`. Τα άλλα τμήματα δεν ταιριάζουν με τις συνθήκες.

Ομοίως, μπορούμε να περάσουμε τη διαδρομή σε ένα PHP script αντί για INI. Πρέπει να επιστρέφει array ή Traversable. Αρχείο `databases.php`:

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

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


@multiple .[filter]
-------------------
Το γράφουμε ως `@multiple N` όπου το "Ν" είναι ένας ακέραιος αριθμός. Η δοκιμή εκτελείται ακριβώς N-φορές.


@testCase .[filter]
-------------------
Ο σχολιασμός δεν έχει παραμέτρους. Τη χρησιμοποιούμε όταν γράφουμε μια δοκιμή ως κλάσεις [TestCase |TestCase]. Σε αυτή την περίπτωση, ο test runner της γραμμής εντολών θα εκτελέσει τις επιμέρους μεθόδους σε ξεχωριστές διεργασίες και παράλληλα σε πολλαπλά νήματα. Αυτό μπορεί να επιταχύνει σημαντικά ολόκληρη τη διαδικασία δοκιμής.


@exitCode .[filter]
-------------------
Το γράφουμε ως `@exitCode N` όπου το `N` is the exit code of the test. For example if `exit(10)` καλείται στη δοκιμή, γράφουμε τον σχολιασμό ως `@exitCode 10`. Θεωρείται ότι αποτυγχάνει αν η δοκιμή τελειώνει με διαφορετικό κωδικό. Ο κωδικός εξόδου 0 (μηδέν) επαληθεύεται αν παραλείψουμε το σχόλιο


@httpCode .[filter]
-------------------
Η σημείωση αξιολογείται μόνο αν το δυαδικό PHP είναι CGI. Διαφορετικά αγνοείται. Το γράφουμε ως `@httpCode NNN` όπου `NNN` είναι ο αναμενόμενος κωδικός HTTP. Ο κωδικός HTTP 200 επαληθεύεται αν παραλείψουμε το σχόλιο. Εάν γράψουμε το `NNN` ως συμβολοσειρά που αξιολογείται ως μηδέν, για παράδειγμα `any`, ο κωδικός HTTP δεν ελέγχεται καθόλου.


@outputMatch a @outputMatchFile .[filter]
-----------------------------------------
Η συμπεριφορά των σχολίων είναι σύμφωνη με τους ισχυρισμούς `Assert::match()` και `Assert::matchFile()`. Αλλά το μοτίβο εντοπίζεται στην τυπική έξοδο της δοκιμής. Μια κατάλληλη περίπτωση χρήσης είναι όταν υποθέτουμε ότι η δοκιμή τερματίζεται με μοιραίο σφάλμα και πρέπει να επαληθεύσουμε την έξοδό της.


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