automated-typo3-update/Documentation/source/extending.rst
Daniel Siepmann 8cb68ff6bb
TASK: Migrate / write documentation
* Add further information and sections, e.g. about contribution and
  extending.

Relates: #63
2017-04-13 10:54:32 +02:00

94 lines
3.1 KiB
ReStructuredText

.. _extending:
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.
.. _extending-sniffs:
Sniffs
------
Follow the official docs of `phpcs`_:
https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial#creating-the-sniff
The following resources might be helpful during working with ``phpcs``:
- https://secure.php.net/manual/en/tokens.php
- :file:`CodeSniffer/Tokens.php`
- :file:`CodeSniffer/File.php`
.. _extending-tests:
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 :file:`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
:file:`src/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff.php`, the following folder
has to exist: :file:`tests/Fixtures/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff/`.
.. _extending-tests-single:
Single test per sniff
---------------------
Inside of the folder at least a file :file:`InputFileForIssues.php` has to exist, containing PHP
code to use for the test. Also a file :file:`Expected.json` has to exist, with the json result of
calling ``phpcs`` with :file:`InputFileForIssues.php`.
Everything else is done out of the box.
If your sniff also implements fixable errors or warnings, you can further provide a
:file:`Expected.diff` which is generated by ``phpcbf``.
.. _extending-tests-multiple:
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 :file:`Arguments.php` in the folder.
This file returns an array:
.. code-block:: php
<?php
return [
'defaultVendor' => [],
'customVendor' => [
'runtime-set' => [
'vendor' => 'MyCustomVendor',
],
],
];
In the example above ``defaultVendor`` and ``customVendor` are subfolders containing the same
structure as documented for :ref:`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 :file:`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 :file:`InputFileForIssues.php` and
compare the result against the :file:`Expected.json`. Same for :file:`Expected.diff`. The existence
of :file:`Expected.diff` itself will trigger the test for ``phpcbf``.
.. _phpcs: https://github.com/squizlabs/PHP_CodeSniffer
.. _phpunit: https://phpunit.de/