Klasy pomocnicze
****************


DomQuery
--------
`Tester\DomQuery` to klasa rozszerzająca `SimpleXMLElement` o łatwe wyszukiwanie w HTML lub XML za pomocą selektorów CSS.

```php
# utworzenie DomQuery z ciągu HTML
$dom = Tester\DomQuery::fromHtml('
	<article class="post">
		<h1>Title</h1>
		<div class="content">Text</div>
	</article>
');

# test istnienia elementów za pomocą selektorów CSS
Assert::true($dom->has('article.post'));
Assert::true($dom->has('h1'));

# znalezienie elementów jako tablica obiektów DomQuery
$headings = $dom->find('h1');
Assert::same('Title', (string) $headings[0]);

# test, czy element odpowiada selektorowi (od wersji 2.5.3)
$content = $dom->find('.content')[0];
Assert::true($content->matches('div'));
Assert::false($content->matches('p'));

# znalezienie najbliższego przodka odpowiadającego selektorowi (od 2.5.5)
$article = $content->closest('.post');
Assert::true($article->matches('article'));
```


FileMock
--------
`Tester\FileMock` emuluje w pamięci pliki i ułatwia w ten sposób testowanie kodu, który używa funkcji `fopen()`, `file_get_contents()`, `parse_ini_file()` i podobnych. Przykład użycia:

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

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

# Nowy pusty plik
$file = Tester\FileMock::create('');

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

# Testujemy utworzoną zawartość
Assert::same("Login\nLogout\n", file_get_contents($file));
```


Assert::with() .[filter]
------------------------
Nie jest to asercja, ale pomocnik do testowania prywatnych metod i właściwości obiektów.

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

$ent = new Entity;

Assert::with($ent, function () {
	Assert::true($this->enabled); // udostępniona prywatna $ent->enabled
});
```


Helpers::purge() .[filter]
--------------------------
Metoda `purge()` tworzy podany katalog, a jeśli już istnieje, usuwa całą jego zawartość. Przydaje się do tworzenia tymczasowego katalogu. Na przykład w `tests/bootstrap.php`:

```php
@mkdir(__DIR__ . '/tmp');  # @ - katalog już może istnieć

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


Environment::lock() .[filter]
-----------------------------
Testy uruchamiane są równolegle. Czasami jednak potrzebujemy, aby przebieg testów się nie nakładał. Typowo w testach bazodanowych konieczne jest, aby test przygotował zawartość bazy danych, a inny test w czasie jego trwania nie ingerował w bazę danych. W tych testach użyjemy `Tester\Environment::lock($name, $dir)`:

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

Pierwszy parametr to nazwa blokady, drugi to ścieżka do katalogu do przechowywania blokady. Test, który uzyska blokadę jako pierwszy, zostanie wykonany, pozostałe testy muszą poczekać na jego zakończenie.


Environment::bypassFinals() .[filter]
-------------------------------------
Klasy lub metody oznaczone jako `final` są trudne do testowania. Wywołanie `Tester\Environment::bypassFinals()` na początku testu powoduje, że słowa kluczowe `final` podczas wczytywania kodu są pomijane.

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

Tester\Environment::bypassFinals();

class MyClass extends NormallyFinalClass  # <-- NormallyFinalClass już nie jest final
{
	// ...
}
```


Environment::setup() .[filter]
------------------------------
- poprawia czytelność wypisu błędów (włącznie z kolorowaniem), inaczej jest wypisany domyślny PHP stack trace
- włącza kontrolę, czy w teście zostały wywołane asercje, inaczej test bez asercji (na przykład zapomnianych) przejdzie również
- przy użyciu `--coverage` uruchamia automatycznie zbieranie informacji o uruchomionym kodzie (opisane dalej)
- wypisuje stan OK lub FAILURE na końcu skryptu


Environment::setupFunctions() .[filter]{data-version:2.5}
---------------------------------------------------------
Tworzy globalne funkcje `test()`, `testException()`, `setUp()` i `tearDown()`, w które możesz dzielić testy.

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


Environment::VariableRunner .[filter]
-------------------------------------
Umożliwia sprawdzenie, czy test został uruchomiony bezpośrednio, czy za pomocą Testera.

```php
if (getenv(Tester\Environment::VariableRunner)) {
	# uruchomiono Testerem
} else {
	# uruchomiono inaczej
}
```


Environment::VariableThread .[filter]
-------------------------------------
Tester uruchamia testy równolegle w podanej liczbie wątków. Jeśli interesuje nas numer wątku, dowiemy się go ze zmiennej środowiskowej:

```php
echo "Działam w wątku numer " . getenv(Tester\Environment::VariableThread);
```