Clases auxiliares

HttpAssert

La clase Tester\HttpAssert ofrece herramientas para probar servidores HTTP. Le permite realizar con facilidad peticiones HTTP y verificar los códigos de estado, las cabeceras y el contenido del cuerpo de la respuesta con una interfaz fluida.

# Petición HTTP básica y verificación de la respuesta
$response = Tester\HttpAssert::fetch('https://example.com/api/users');
$response
	->expectCode(200)
	->expectHeader('Content-Type', contains: 'json')
	->expectBody(contains: 'users');

El método fetch() crea de forma predeterminada una petición GET, pero todos los parámetros se pueden personalizar:

HttpAssert::fetch(
	'https://api.example.com/users',
	method: 'POST',
	headers: [
		'Authorization' => 'Bearer token123',  # array asociativo
		'Accept: application/json',            # o en formato de cadena
	],
	cookies: ['session' => 'abc123'],
	follow: false,                             # no seguir las redirecciones
	body: '{"name": "John"}'
)
	->expectCode(201);

Los códigos de estado se pueden verificar con los métodos expectCode() y denyCode(). Puede pasar un número concreto o una función de validación:

$response
	->expectCode(200)                           # código exacto
	->expectCode(fn($code) => $code < 400)      # validación propia
	->denyCode(404)                             # no debe ser 404
	->denyCode(fn($code) => $code >= 500);      # no debe ser un error del servidor

Para verificar las cabeceras use los métodos expectHeader() y denyHeader(). Puede comprobar si una cabecera existe, verificar su valor exacto o casar parte de su contenido:

$response
	->expectHeader('Content-Type')                     # la cabecera debe existir
	->expectHeader('Content-Type', 'application/json') # valor exacto
	->expectHeader('Content-Type', contains: 'json')   # contiene el texto
	->expectHeader('Server', matches: 'nginx %a%')     # encaja con el patrón
	->denyHeader('X-Powered-By')                       # la cabecera no debe existir
	->denyHeader('X-Debug', contains: 'sensitive')     # no debe contener el texto
	->denyHeader('X-Debug', matches: '~debug~i');      # no debe encajar con el patrón

La verificación del cuerpo de la respuesta funciona de forma parecida con los métodos expectBody() y denyBody():

$response
	->expectBody('OK')                              # valor exacto
	->expectBody(contains: '"status": "success"')   # contiene un fragmento JSON
	->expectBody(matches: '%A% hello %A%')          # encaja con el patrón
	->expectBody(fn($body) => json_decode($body) !== null) # validación propia
	->denyBody('Error occurred')                    # no debe tener ese valor exacto
	->denyBody(contains: 'error')                   # no debe contener el texto
	->denyBody(matches: '~exception|fatal~i');      # no debe encajar con el patrón

El parámetro follow controla cómo trata HttpAssert las redirecciones HTTP:

# Probar la redirección sin seguirla (predeterminado)
HttpAssert::fetch('https://example.com/redirect', follow: false)
	->expectCode(301)
	->expectHeader('Location', 'https://example.com/new-url');

# Seguir todas las redirecciones hasta la respuesta final
HttpAssert::fetch('https://example.com/redirect', follow: true)
	->expectCode(200)
	->expectBody(contains: 'final content');

DomQuery

Tester\DomQuery es una clase que extiende SimpleXMLElement y permite consultar con facilidad HTML o XML mediante selectores CSS.

# crea DomQuery a partir de una cadena HTML
$dom = Tester\DomQuery::fromHtml('
	<article class="post">
		<h1>Title</h1>
		<div class="content">Text</div>
	</article>
');

# comprueba la existencia del elemento con selectores CSS
Assert::true($dom->has('article.post'));
Assert::true($dom->has('h1'));

# encuentra los elementos como array de objetos DomQuery
$headings = $dom->find('h1');
Assert::same('Title', (string) $headings[0]);

# comprueba si el elemento encaja con el selector (desde la versión 2.5.3)
$content = $dom->find('.content')[0];
Assert::true($content->matches('div'));
Assert::false($content->matches('p'));

# encuentra el antecesor más cercano que encaje con el selector (desde 2.5.5)
$article = $content->closest('.post');
Assert::true($article->matches('article'));

Para los documentos XML use el método fromXml():

$dom = Tester\DomQuery::fromXml('<catalog><item>First</item></catalog>');
Assert::true($dom->has('item'));

FileMock

Tester\FileMock emula archivos en memoria y facilita probar código que usa funciones como fopen(), file_get_contents(), parse_ini_file() y similares. Ejemplo de uso:

# Clase probada
class Logger
{
	public function __construct(
		private string $logFile,
	) {
	}

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

# Archivo nuevo vacío
$file = Tester\FileMock::create('');

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

# Prueba el contenido creado
Assert::same("Login\nLogout\n", file_get_contents($file));

El segundo parámetro opcional $extension establece la extensión del archivo en la URL generada, lo que viene bien cuando el código probado decide en función de ella:

$file = Tester\FileMock::create('{"key": "value"}', 'json');

Assert::with()

Esto no es una aserción, sino un ayudante para probar los métodos y las propiedades privadas de los objetos.

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

$ent = new Entity;

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

Helpers::purge()

El método purge() crea el directorio indicado y, si ya existe, borra todo su contenido. Es útil para crear un directorio temporal. Por ejemplo, en tests/bootstrap.php:

@mkdir(__DIR__ . '/tmp');  # @ - el directorio puede existir ya

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

Environment::lock()

Las pruebas se ejecutan en paralelo. A veces, sin embargo, necesitamos que sus ejecuciones no se solapen. Normalmente, las pruebas de base de datos requieren preparar el contenido de la base de datos y asegurarse de que ninguna otra prueba interfiere con ella durante su ejecución. En esas pruebas usamos Tester\Environment::lock($name, $dir):

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

El primer parámetro es el nombre del bloqueo y el segundo, la ruta al directorio donde se guarda. La prueba que adquiere el bloqueo primero continúa; las demás tienen que esperar a que termine.

Environment::bypassFinals()

Las clases o los métodos marcados como final son difíciles de probar. Llamar a Tester\Environment::bypassFinals() al principio de una prueba hace que las palabras clave final se omitan al cargar el código.

require __DIR__ . '/bootstrap.php';

Tester\Environment::bypassFinals();

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

Environment::setup()

• mejora la legibilidad de los volcados de error (incluido el coloreado); si no, se imprime el stack trace predeterminado de PHP
• activa la comprobación de que en la prueba se llamó a alguna aserción; si no, las pruebas sin aserciones (p. ej. olvidadas) también pasan
• empieza a recoger automáticamente información sobre el código ejecutado (cuando se usa --coverage) (se describe más adelante)
• imprime al final del script el estado OK o FAILURE

Environment::setupFunctions()

Crea las funciones globales test(), testException(), testNoError(), setUp() y tearDown(), con las que puede estructurar sus pruebas.

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

Environment::VariableRunner

Permite averiguar si la prueba se ejecutó directamente o mediante Tester.

if (getenv(Tester\Environment::VariableRunner)) {
	# ejecutado por Tester
} else {
	# ejecutado de otra manera
}

Environment::VariableThread

Tester ejecuta las pruebas en paralelo en el número de hilos indicado. Si nos interesa el número del hilo, lo averiguamos con la variable de entorno:

echo "Running in thread number " . getenv(Tester\Environment::VariableThread);