From 1505232bab64f5f87f36e3232bdc8b91ad3b4042 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 7 Apr 2024 11:28:41 +0545 Subject: [PATCH 1/5] update testing docs --- README.md | 7 +- docs/testing.md | 195 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+), 2 deletions(-) create mode 100644 docs/testing.md diff --git a/README.md b/README.md index b9fd2df..3db716f 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,5 @@ -# docs -Utopia php docs +# Utopia PHP Docs + +Lite & fast micro PHP framework and libraries that are **easy to learn and use**. + +- [Testing](./docs/testing.md) \ No newline at end of file diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..93fe3b9 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,195 @@ +# Testing + +We use GitHub actions for testing and maintaining code quality. There are two sets of templates that you can use for running the tests and analyzers. + +## Without using docker + +If the library doesn't require docker to function and run tests, use these set of templates to create GitHub action for those libraries. + +1. tests.yml + +```yml +name: "Tests" + +on: [pull_request] +jobs: + lint: + name: Tests ${{ matrix.php-versions }} + runs-on: ubuntu-latest + strategy: + matrix: + php-versions: ['8.1', '8.2', '8.3', 'nightly'] + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Setup PHP ${{ matrix.php-versions }} + uses: shivammathur/setup-php@v2 + with: + php-version: ${{ matrix.php-versions }} + + - name: Validate composer.json and composer.lock + run: composer validate --strict + + - name: Compose install + run: composer install --ignore-platform-reqs + + - name: Run tests + run: composer test +``` + +2. linter.yml + +```yml +name: "Linter" + +on: [pull_request] +jobs: + lint: + name: Linter + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + fetch-depth: 2 + + - run: git checkout HEAD^2 + + - name: Run Linter + run: | + docker run --rm -v $PWD:/app composer sh -c \ + "composer install --profile --ignore-platform-reqs && composer lint" +``` + +3. codeql-analysis.yml + +```yml +name: "CodeQL" + +on: [pull_request] +jobs: + lint: + name: CodeQL + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Run CodeQL + run: | + docker run --rm -v $PWD:/app composer sh -c \ + "composer install --profile --ignore-platform-reqs && composer check" +``` + + +## Using docker + +If the library requires docker to function and run tests use these set of templates to create GitHub action for those libraries. + +1. tests.yml + +```yaml +name: "Tests" + +on: [ pull_request ] +jobs: + lint: + name: Tests + runs-on: ubuntu-latest + strategy: + matrix: + php-versions: ['8.1', '8.2', '8.3'] # add PHP versions as required + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + fetch-depth: 2 + + - run: git checkout HEAD^2 + + - name: Build + run: | + export PHP_VERSION=${{ matrix.php-versions }} + docker compose build + docker compose up -d + sleep 10 + + - name: Run Tests + run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests +``` + +You also need to create a corresponding Dockerfile for each PHP version in the format `Dockerfile-php-[PHP_VERSION]`. and in the docker compose the service should be defined as the following so that it uses the corresponding Dockerfile for each PHP version test. Where `8.3` is a default version if `PHP_VERSION` environmanet variable is not specified. + +```yml +tests: + build: + context: . + dockerfile: Dockerfile.php-${PHP_VERSION:-8.3} +``` + +For the above test file where you are testing 3 php versions, following Dockerfile should exist. + +``` +- Dockerfile-php-8.1 +- Dockerfile-php-8.2 +- Dockerfile-php-8.3 +``` + +For linter and code analysis we can use only one PHP version. + +2. linter.yml + +```yml +name: "Linter" + +on: [ pull_request ] +jobs: + lint: + name: Linter + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + fetch-depth: 2 + + - run: git checkout HEAD^2 + + - name: Run Linter + run: | + docker run --rm -v $PWD:/app composer sh -c \ + "composer install --profile --ignore-platform-reqs && composer lint" +``` + +3. codeql-analysis.yml + +```yml +name: "CodeQL" + +on: [ pull_request ] +jobs: + lint: + name: CodeQL + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + with: + fetch-depth: 2 + + - run: git checkout HEAD^2 + + - name: Run CodeQL + run: | + docker run --rm -v $PWD:/app composer sh -c \ + "composer install --profile --ignore-platform-reqs && composer check" +``` + +> Don't forget to define the scripts `check`, `lint` and `test` on `composer.json` \ No newline at end of file From 7ed0e688778716a2420f80a818b88f2b05635dda Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 7 Apr 2024 13:33:46 +0545 Subject: [PATCH 2/5] Update testing.md --- docs/testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/testing.md b/docs/testing.md index 93fe3b9..f0c0dcf 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -129,7 +129,7 @@ You also need to create a corresponding Dockerfile for each PHP version in the f tests: build: context: . - dockerfile: Dockerfile.php-${PHP_VERSION:-8.3} + dockerfile: Dockerfile-php-${PHP_VERSION:-8.3} ``` For the above test file where you are testing 3 php versions, following Dockerfile should exist. @@ -192,4 +192,4 @@ jobs: "composer install --profile --ignore-platform-reqs && composer check" ``` -> Don't forget to define the scripts `check`, `lint` and `test` on `composer.json` \ No newline at end of file +> Don't forget to define the scripts `check`, `lint` and `test` on `composer.json` From ffaf2f4f57717863019a3c8a5ccfdf776d277d44 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 9 Apr 2024 08:25:54 +0545 Subject: [PATCH 3/5] Update testing.md --- docs/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/testing.md b/docs/testing.md index f0c0dcf..099aee2 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -120,7 +120,7 @@ jobs: sleep 10 - name: Run Tests - run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml tests + run: docker compose exec tests vendor/bin/phpunit --configuration phpunit.xml ``` You also need to create a corresponding Dockerfile for each PHP version in the format `Dockerfile-php-[PHP_VERSION]`. and in the docker compose the service should be defined as the following so that it uses the corresponding Dockerfile for each PHP version test. Where `8.3` is a default version if `PHP_VERSION` environmanet variable is not specified. From a2e099568e36be26bc2b8d2df78ccfd21fc8002d Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 9 Apr 2024 11:17:10 +0545 Subject: [PATCH 4/5] Update testing.md --- docs/testing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/testing.md b/docs/testing.md index 099aee2..e5412e8 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -129,15 +129,15 @@ You also need to create a corresponding Dockerfile for each PHP version in the f tests: build: context: . - dockerfile: Dockerfile-php-${PHP_VERSION:-8.3} + dockerfile: php-${PHP_VERSION:-8.3}.Dockerfile ``` For the above test file where you are testing 3 php versions, following Dockerfile should exist. ``` -- Dockerfile-php-8.1 -- Dockerfile-php-8.2 -- Dockerfile-php-8.3 +- php-8.1.Dockerfile +- php-8.2.Dockerfile +- php-8.3.Dockerfile ``` For linter and code analysis we can use only one PHP version. From 333dfd99ec77e7b94b1e856581664913f746c0fe Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Tue, 9 Apr 2024 11:24:13 +0545 Subject: [PATCH 5/5] Update testing.md --- docs/testing.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/testing.md b/docs/testing.md index e5412e8..c8527b0 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -2,6 +2,26 @@ We use GitHub actions for testing and maintaining code quality. There are two sets of templates that you can use for running the tests and analyzers. +## Composer setup + +Install dev dependencies. Phpunit for testing, laravel pint for formatting and lining, phpstan for static analysis. + +```bash +composer require phpunit/phpunit laravel/pint phpstan/phpstan --dev +``` + +Also update scripts so it's easier to use + +```json +"scripts": { + "lint": "./vendor/bin/pint --test", + "format": "./vendor/bin/pint", + "test": "vendor/bin/phpunit --configuration phpunit.xml", + "check": "./vendor/bin/phpstan analyse --level max src tests" +}, +``` + + ## Without using docker If the library doesn't require docker to function and run tests, use these set of templates to create GitHub action for those libraries.