automated-typo3-update/Documentation/source/extending.rst

Extending

It's possible to extend the provided migrations.

Also adding tests is pretty easy and done by adding a folder with an input file and an file holding the expectations.

Sniffs

Follow the official docs of phpcs: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial#user-content-creating-the-sniff

The following resources might be helpful during working with phpcs:

• https://secure.php.net/manual/en/tokens.php
• CodeSniffer/Tokens.php
• CodeSniffer/File.php

Tests

We are using phpunit as testing framework.

Adding tests for sniffs is as easy as providing the same folder structure as for the sniff, just inside the tests/Fixtures folder. Instead of adding the sniff as a file, you have to provide a folder named like the sniff. E.g. you want to add a test for sniff src/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff.php, the following folder has to exist: tests/Fixtures/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff/.

Single test per sniff

Inside of the folder at least a file InputFileForIssues.php has to exist, containing PHP code to use for the test. Also a file Expected.json has to exist, with the json result of calling phpcs with InputFileForIssues.php.

Everything else is done out of the box.

If your sniff also implements fixable errors or warnings, you can further provide a Expected.diff which is generated by phpcbf.

Multiple tests per sniff

Also it's possible to provide multiple tests for a single sniff, e.g. with different cli arguments like options for the sniff. In that case you have to place a Arguments.php in the folder. This file returns an array:

<?php

return [
    'defaultVendor' => [],
    'customVendor' => [
        'runtime-set' => [
            'vendor' => 'MyCustomVendor',
        ],
    ],
];

In the example above defaultVendor and customVendor are subfolders containing the same structure as documented for extending-tests-single. This way it's possible to run multiple tests per sniff.

Also you can provide further cli arguments on a key -> value base. Where runtime-set is special, as it contains a sub array to provide multiple runtime sets.

How sniff tests are implemented

We just find all folders below tests/Fixtures/Standards/Typo3Update/Sniffs ending with Sniff and check the structure. They are provided to the test itself through a dataprovider in phpunit.

We then build the phpcs cli call and execute it against the InputFileForIssues.php and compare the result against the Expected.json. Same for Expected.diff. The existence of Expected.diff itself will trigger the test for phpcbf.