Aides
*****


DomQuery
--------
`Tester\DomQuery` est une classe qui étend `SimpleXMLElement` avec des méthodes qui facilitent le test du contenu HTML ou XML.

```php
# let's have an HTML document in $html that we load
$dom = Tester\DomQuery::fromHtml($html);

# we can test the presence of elements using CSS selectors
Assert::true($dom->has('form#registration'));
Assert::true($dom->has('input[name="username"]'));
Assert::true($dom->has('input[type="submit"]'));

# or select elements as array of DomQuery
$elems = $dom->find('input[data-autocomplete]');
```


FileMock
--------
`Tester\FileMock` émule des fichiers en mémoire pour vous aider à tester un code qui utilise des fonctions comme `fopen()`, `file_get_contents()` ou `parse_ini_file()`. Par exemple :

```php
# Tested class
class Logger
{
	public function __construct(
		private string $logFile,
	) {
	}

	public function log(string $message): void
	{
		file_put_contents($this->logFile, $message . "\n", FILE_APPEND);
	}
}

# New empty file
$file = Tester\FileMock::create('');

$logger = new Logger($file);
$logger->log('Login');
$logger->log('Logout');

# Created content testing
Assert::same("Login\nLogout\n", file_get_contents($file));
```


Assert::with() .[filter]
------------------------
Il ne s'agit pas d'une assertion, mais d'une aide pour tester les méthodes privées et les objets de propriété.

```php
class Entity
{
	private $enabled;
	// ...
}

$ent = new Entity;

Assert::with($ent, function () {
	Assert::true($this->enabled); // accessible en privé $ent->enabled
});
```


Helpers::purge() .[filter]
--------------------------
La méthode `purge()` crée le répertoire spécifié et, s'il existe déjà, supprime tout son contenu. Elle est pratique pour la création de répertoires temporaires. Par exemple, dans `tests/bootstrap.php`:

```php
@mkdir(__DIR__ . '/tmp');  # @ - directory may already exist

define('TempDir', __DIR__ . '/tmp/' . getmypid());
Tester\Helpers::purge(TempDir);
```


Environment::lock() .[filter]
-----------------------------
Les tests s'exécutent en parallèle. Parfois, nous n'avons pas besoin de faire se chevaucher l'exécution des tests. Typiquement, les tests de base de données doivent préparer le contenu de la base de données et rien ne doit les perturber pendant l'exécution du test. Dans ces cas, nous utilisons `Tester\Environment::lock($name, $dir)`:

```php
Tester\Environment::lock('database', __DIR__ . '/tmp');
```

Le premier argument est un nom de verrou. Le second est un chemin vers un répertoire pour sauvegarder le verrou. Le test qui acquiert le verrou s'exécute en premier. Les autres tests doivent attendre qu'il soit terminé.


Environment::bypassFinals() .[filter]
-------------------------------------
Les classes ou méthodes marquées comme `final` sont difficiles à tester. L'appel de `Tester\Environment::bypassFinals()` dans un début de test fait que les mots-clés `final` sont supprimés lors du chargement du code.

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

Tester\Environment::bypassFinals();

class MyClass extends NormallyFinalClass # <-- NormallyFinalClass n'est plus final
{
	// ...
}
```


Environment::setup() .[filter]
------------------------------
- améliore la lisibilité du dump d'erreur (coloration incluse), sinon, la trace de pile PHP par défaut est imprimée.
- permet de vérifier que les assertions ont été appelées dans le test, sinon les tests sans assertions (par exemple oubliées) passent aussi
- lance automatiquement le collecteur de couverture de code lorsque `--coverage` est utilisé (décrit plus tard)
- affiche le statut OK ou FAILURE à la fin du script.


Environment::setupFunctions() .[filter]{data-version:2.5}
---------------------------------------------------------
Crée les fonctions globales `test()`, `testException()`, `setUp()` et `tearDown()` dans lesquelles vous pouvez diviser les tests.

```php
test('test description', function () {
	Assert::same(123, foo());
	Assert::false(bar());
	// ...
});
```


Environment::VariableRunner .[filter]
-------------------------------------
Permet de savoir si le test a été exécuté directement ou via le Testeur.

```php
if (getenv(Tester\Environment::VariableRunner)) {
	# run by Tester
} else {
	# another way
}
```


Environment::VariableThread .[filter]
-------------------------------------
Tester exécute les tests en parallèle dans un nombre donné de threads. Nous trouverons un numéro de thread dans une variable Environmentale lorsque nous serons intéressés :

```php
echo "I'm running in a thread number " . getenv(Tester\Environment::VariableThread);
```