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

Features

Sniffs do not always add errors or warnings in our standard, instead for more flexibility, we use them to find specific "tokens", e.g. class names. We then attach so called Features to sniffs to work on that token.

E.g. we deliver the Feature LegacyClassnameFeature which will check whether a given class name is legacy and should be replaced. As class names may occur in many places like type hints or php doc blocks, the sniffs will detect the class names and the feature will work on them.

Features can be attached to the sniffs. A feature has to implement the FeatureInterface and will work on tokens found by sniffs.

To attach a Feature to Sniffs, provide a yaml-configuration, see configuration-features.

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/.

Also for convenience add a test class with following content:

<?php

namespace Typo3Update\Tests\Sniffs\Removed;

/*
* Copyright (C) 2017  Daniel Siepmann <coding@daniel-siepmann.de>
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
* 02110-1301, USA.
*/

use Typo3Update\Tests\SniffsTest;

class TypoScriptSniffTest extends SniffsTest
{
}

Place it accordingly to namespace. Adjust namespace and class name. No code is needed, everything is done in SniffsTest. But this enables you to add --filter to phpunit to run just one test. Also IDEs support to run the single test file. This makes development much faster and failing tests more helpfull as they contain the class name.

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.

5.3 KiB Raw Blame History