Merge pull request #41 from qase-tms/release/2.0.0

Added new version of PHPUnit reporter

.github/workflows/php.yml

@@ -0,0 +1,32 @@
+name: CI - PHP Build & Tests
+
+on:
+  push:
+  pull_request:
+    branches:
+      - 'main'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        php-version: [8.0, 8.1, 8.2, 8.3, 8.4]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: mbstring, intl
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-suggest
+
+      - name: Run tests
+        run: vendor/bin/phpunit

.gitignore

@@ -1,6 +1,59 @@
-# dependencies
-/vendor/
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
 
-# code coverage and quality reports
+.idea/**
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### PHPUnit template
+# Covers PHPUnit
+# Reference: https://phpunit.de/
+
+# Generated files
 .phpunit.result.cache
-.phpunit.cache/
+.phpunit.cache
+
+# PHPUnit
+/app/phpunit.xml
+/phpunit.xml
+
+# Build data
+/build/
+**/vendor/
+
+.DS_Store

README.md

@@ -1,124 +1,130 @@
-> # Qase TMS PHPUnit reporter
->
-> Publish results simple and easy.
+# Qase TMS PHPUnit Reporter
 
-## How to integrate
+Publish test results easily and efficiently.
 
-```bash
-composer require qase/phpunit-reporter
+## Installation
+
+To install the latest version, run:
+
+```sh
+composer require qase/phpunit-reporter 
 ```
 
-## Example of usage
+## Getting Started
+
+The PHPUnit reporter can auto-generate test cases and suites based on your test data.
+Test results of subsequent test runs will match the same test cases as long as their names and file paths don’t change.
+
+You can also annotate tests with the IDs of existing test cases from Qase.io before executing them.
+This is a more reliable way to bind automated tests to test cases, ensuring they persist when you rename, move, or
+parameterize your tests.
 
-The PHPUnit reporter has the ability to auto-generate test cases
-and suites from your test data.
+For example:
 
-But if necessary, you can independently register the ID of already
-existing test cases from TMS before the executing tests. For example:
+```injectablephp
+<?php
 
-```php
-/**
- * @qaseId 3
- */
-public function testCanBeUsedAsString(): void
+namespace Tests;
+
+use Exception;
+use PHPUnit\Framework\TestCase;
+use Qase\PHPUnitReporter\Attributes\Field;
+use Qase\PHPUnitReporter\Attributes\Parameter;
+use Qase\PHPUnitReporter\Attributes\QaseId;
+use Qase\PHPUnitReporter\Attributes\Suite;
+use Qase\PHPUnitReporter\Attributes\Title;
+
+#[Suite("Main suite")]
+class SimplesTest extends TestCase
 {
-    $this->assertEquals(
-        'user@example.com',
-        Email::fromString('user@example.com')
-    );
+    #[
+        Title('Test one'),
+        Parameter("param1", "value1"),
+    ]
+    public function testOne(): void
+    {
+        $this->assertTrue(true);
+    }
+
+    #[
+        QaseId(123),
+        Field('description', 'Some description'),
+        Field('severity', 'major')
+    ]
+    public function testTwo(): void
+    {
+        $this->assertTrue(false);
+    }
+
+    #[
+        Suite('Suite one'),
+        Suite('Suite two')
+    ]
+    public function testThree(): void
+    {
+        throw new Exception('Some exception');
+    }
 }
 ```
-To run tests and create a test run, execute the command:
+
+To execute PHPUnit tests and report them to Qase.io, run the command:
 
 ```bash
-$ ./vendor/bin/phpunit
+QASE_MODE=testops ./vendor/bin/phpunit
 ```
 
-![Output of run](example/screenshots/screenshot.png)
+or, if configured in a script:
 
-A test run will be performed and available at:
+```bash
+composer test
 ```
+
+A test run will be created and accessible at:
+
 https://app.qase.io/run/QASE_PROJECT_CODE
-```
 
-If test fails, a defect will be automatically created
+### Parallel Execution
 
-## Using parameterization
+The reporter supports parallel execution of tests using the `paratest` package.
 
-PHPUnit reporter also allows you to perform parameterization of the test case. To do this, you need to specify a dataprovider. Example:
-```php
-    /**
-     * @dataProvider additionProvider
-     */
-    public function testUsingProvider($a, $b, $expected)
-    {
-        $this->assertSame($expected, $a + $b);
-    }
+To run tests in parallel, use the following command:
 
-    public function additionProvider()
-    {
-        return [
-            [0, 0, 0],
-            [0, 1, 1],
-            [1, 0, 1],
-            [1, 1, 3]
-        ];
-    }
+```bash
+QASE_MODE=testops ./vendor/bin/paratest
 ```
-![dashboard](example/screenshots/screenshot2.png)
 
 ## Configuration
 
-Add to your `phpunit.xml` extension:
+Qase PHPUnit Reporter can be configured using:
 
-```xml
-<extensions>
-  <extension class="Qase\PHPUnit\Reporter"/>
-</extensions>
-```
+1. A separate configuration file qase.config.json.
+2. Environment variables (which override the values in the configuration file).
+
+For a full list of configuration options, refer to
+the [Configuration Reference](https://github.com/qase-tms/qase-php-commons/blob/main/README.md#configuration).
 
-Reporter options (* - required):
-
-- `QASE_REPORT` - toggles sending reports to Qase.io, set `1` to enable
-- *`QASE_API_TOKEN` - access token, you can find more information [here][auth].
-- *`QASE_PROJECT_CODE` - code of your project (can be extracted from main page of your project,
-  as example, for `https://app.qase.io/project/DEMO` -> `DEMO` is project code here.
-- *`QASE_API_BASE_URL` - URL endpoint API from Qase TMS, default is `https://api.qase.io/v1`.
-- `QASE_RUN_ID` - allows you to use an existing test run instead of creating new.
-- `QASE_RUN_NAME` - Set custom Run name, when new run is created.
-- `QASE_RUN_DESCRIPTION` - Set custom Run description, when new run is created.
-- `QASE_RUN_COMPLETE` - performs the "complete" function after passing the test run.
-- `QASE_ENVIRONMENT_ID` - environment ID from Qase TMS
-- `QASE_LOGGING` - toggles debug logging, set `1` to enable
-
-The configuration file should be called `phpunit.xml`, an example of such a file:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<phpunit>
-  <extensions>
-    <extension class="Qase\PHPUnit\Reporter"/>
-  </extensions>
-  <testsuites>
-    <testsuite name="qase-phpunit">
-      <directory>./tests</directory>
-    </testsuite>
-  </testsuites>
-  <php>
-    <env name="QASE_REPORT" value="1" force="true" />
-    <env name="QASE_API_TOKEN" value="<api_key>" force="true" />
-    <env name="QASE_PROJECT_CODE" value="<project_code>" force="true" />
-    <env name="QASE_API_BASE_URL" value="https://api.qase.io/v1" force="true" />
-    <env name="QASE_RUN_ID" value="" force="true" />
-    <env name="QASE_RUN_NAME" value="PHPUnit run" force="true" />
-    <env name="QASE_RUN_DESCRIPTION" value="PHPUnit automated run" force="true" />
-    <env name="QASE_RUN_COMPLETE" value="1" force="true" />
-    <env name="QASE_ENVIRONMENT_ID" value="1" force="true" />
-    <env name="QASE_LOGGING" value="1" force="true" />
-  </php>
-</phpunit>
+Example qase.config.json
+
+```json
+{
+  "mode": "testops",
+  "debug": true,
+  "testops": {
+    "api": {
+      "token": "api_key"
+    },
+    "project": "project_code",
+    "run": {
+      "complete": true
+    }
+  }
+}
 ```
 
-<!-- references -->
+## Requirements
+
+We maintain the reporter on LTS versions of PHP.
+
+- php >= 8.0
+- phpunit >= 9.5
 
-[auth]: https://developers.qase.io/#authentication