Automatické testování zdrojového kódu v dokumentaci

Myiyk

V dokumentaci se nachází kód, který je nefunkční vzhledem k aktuální verzi nette. Nikomu se pochopitelně nechce tento kód hledat, protože to je velmi pracné.

Tak mě napadlo, že by se testy psaly do dokumentace přímo.

Testy by byly celkem primitivní, u Latte by se testovalo, zda vygeneruje požadovaný kód. U routeru, zda udělá správnou routu. Testem je i to, že daný Latte kód lze zkompilovat a tedy, že všechny použité makra existují a nejsou deprecated.

Taková jest teorie.

V praxi by se musela udělat nějaká syntaxe pro texy, aby šlo psát komentáře. (což aktuálně nejde)
A musel by se napsat spouštěč testů, který vyhodnotí v jakém prostředí (latte / čisté php / presenter / komponenta) kód spustit.

Myiyk

Prakticky vzato již teď by šlo nechat zkompilovat všechny Latte kódy z dokumentace.

Felix

Zni to urcite zajimave. Akorat si to zatim nedokazu predstavit jak to bude v praxi.

Myiyk

Jednoduchý příklad: v dokumentaci stránkování je kód

$paginator = new Nette\Utils\Paginator;
$paginator->setItemCount(356); // celkový počet položek (např. článků)
$paginator->setItemsPerPage(30); // počet položek na stránce
$paginator->setPage(1); // číslo aktuální stránky, číslováno od 1

test bude spočívat v tom, že se to pustí v php. Tím se ověří že existuje ta třída i metody.
Když bude BC break, test na tom spadne.

Složitější příklad: z dokumentace n:class
aktuální kód

<ul>
    {foreach $data as $item}
    <li n:class="$iterator->odd ? alt, $iterator->last ? last">{$item}</li>
    {/foreach}
</ul>

kód s testem

### before-test
$data = ['alfa', 'beta', 'gama'];
### end
<ul>
    {foreach $data as $item}
    <li n:class="$iterator->odd ? alt, $iterator->last ? last">{$item}</li>
    {/foreach}
</ul>
### assert-equals
<ul>
	<li class="alt">alfa</li>
	<li>beta</li>
	<li class="alt last">gama</li>
</ul>
### end

Asi nemá smysl testovat funkcionalitu, protože ta už je otestována v samotném Latte, ale testovat hlavně že to lze zkompilovat. Vlastně by tam ani ten assert nemusel být. Jen nastavit výchozí hodnoty, aby proběhl všechen kód.

Editoval Myiyk (23. 5. 2016 17:23)

David Grudl

Myslím, že úplně stačí testovat, že to jde zkompilovat. Nevěřím tomu, že by někdo psal do dokumentace i testy.

Myiyk

PHP kód se bude muset spustit, nelze jej zkompilovat.
U Latte si nejsem jist.

Jde mi o to, jestli se budou muset inicializovat použité proměnné, aby to nespadlo, že proměnná neexistuje.

David Grudl

Při zavolání $latte->compile() se proměnné nepoužívají.

Myiyk

Sestrojil jsem základní verzi https://github.com/…/tree/tester
Testuje to pouze Latte kód.

Výstup pro dokumentaci 2.3 je:

Problem in file /Library/WebServer/Documents/nette-dokumentace/doc/cs/forms.texy:975
Missing {/form} in mock://16......latte:6
Problem in file /Library/WebServer/Documents/nette-dokumentace/doc/cs/troubleshooting.texy:22
Unknown macro {je} in mock://49......latte:1
Problem in file /Library/WebServer/Documents/nette-dokumentace/doc/en/forms.texy:995
Missing {/form} in mock://69......latte:6
Problem in file /Library/WebServer/Documents/nette-dokumentace/doc/en/troubleshooting.texy:22
Unknown macro {is}, did you mean {if}? in mock://104......latte:1

Což jsou všechno úmyslné chyby, takže to je v pořádku.