Merge pull request #76 from mage-os/DavidLambauer-patch-9

Author: DavidLambauer

unit-testing.md

@@ -1,157 +1,265 @@
-# Unit Testing Documentation
+# Unit Testing in Magento 2
 
 [TOC]
 
-## Introduction
+## Overview
 
-Unit testing is an essential practice in software development that involves testing individual units or components of
-code to ensure their correctness. In this documentation, we will explore the fundamentals of unit testing, its benefits,
-and how to write effective unit tests for PHP and Magento 2.
+Unit testing is a critical part of software development. It involves testing individual units of code (such as functions
+or methods) to ensure they perform as expected. In Magento 2, PHPUnit is the testing framework used for writing and
+executing unit tests.
 
-## Benefits of Unit Testing
+Magento 2 has a solid structure for unit tests that separates them from other types of tests (like integration,
+functional, and performance tests). In a typical Magento 2 module, the unit tests are located in the `Test/Unit`
+directory of the module.
 
-Unit testing offers numerous benefits, including:
+## Setup and Configuration
 
-1. **Bug Prevention**: By testing individual units of code, potential bugs and errors can be identified and fixed early
-   in the development process, reducing the overall cost and effort required.
+Before you begin, ensure you have PHPUnit installed. Magento 2 recommends using the latest stable PHPUnit version
+supported by your PHP installation.
 
-2. **Code Maintainability**: Unit tests act as a safety net when making changes to the codebase. They provide assurance
-   that existing functionality will not break due to modifications, making it easier to refactor and improve code.
+You can install PHPUnit globally or as a part of your project via Composer. The following command installs PHPUnit
+globally:
 
-3. **Documentation**: Unit tests serve as living documentation, providing examples of how the code should be used and
-   the expected behavior of its components.
+```bash
+composer global require phpunit/phpunit
+```
+
+After installing PHPUnit, validate the installation by checking the version:
 
-4. **Rapid Feedback**: Unit tests enable quick feedback on code changes, as they can be executed independently and do
-   not require the entire application to be running.
+```bash
+phpunit --version
+```
 
-5. **Collaboration**: Unit tests facilitate collaboration among developers by providing a common understanding of code
-   functionality and behavior.
+## Creating a Unit Test
 
-## Unit Testing in PHP
+In this section, we'll create a simple unit test for a hypothetical SampleModule in Magento 2.
 
-### PHPUnit
+1. Navigate to your module's directory and create a new Test/Unit directory if it doesn't exist.
 
-PHPUnit is a widely used unit testing framework for PHP. It provides a rich set of assertions, test runners, and other
-utilities to aid in writing effective unit tests. Let's look at some examples of how to write unit tests using PHPUnit.
+```bash
+mkdir -p app/code/Vendor/SampleModule/Test/Unit
+```
 
-To begin, create a new test class, `MyClassTest`, that extends the `PHPUnit\Framework\TestCase` class:
+2. Inside the `Test/Unit` directory, create a new test class. In this case, we'll create `SampleTest.php`:
 
 ```php
-use PHPUnit\Framework\TestCase;
+<?php
+declare(strict_types=1);
+
+namespace Vendor\SampleModule\Test\Unit;
 
-class MyClassTest extends TestCase
+class SampleTest extends \PHPUnit\Framework\TestCase
 {
-    // Test methods will be written here
+    public function testSampleMethod(): void
+    {
+        $this->assertEquals(10, 5 + 5);
+    }
 }
 ```
 
-#### Asserting Equality
+In this example, `testSampleMethod` is a simple test case that asserts whether `5 + 5` equals `10`.
 
-PHPUnit provides various assertion methods to validate expected outcomes. One common assertion is to check for equality
-between expected and actual values. For example:
+## Running Unit Tests
 
-```php
-public function testAddition()
-{
-    $result = 2 + 2;
-    $this->assertEquals(4, $result);
-}
+To run the unit test, use the phpunit command from the root directory of your Magento 2 installation:
+
+```bash
+./vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/Vendor/SampleModule/Test/Unit
 ```
 
-In the above example, the `assertEquals` method checks whether the `$result` variable is equal to `4`.
+This command tells PHPUnit to use the configuration specified in phpunit.xml.dist and run the tests located
+in `app/code/Vendor/SampleModule/Test/Unit`.
 
-#### Mocking Dependencies
+To run an entire suite (i.e., all tests in a directory), specify the directory path:
 
-When testing code that has dependencies, it's often necessary to create mocks or stubs to isolate the unit being tested.
-PHPUnit provides a `getMock()` method to create mock objects.
+```bash
+./vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/Vendor/SampleModule/Test/Unit
+```
 
-```php
-public function testSomethingWithMock()
-{
-    $dependencyMock = $this->getMockBuilder(DependencyClass::class)
-                          ->getMock();
+The output should look something like this:
 
-    // Use the mock object within the test
-}
+```bash
+PHPUnit X.X.X by Sebastian Bergmann and contributors.
+
+.                                       1 / 1 (100%)
+
+Time: X ms, Memory: X MB
+
+OK (1 test, 1 assertion)
 ```
 
-In the above example, the `getMockBuilder()` method creates a mock object of the `DependencyClass`. This allows the test
-to control the behavior of the dependency and focus solely on the unit being tested.
+## Run Unit Tests within PHPStorm
+
+To run tests within PHPStorm, follow these steps:
+
+Open the `Settings/Preferences` dialog (`Ctrl+Alt+S`), go to `Languages & Frameworks | PHP | Test Frameworks`.
+Click `+`, and choose `PHPUnit Local`.
+Configure the PHPUnit library and settings.
+After the configuration, go to your test, right-click on it and select Run `test-name`.
+
+## Write Testable Code
+
+Writing testable code involves designing your code in a way that makes it easier to isolate and test individual units.
+Some tips for writing testable code include:
 
-For more advanced mocking scenarios, PHPUnit also supports the use of mock libraries such as Mockery and Prophecy.
+**Single Responsibility**: Each method/class should have a single responsibility. It should do one thing and do it well.
+**Avoid Static Methods**: Static methods can't be mocked or stubbed, making them difficult to test.
+**Dependency Injection**: Using dependency injection helps make your code more flexible and easier to test.
 
-## Unit Testing in Magento 2
+## Best Practices
 
-### Magento Testing Framework (MTF)
+**Use Descriptive Test Method Names**: The method name should describe what the test does. For example,
+`testUserIsCreatedWithValidInput` is descriptive and you can understand what the test does by looking at its name.
+**One Assertion Per Test Method**: Ideally, each test should only have one assertion. This makes the tests more readable
+and
+errors easier to pinpoint.
+**Don't Test Everything**: It's important to note that not all code needs to be tested. If it's already being tested
+elsewhere or it's part of the framework's functionality, there's usually no need to test it again.
 
-Magento 2 provides a dedicated testing framework called Magento Testing Framework (MTF) for writing unit tests. MTF
-extends PHPUnit and introduces additional features specific to Magento.
 
-To write unit tests in Magento 2, follow these steps:
+## Mocking
 
-1. Create a new test class that extends the `Magento\FunctionalTestingFramework\TestCase\TestCase` class:
+Mocking is a process used in unit testing when the unit of code has external dependencies. A mock object is a dummy
+implementation that simulates the behavior of a real object.
 
 ```php
-use Magento\FunctionalTestingFramework\TestCase\TestCase;
+<?php
+namespace Vendor\SampleModule\Test\Unit;
 
-class MyMagentoTest extends TestCase
+use PHPUnit\Framework\TestCase;
+use PHPUnit\Framework\MockObject\MockObject;
+use Vendor\SampleModule\Model\Sample;
+
+class SampleTest extends TestCase
 {
-    // Test methods will be written here
+    /**
+    * @var MockObject
+    */
+    private $sampleMock;
+
+    protected function setUp(): void
+    {
+        $this->sampleMock = $this->getMockBuilder(Sample::class)
+            ->disableOriginalConstructor()
+            ->getMock();
+    }
+
+    public function testSampleMethod()
+    {
+        $this->sampleMock->method('getNumber')
+            ->willReturn(5);
+
+        $this->assertEquals(10, $this->sampleMock->getNumber() + 5);
+    }
 }
 ```
 
-2. Use the Magento testing APIs to interact with the Magento system and test the desired functionality.
+In this example, `Sample::class` is a dependency of the unit being tested. We create a mock for this dependency and
+define
+its behavior to return `5` when getNumber is called.
+
+## DocBlock Annotations
+
+DocBlocks or PHPDoc comments are used to provide metadata for your codebase. These comments can be parsed by tools to
+generate human-readable documentation.
+
+PHPUnit uses these annotations to control the behavior of your tests. Here are some commonly used annotations:
+
+- `@test`: This annotation can be used to mark a method as a test method.
+- `@dataProvider`: This annotation can be used to specify a method that returns data for a test.
+- `@depends`: This annotation can be used to specify that a test depends on another test.
+- `@group`: This annotation allows you to group tests together so you can run a set of tests separately from others.
+
+Example:
 
 ```php
-public function testMyCustomModule()
+/**
+ * @test
+ * @dataProvider additionProvider
+ */
+public function testAdd($a, $b, $expected)
+{
+    $this->assertEquals($expected, $a + $b);
+}
+
+public function additionProvider()
 {
-    $this->loginAdminUser('admin', 'password');
-    $this->openAdminPage('my_custom_module');
-    $this->seePageTitle('My Custom Module');
-    // Additional assertions and interactions
+    return [
+        [1, 2, 3],
+        [0, 0, 0],
+        [-1, -1, -2],
+    ];
 }
 ```
 
-In the above example, the test interacts with the Magento system by logging in as an admin user, opening an admin page,
-and asserting the expected page title.
-
-### Data Fixtures
-
-Magento 2 allows the creation of data fixtures to provide consistent test data for unit tests. Data fixtures are defined
-in XML files and can be used to set up test scenarios.
-
-```xml
-<testData>
-    <fixture>
-        <name>my_module_data</name>
-        <data>
-            <table_name>
-                <row>
-                    <column1>value1</column1>
-                    <column2>value2</column2>
-                </row>
-            </table_name>
-        </data>
-    </fixture>
-</testData>
+In this example, `@test` marks `testAdd` as a test method, and `@dataProvider` specifies `additionProvider` as the
+method
+providing data for the `testAdd` test.
+
+This concludes our in-depth guide on unit testing in Magento 2. Remember that good tests can help you catch bugs early,
+make your codebase more maintainable, and save you, your team, and your users a lot of trouble down the line. Happy
+testing!
+
+
+## Code Coverage
+
+Code coverage is a measure that describes the degree to which the source code of a program is executed when a particular
+test suite runs. To generate a code coverage report, PHPUnit needs `Xdebug` or `pcov` installed.
+
+You can enable code coverage in the PHPUnit configuration file (phpunit.xml) or run the command:
+
+```bash
+./vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist --coverage-html coverage app/code/Vendor/SampleModule/Test/Unit
 ```
 
-In the above example, a fixture named `my_module_data` is defined, which inserts a row into the `table_name` table with
-specified column values.
+This command will generate an HTML report in the `coverage` directory.
 
-Fixtures can be used within a test using the `loadFixture()` method provided by MTF:
+## Run Unit Tests in CI
 
-```php
-public function testMyModuleWithFixture()
-{
-    $this->loadFixture('my_module_data');
-    // Additional test logic using the fixture data
-}
+### GitHub Actions
+
+In your `.github/workflows` directory, create a new file called `run-tests.yml` and populate it:
+
+```yaml
+name: Run PHPUnit Tests
+
+on: [ push, pull_request ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Validate composer.json and composer.lock
+        run: composer validate
+
+      - name: Install Dependencies
+        run: composer install --prefer-dist --no-progress --no-suggest
+
+      - name: Run PHPUnit
+        run: ./vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/Vendor/SampleModule/Test/Unit
+```
+
+### GitLab Pipelines
+
+In your .gitlab-ci.yml, add:
+
+```yaml
+stages:
+  - test
+
+phpunit:
+  stage: test
+  image: php:latest
+  script:
+    - composer install
+    - ./vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/Vendor/SampleModule/Test/Unit
 ```
 
-## Conclusion
+## Summary
 
-Unit testing plays a crucial role in software development, enabling developers to validate the correctness of individual
-units of code. By incorporating unit testing into your PHP and Magento 2 projects, you can increase code quality, reduce
-bugs, and improve maintainability. Use this documentation as a guide to get started with unit testing and leverage the
-benefits it offers. Happy testing!
+Unit testing is a vital part of the Magento 2 development process. It helps ensure that your code functions as expected,
+which can help reduce bugs and issues in the future. By using PHPUnit, Magento 2 developers can write and run unit tests
+to validate their code throughout the development process.