diff --git a/Makefile b/Makefile index 0695f932b..c93287468 100644 --- a/Makefile +++ b/Makefile @@ -4,12 +4,15 @@ run: --entrypoint $(CMD) \ php +test-all: test-base \ + test-driver-all test-driver-all: test-driver-sqlite \ test-driver-mysql \ test-driver-mariadb \ test-driver-pgsql \ test-driver-mssql \ test-driver-oracle +test-base: testsuite-Db test-driver-sqlite: testsuite-Sqlite test-driver-mysql: testsuite-Mysql test-driver-mariadb: @@ -32,9 +35,6 @@ testsuite-%: --entrypoint "vendor/bin/phpunit --testsuite $(subst testsuite-,,$@) $(RUN_ARGS)" \ php -static-analysis: CMD="vendor/bin/psalm --no-cache" -static-analysis: run - mutation: CMD="\ vendor/bin/roave-infection-static-analysis-plugin \ --threads=2 \ @@ -44,6 +44,12 @@ vendor/bin/roave-infection-static-analysis-plugin \ --only-covered" mutation: run +static-analysis: CMD="vendor/bin/psalm --no-cache" +static-analysis: run + +rector: CMD="vendor/bin/rector" +rector: run + composer-require-checker: CMD="vendor/bin/composer-require-checker" composer-require-checker: run diff --git a/docker-compose.yml b/docker-compose.yml index 753bb5ba2..8302c5846 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -33,6 +33,7 @@ services: YII_MSSQL_PASSWORD: YourStrong!Passw0rd YII_ORACLE_SID: FREE + YII_ORACLE_DATABASE: FREEPDB1 YII_ORACLE_HOST: oracle YII_ORACLE_PORT: 1521 YII_ORACLE_USER: system diff --git a/docs/internals.md b/docs/internals.md index 9afe6c3e5..53fe939b3 100644 --- a/docs/internals.md +++ b/docs/internals.md @@ -6,90 +6,114 @@ All our packages have github actions by default, so you can test your [contribut > Note: We recommend pull requesting in draft mode until all tests pass. -## Unit testing +## Local development -This package can be tested globally or individually for each DBMS. +Docker is used to ease the local development. -- [MSSQL](https://github.com/yiisoft/db-mssql) -- [MySQL/MariaDB](https://github.com/yiisoft/db-mysql) -- [Oracle](https://github.com/yiisoft/db-oracle) -- [PostgreSQL](https://github.com/yiisoft/db-pgsql) -- [SQLite](https://github.com/yiisoft/db-sqlite) +### Setup -### Docker images +Prerequisites: -For greater ease it is recommended to use Docker containers for each DBMS, for this you can use the [docker-compose.yml](https://docs.docker.com/compose/compose-file/) file that in the root directory of each package. +- Docker. +- Docker Compose. +- +Clone all repos of drivers' packages: -- [MSSQL 2022](https://github.com/yiisoft/db-mssql/blob/master/docker-compose.yml) -- [MySQL 8](https://github.com/yiisoft/db-mysql/blob/master/docker-compose.yml) -- [MariaDB 10.11](https://github.com/yiisoft/db-mysql/blob/master/docker-compose-mariadb.yml) -- [Oracle 21](https://github.com/yiisoft/db-oracle/blob/master/docker-compose.yml) -- [PostgreSQL 15](https://github.com/yiisoft/db-pgsql/blob/master/docker-compose.yml) +- [SQLite](https://github.com/yiisoft/db-sqlite) +- [MySQL](https://github.com/yiisoft/db-mysql) +- [PostgreSQL](https://github.com/yiisoft/db-pgsql) +- [Microsoft SQL Server](https://github.com/yiisoft/db-mssql) +- [Oracle](https://github.com/yiisoft/oracle) + +Create `docker-compose.override.yml` file in the root of the package. Add this contents: + +```yaml +services: + php: + volumes: + - /path/to/packages/db-sqlite:/code/vendor/yiisoft/db-sqlite + - /path/to/packages/db-mysql:/code/vendor/yiisoft/db-mysql + - /path/to/packages/db-pgsql:/code/vendor/yiisoft/db-pgsql + - /path/to/packages/db-mssql:/code/vendor/yiisoft/db-mssql + - /path/to/packages/db-oracle:/code/vendor/yiisoft/db-oracle +``` -For running the Docker containers you can use the following command: +Adjust the `/path/to/packages` to the path where packages are installed on your host machine. -```shell -docker compose up -d -``` +In case of ports' collisions, the mapping and enviroment variables can also be adjusted here. -### Global testing +### Unit testing -The following steps are required to run the tests. +#### Available commands -1. Run all Docker containers for each DBMS. -2. Install the dependencies of the project with composer. -3. Run the tests. +`make test-all` - run all available tests. +`make test-db` - run tests for base db package only. +`make test-driver-all` - run tests for all drivers. +`make test-driver-sqlite` - run tests for SQLite driver only. +`make test-driver-mysql` - run tests for MySQL driver only (using MySQL database). +`make test-driver-mariadb` - run tests for MySQL driver only (using MariaDB database). +`make test-driver-pgsql` - run tests for PostgreSQL driver only. +`make test-driver-mssql` - run tests for Microsoft SQL Server driver only. +`make test-driver-oracle`- run tsets for Oracle driver only. -```shell -./vendor/bin/phpunit -``` +#### Testing different versions -### Individual testing +Docker Compose services use the following stack: -The following steps are required to run the tests. +- PHP 8.3. +- MySQL 9. +- MariaDB 11. +- PostgreSQL 19. +- Microsoft SQL Server 2022. +- Oracle Free 23. -1. Run the Docker container for the dbms you want to test. -2. Install the dependencies of the project with composer. -3. Run the tests. +Different versions are available in GitHub Actions. Other versions of RDBMS might be added to Docker Compose in the +future. -```shell -./vendor/bin/phpunit --testsuite=Pgsql -``` +#### Slow execution time -Suites available: +Running `make` command for the first time can take some time due to building and/or starting all required Docker Compose +services. All subsequent calls will be faster. -- Mssql -- Mysql -- Oracle -- Pgsql -- Sqlite +The execution time of Oracle tests is the longest. The recommended flow is to run only changed / added tests. Add +`@group temp` PHPDoc annotation to changed / added tests temporarily. Then you can limit running tests with the +following command: ```shell -make test-oracle RUN_ARGS="--group temp" +make test-driver-oracle RUN_ARGS="--group temp" ``` -## Static analysis +Don't forget to remove the temporary `@group` tags before marking PR as ready for review. + +Avoid mixing changes for altering test structure with actual changes in test code. + +### Static analysis The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis: ```shell -./vendor/bin/psalm +make static-analysis ``` -## Code style +### Code style Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or use either newest or any specific version of PHP: ```shell -./vendor/bin/rector +make rector ``` -## Dependencies +### Dependencies This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if all dependencies are correctly defined in `composer.json`. To run the checker, execute the following command: ```shell -./vendor/bin/composer-require-checker +make composer-require-checker ``` + +### Miscellaneous commands + +`make shell` - open interactive shell. +`make run command` - run arbitrary command.