Ayudantes
*********


DomQuery
--------
`Tester\DomQuery` es una clase que amplía `SimpleXMLElement` con métodos que facilitan la comprobación de contenidos HTML o XML.

```php
# en $html es una cadena con el documento HTML, en $dom obtenemos el elemento raíz
$dom = Tester\DomQuery::fromHtml($html);

# podemos comprobar la presencia de elementos utilizando selectores CSS
Assert::true($dom->has('form#registration'));
Assert::true($dom->has('input[name="username"]'));
Assert::true($dom->has('input[type="submit"]'));

# o seleccionar elementos como array de DomQuery
$elems = $dom->find('input[data-autocomplete]');

# o verificar que el elemento coincide con el selector (a partir de la versión 2.5.3)
Assert::true($elems[0]->matches('[type="submit"]'));
```


FileMock
--------
`Tester\FileMock` emula archivos en memoria para ayudarle a probar un código que utilice funciones como `fopen()`, `file_get_contents()` o `parse_ini_file()`. Por ejemplo

```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]
------------------------
Esto no es una aserción, sino un ayudante para probar métodos privados y objetos de propiedad.

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

$ent = new Entity;

Assert::with($ent, function () {
	Assert::true($this->habilitado); // accesible privado $ent->habilitado
});
```


Helpers::purge() .[filter]
--------------------------
El método `purge()` crea el directorio especificado y, si ya existe, borra todo su contenido. Es útil para la creación de directorios temporales. Por ejemplo en `tests/bootstrap.php`:

```php
@mkdir(__DIR__ . '/tmp'); # @ - es posible que el directorio ya exista

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


Environment::lock() .[filter]
-----------------------------
Las pruebas se ejecutan en paralelo. A veces necesitamos no solapar la ejecución de las pruebas. Típicamente las pruebas de base de datos necesitan preparar el contenido de la base de datos y necesitan que nada las perturbe durante el tiempo de ejecución de la prueba. En estos casos utilizamos `Tester\Environment::lock($name, $dir)`:

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

El primer argumento es un nombre de bloqueo. El segundo es una ruta al directorio para guardar el bloqueo. La prueba que adquiere el bloqueo se ejecuta primero. Las demás pruebas deben esperar a que se complete.


Environment::bypassFinals() .[filter]
-------------------------------------
Las clases o métodos marcados como `final` son difíciles de probar. Llamar a `Tester\Environment::bypassFinals()` en un inicio de prueba provoca que las palabras clave `final` sean eliminadas durante la carga del código.

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

Tester\Environment::bypassFinals();

class MyClass extends NormallyFinalClass # <-- NormallyFinalClass ya no es final
{
	// ...
}
```


Environment::setup() .[filter]
------------------------------
- mejora la legibilidad del volcado de errores (coloreado incluido), de lo contrario, se imprime el seguimiento de pila de PHP por defecto
- permite comprobar que las aserciones han sido invocadas en la prueba, de lo contrario, las pruebas sin (p.e. olvidadas) aserciones pasan también
- inicia automáticamente el colector de cobertura de código cuando se utiliza `--coverage` (descrito más adelante)
- imprime el estado OK o FAILURE al final del script


Environment::setupFunctions() .[filter]{data-version:2.5}
---------------------------------------------------------
Crea las funciones globales `test()`, `testException()`, `setUp()` y `tearDown()` en las que se pueden dividir las pruebas.

```php
test('descripción de la prueba', function () {
	Assert::same(123, foo());
	Assert::false(bar());
	// ...
});
```


Environment::VariableRunner .[filter]
-------------------------------------
Le permite averiguar si la prueba se ejecutó directamente o a través del Comprobador.

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


Environment::VariableThread .[filter]
-------------------------------------
Tester ejecuta pruebas en paralelo en un número determinado de hilos. Encontraremos un número de hilos en una variable de entorno cuando nos interese:

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