mirror of
https://github.com/FriendsOfTYPO3/tea.git
synced 2024-11-10 00:56:12 +01:00
236 lines
11 KiB
Markdown
236 lines
11 KiB
Markdown
# Example TYPO3 extension for code quality checks and automated tests
|
|
|
|
[](https://github.com/TYPO3-Documentation/tea/actions)
|
|
[](https://gitlab.typo3.org/qa/example-extension/-/pipelines)
|
|
[](https://packagist.org/packages/ttn/tea)
|
|
[](https://packagist.org/packages/ttn/tea)
|
|
[](https://packagist.org/packages/ttn/tea)
|
|
[](https://packagist.org/packages/ttn/tea)
|
|
[](CODE_OF_CONDUCT.md)
|
|
|
|
## What is this all about?
|
|
|
|
This Extbase/Fluid-based TYPO3 extension is an example showcase for best
|
|
practices in continuous integration, automated code checks and unit and
|
|
functional testing.
|
|
|
|
You can also use this extension to manage your collection of delicious teas.
|
|
|
|
## Extension manual
|
|
|
|
The rendered extension manual is available
|
|
[on docs.typo3.org](https://docs.typo3.org/p/ttn/tea/master/en-us/).
|
|
|
|
## Used testing framework and approach to TYPO3 version support
|
|
|
|
Extensions usually needs to support two LTS versions of TYPO3 in parallel
|
|
(assuming that they should support all currently supported TYPO3 LTS versions).
|
|
To achieve this, there are two different approaches, which also affect the
|
|
choice of a testing framework for unit and functional tests:
|
|
|
|
### Approach 1: single branch with multi-version support
|
|
|
|
With this approach, there is one main branch that gets new features. It needs to
|
|
support two TYPO3 LTS versions in parallel.
|
|
|
|
The downside is that this slightly increases code complexity (as
|
|
version-dependent code switches might be necessary). The upside is that there
|
|
is only one branch to maintain, which makes adding new features (and all other
|
|
code changes) a lot less of a hassle.
|
|
|
|
As the [TYPO3 testing framework](https://github.com/TYPO3/testing-framework)
|
|
supports only one TYPO3 LTS version at a time, you will need to use the
|
|
[Nimut testing framework](https://github.com/Nimut/testing-framework) instead.
|
|
This testing framework can support multiple TYPO3 versions at a time, and
|
|
it provides version-independent abstractions for testing.
|
|
|
|
(This is the approach that we have chosen for this extension as we do not want
|
|
to maintain two branches in parallel.)
|
|
|
|
### Approach 2: multiple branches for each TYPO3 version
|
|
|
|
With this approach, there is are two main branches that get new features in
|
|
parallel. Each branch supports exactly one TYPO3 LTS version.
|
|
|
|
The upside is that this slightly decreases code complexity (as
|
|
version-dependent code switches are not necessary). The downside is that there
|
|
are two branches to maintain, which makes adding new features (and all other
|
|
code changes) more of a hassle.
|
|
|
|
For this approach, the
|
|
[TYPO3 testing framework](https://github.com/TYPO3/testing-framework) (which
|
|
supports only one TYPO3 LTS version at a time) will work just fine.
|
|
|
|
## Working locally or Docker-based with ddev
|
|
|
|
You can run the automated tests and code quality checks either locally (with a
|
|
local PHP, Composer and database), or you can use
|
|
[ddev](https://github.com/drud/ddev) for a Docker-based setup.
|
|
|
|
## Composer, PHIVE, GitHub Actions and GitLab CI
|
|
|
|
### Development tools: Composer, PHIVE and dependency hell
|
|
|
|
Most development tools (e.g., PHP_CodeSniffer) are installed with
|
|
[PHIVE](https://phar.io/), not with Composer. PHIVE packages each tool with all
|
|
its dependencies as a separate PHAR. This helps avoid dependency hell (which
|
|
means that you cannot install or upgrade some tool as the tool's dependencies
|
|
conflict with the dependencies on another library). It also allows running
|
|
versions of tools that require a PHP version that is higher than the lowest
|
|
allowed PHP version for this project.
|
|
|
|
Some tools are not available via PHIVE, e.g., the Nimut testing framework or
|
|
the JSON linter. For these tools, we keep using Composer for the time being.
|
|
|
|
### Running the code quality checks locally and in a CI environment
|
|
|
|
As an example, this extension provides several redundant ways to run the code
|
|
quality checks. (Running the unit and functional tests is a bit different.)
|
|
You can copy the corresponding configuration depending on which Git hosting
|
|
service and which CI platform you plan to use and whether you would like to run
|
|
the code quality checks locally:
|
|
|
|
#### GitHub Actions
|
|
|
|
This extension has two code-checking workflows for
|
|
[GitHub Actions](https://github.com/TYPO3-Documentation/tea/actions):
|
|
|
|
- [one that completely relies on predefined actions](.github/workflows/ci.yml):
|
|
This workflow does not need the development tools to be installed via PHIVE.
|
|
Use this workflow if you only want to run the code quality checks in GitHub
|
|
Actions, but not locally.
|
|
|
|
- [one that uses the PHIVE-installed tools](.github/workflows/ci-composer-scripts.yml):
|
|
This workflow uses the development tools installed via PHIVE and calls them
|
|
using the provided Composer scripts. Use this workflow if want to run the code
|
|
quality checks locally as well as in GitHub Actions.
|
|
|
|
#### GitLab CI
|
|
|
|
This extension also provides [configuration](.gitlab/pipeline/.gitlab-ci.yml)
|
|
for [GitLab CI](https://gitlab.typo3.org/qa/example-extension/-/pipelines).
|
|
|
|
## Composer scripts
|
|
|
|
For most development-related tasks, this extension provides Composer scripts.
|
|
If you are working locally, you can run them using `composer <scriptname>`. If
|
|
you are working with ddev, you can run them with `ddev composer <scriptname>`.
|
|
(You do not need to start or build the containers for this as this happens
|
|
automatically.)
|
|
|
|
The code-quality-related Composer scripts make use of the PHIVE-installed tools.
|
|
This means that for non-ddev-based development, you need to run `phive install`
|
|
before you can use the Composer scripts.
|
|
|
|
### Available Composer scripts
|
|
|
|
You can run `composer` (or `ddev composer`) to display a list of all available
|
|
Composer commands and scripts.
|
|
|
|
| Script name | Action | Tool |
|
|
|------------------------|-------------------------------|---------------------------------------------------------------------------------|
|
|
|`ci` | run code checks | the tools listed for the individual checks |
|
|
|`ci:composer:normalize` | normalize `composer.json` | [composer-normalize](https://github.com/ergebnis/composer-normalize) |
|
|
|`ci:json:lint` | lint the JSON files | [JSON Lint](https://github.com/Seldaek/jsonlint) |
|
|
|`ci:php` | run all static checks for PHP | the tools listed for the individual checks |
|
|
|`ci:php:copypaste` | check for copy'n'pasted code | [PHP Copy/Paste Detector (PHPCPD)](https://github.com/sebastianbergmann/phpcpd) |
|
|
|`ci:php:cs-fixer` | check the code style | [PHP Coding Standards Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) |
|
|
|`ci:php:lint` | lint the PHP files | `php -l` |
|
|
|`ci:php:sniff` | check the code style | [PHP_CodeSniffer (PHPCS)](https://github.com/squizlabs/PHP_CodeSniffer) |
|
|
|`ci:php:stan` | check the types | [PHPStan](https://github.com/phpstan/phpstan) |
|
|
|`ci:tests:functional` | run the functional tests | [PHPUnit](https://github.com/sebastianbergmann/phpunit/) |
|
|
|`ci:tests:tests` | run all PHPUnit tests | [PHPUnit](https://github.com/sebastianbergmann/phpunit/) |
|
|
|`ci:tests:unit` | run the unit tests | [PHPUnit](https://github.com/sebastianbergmann/phpunit/) |
|
|
|`ci:ts:lint` | lint the TypoScript files | [TypoScript Lint](https://github.com/martin-helmich/typo3-typoscript-lint) |
|
|
|`ci:yaml:lint` | lint the YAML files | [yaml-lint](https://github.com/j13k/yaml-lint) |
|
|
|`fix:php` | run all fixes for PHP | the tools listed for the individual checks |
|
|
|`fix:php:cs` | fix the code style | [PHP Coding Standards Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) |
|
|
|`fix:php:sniff` | fix the code style | [PHP_CodeSniffer (PHPCS)](https://github.com/squizlabs/PHP_CodeSniffer) |
|
|
|
|
## Running the unit and functional tests
|
|
|
|
### On the command line
|
|
|
|
To run the unit tests with ddev, use this command:
|
|
|
|
```bash
|
|
ddev composer ci:tests:unit
|
|
```
|
|
To run the functional tests with ddev, use this command:
|
|
|
|
```bash
|
|
ddev composer ci:tests:functional
|
|
```
|
|
|
|
If you are working locally without ddev, omit the `ddev` part.
|
|
|
|
### In PhpStorm
|
|
|
|
#### General setup for PHPUnit
|
|
|
|
File > Settings > PHP > Test Frameworks
|
|
|
|
- (*) Use Composer autoloader
|
|
- Path to script: select `.Build/vendor/autoload.php` in your project folder
|
|
|
|
In the Run configurations, edit the PHPUnit configuration and use these
|
|
settings so this configuration can serve as a template:
|
|
|
|
- Directory: use the `Tests/Unit` directory in your project
|
|
- (*) Use alternative configuration file
|
|
- use `.Build/vendor/nimut/testing-framework/res/Configuration/UnitTests.xml`
|
|
in your project folder
|
|
- add the following environment variables:
|
|
- typo3DatabaseUsername
|
|
- typo3DatabasePassword
|
|
- typo3DatabaseHost
|
|
- typo3DatabaseName
|
|
|
|
#### Unit tests configuration
|
|
|
|
In the Run configurations, copy the PHPUnit configuration and use these
|
|
settings:
|
|
|
|
- Directory: use the `Tests/Unit` directory in your project
|
|
|
|
#### Functional tests configuration
|
|
|
|
In the Run configurations, copy the PHPUnit configuration and use these
|
|
settings:
|
|
|
|
- Directory: use the `Tests/Functional` directory in your project
|
|
- (*) Use alternative configuration file
|
|
- use
|
|
`.Build/vendor/nimut/testing-framework/res/Configuration/FunctionalTests.xml`
|
|
|
|
## Running the acceptance tests
|
|
|
|
### On the command line
|
|
|
|
1. make sure you have Chrome installed on your machine
|
|
1. [download the latest version of ChromeDriver](http://chromedriver.chromium.org/downloads)
|
|
1. unzip it
|
|
1. `chromedriver --url-base=wd/hub`
|
|
1. `.Build/vendor/bin/codecept run` (in another terminal)
|
|
|
|
### In PhpStorm
|
|
|
|
1. make sure the "Codeception Framework" plugin is activated
|
|
2. right-click on `Tests/Acceptance/StarterCest.php`
|
|
3. Run 'Acceptance (Codeception)'
|
|
|
|
## Security
|
|
|
|
Libraries and extensions do not need the security check as they should not have
|
|
any restrictions concerning the other libraries they are installed alongside
|
|
with (unless those would create breakage). Libraries and extension also should
|
|
not have a version-controlled `composer.lock` (which usually is used for
|
|
security checks).
|
|
|
|
Instead, the projects and distributions (i.e., for TYPO3 installations) need to
|
|
have the security checks.
|
|
|
|
## Rendering the documentation
|
|
|
|
After you have cloned the git repository, follow
|
|
[the TYPO3 documentation quickstart guide](https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/RenderingDocs/Quickstart.html).
|