# Testing

> This package provides a consistent set of Composer scripts for local validation, plus npm scripts for the jQuery plugin and the browser acceptance tests.

This package provides a consistent set of [Composer](https://getcomposer.org/) scripts for local validation, plus
[npm](https://www.npmjs.com/) scripts for the jQuery plugin and the browser acceptance tests. Applications install only
the PHP package.

Tool references:

- [Actionlint](https://github.com/rhysd/actionlint) for GitHub Actions workflow linting.
- [Codespell](https://github.com/codespell-project/codespell) for spelling checks.
- [Composer Require Checker](https://github.com/maglnet/ComposerRequireChecker) for dependency definition checks.
- [Easy Coding Standard (ECS)](https://github.com/easy-coding-standard/easy-coding-standard) for coding standards.
- [EditorConfig Checker](https://github.com/editorconfig-checker/editorconfig-checker) for EditorConfig compliance.
- [ESLint](https://eslint.org/) for JavaScript linting.
- [Gitleaks](https://github.com/gitleaks/gitleaks) for secret scanning.
- [Infection](https://infection.github.io/) for PHP mutation testing.
- [Markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) for Markdown linting.
- [PHPStan](https://phpstan.org/) for static analysis.
- [Playwright](https://playwright.dev/) for PHP-rendered browser acceptance tests.
- [Prettier](https://prettier.io/) for Markdown and YAML formatting checks.
- [StrykerJS](https://stryker-mutator.io/) for JavaScript mutation testing.
- [Testo](https://php-testo.github.io/) for PHP unit tests.
- [Vitest](https://vitest.dev/) with [jsdom](https://github.com/jsdom/jsdom) for JavaScript unit tests.
- [Yamllint](https://github.com/adrienverge/yamllint) for YAML linting.
- [Zizmor](https://github.com/zizmorcore/zizmor) for GitHub Actions security audits.

## Automated refactoring (Rector)

The `rector` and `rector-check` scripts have no `rector.php` configuration yet; they are not part of the checks.

## Coding standards (ECS)

Check coding standards without modifying files.

```bash
composer ecs-check
```

Apply coding standard fixes. Review the changes before keeping them.

```bash
composer ecs
```

## Dependency definition check

Verify that runtime dependencies are correctly declared in `composer.json`.

```bash
composer check-dependencies
```

## Mutation testing (Infection)

Run mutation testing.

```bash
composer mutation
```

Run mutation testing with PHPStan static analysis enabled.

```bash
composer mutation-static
```

Options live in `infection.json5`, which runs the mutants through the Testo adapter (`testo/bridge-infection`); the
reports are written to `runtime/infection`.

## Repository quality checks

Make the CLI tools used by the shared quality workflow available on `PATH`: actionlint with its ShellCheck helper,
codespell, EditorConfig Checker, markdownlint-cli2, Prettier and yamllint. Run all checks:

```bash
composer quality
```

Each tool also has its own script:

```bash
composer actionlint
composer codespell
composer editorconfig-checker
composer markdownlint
composer prettier
composer yamllint
```

The linter configuration lives in `.github/linters`, and the Prettier configuration in `.prettierrc.json` and
`.prettierignore`. CI uses the same files.

## Static analysis (PHPStan)

Run static analysis.

```bash
composer static
```

## Unit tests (Testo)

Run the full test suite configured in `testo.php`.

```bash
composer tests
```

Run one group (`api`, `asset`, `model`, `widget`).

```bash
composer tests -- --group=widget
```

The production-mode asset cases (`YII_DEBUG=false`) need the [runkit7](https://github.com/runkit7/runkit7) extension;
Testo skips them without it. In the `build` workflow, setup-php installs runkit7 only on the Windows jobs for PHP 8.3,
so the other jobs skip these cases. The browser acceptance tests cover the default selection of the minified asset in
their `rendered-production` project on every run.

The `build` workflow runs Testo on PHP 8.3 to 8.5, on Ubuntu and Windows: with the Composer resolution of each PHP
version, with Symfony 6.4, and with `yiisoft/yii2:22.0.x-dev`. Static analysis runs on PHP 8.5; the `assets` workflow
serves the browser fixture with PHP 8.3.

## Workflow security checks

Make zizmor and Gitleaks available on `PATH`. Audit the current workflow files with the same pedantic persona used by
the shared security workflow:

```bash
composer zizmor
```

Scan Git history for secrets with the repository's Gitleaks configuration:

```bash
composer gitleaks
```

Run both checks. Findings make the command fail; inspect them rather than disabling the checks.

```bash
composer security
```

Zizmor needs GitHub API access for its online audits. If the tool runs offline, report that limit separately. To request
an offline audit explicitly:

```bash
composer zizmor -- --offline
```

Report hosted CI execution and its PHP/OS matrix separately from these local commands. Keep generated reports in ignored
`internal/`.

## Passing extra arguments

Composer scripts support forwarding additional arguments using `--`.

Run Testo with a Clover code coverage report (needs PCOV or Xdebug).

```bash
composer tests -- --coverage-clover=internal/coverage/clover.xml
```

Run one test class.

```bash
composer tests -- --filter=DynamicFormWidgetTest
```

## JavaScript tests (Vitest)

Install the Node.js toolchain (see `.nvmrc`) and the PHP dependencies, because the tests load Yii's client scripts from
`vendor/yiisoft/yii2`. Run every project (`source`, `source-script`, `production`) with the coverage thresholds of
`vitest.config.mjs`:

```bash
composer update
npm ci
npm run test:js
```

Run one project:

```bash
npx vitest run --project production
```

`tests/js/kartik.test.js` also loads the Kartik scripts that `composer update` installs from the pinned development
dependencies, `tests/js/tomselect.test.js` the TomSelect build that `npm ci` installs, `tests/js/inputmask.test.js` the
Inputmask build of the pinned `bower-asset/inputmask`, and `tests/js/datepicker.test.js` the scripts of the pinned
Kartik DatePicker (see [Third-party integrations](#third-party-integrations)).

Tests registered as known defects pass while the defect reproduces; report them as failures instead:

```bash
npm run test:js:strict
```

## JavaScript mutation testing (Stryker)

Run mutation testing for the plugin source. Thresholds live in `stryker.config.mjs`; the report is written to
`runtime/stryker`. Stryker runs only the tests that cover each mutant, in the `source` project of
`vitest.mutation.config.mjs` on the `vmThreads` pool, so each run reuses its worker instead of starting a thread.

```bash
npm run test:mutation
```

## JavaScript linting (ESLint)

Lint the plugin, the tests, the tools and the configuration files with `.github/linters/eslint.config.mjs`.

```bash
npm run lint
```

## Browser acceptance tests (Playwright)

Install Chromium once, then run both asset variants. Playwright starts the PHP built-in server with
`tests/Support/Browser/router.php`.

```bash
npx playwright install chromium
npm run test:browser
```

Environment variables:

- `PHP_BINARY`: PHP executable that serves the fixture (default `php`).
- `DYNAMICFORM_BASE_URL`: use an already running fixture server instead, for example a PHP 8.3 container.
- `CHROMIUM_PATH`: use an installed Chromium instead of the Playwright download.

```bash
php -S 127.0.0.1:8181 tests/Support/Browser/router.php
DYNAMICFORM_BASE_URL=http://127.0.0.1:8181 npx playwright test
```

Run only the Kartik Select2 and DepDrop acceptance tests:

```bash
npx playwright test tests/browser/rendered-kartik.spec.mjs
```

Run only the TomSelect acceptance tests:

```bash
npx playwright test tests/browser/rendered-tomselect.spec.mjs
```

Run only the Inputmask acceptance tests:

```bash
npx playwright test tests/browser/rendered-inputmask.spec.mjs
```

Run only the Kartik DatePicker acceptance tests:

```bash
npx playwright test tests/browser/rendered-datepicker.spec.mjs
```

## Third-party integrations

Integration tests run against real, pinned library versions; no plugin is replaced by a stub. The `kartik` browser
scenario renders the widgets through `ActiveForm::field()->widget()`, and its DepDrop requests and Select2 AJAX searches
are answered by deterministic endpoints of `tests/Support/Browser/router.php`, so no external service is contacted. The
`tomselect` scenario publishes TomSelect from `node_modules/tom-select` through a fixture asset bundle and initializes
it on the rendered selects as an application does; `tests/js/tomselect.test.js` loads the same build. The `inputmask`
scenario renders Yii's own `yii\widgets\MaskedInput`, which publishes Inputmask from `bower-asset/inputmask` and masks
the rendered inputs; `tests/js/inputmask.test.js` loads the same `jquery.inputmask.js`. The `datepicker` scenario
renders Kartik DatePicker as a prepended component, as `TYPE_INPUT` and as `TYPE_INLINE`; `tests/js/datepicker.test.js`
loads the same bootstrap-datepicker fork and `datepicker-kv.js`. `tests/js/kartik-inputs.test.js` loads the scripts the
asset bundles of the Kartik TimePicker, FileInput, TouchSpin, MaskMoney and NumberControl widgets register, on the
markup those widgets render; no browser scenario renders them.

| Library                                                                               | Version | Installed by                                                   |
| ------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------- |
| [Select2](https://github.com/select2/select2)                                         | 4.1.0   | npm (`select2`), JavaScript tests                              |
| [Select2](https://github.com/select2/select2)                                         | 4.1.0   | Composer (`select2/select2`), PHP-rendered browser tests       |
| [kartik-v/yii2-widget-select2](https://github.com/kartik-v/yii2-widget-select2)       | 2.2.5   | Composer                                                       |
| [kartik-v/yii2-widget-depdrop](https://github.com/kartik-v/yii2-widget-depdrop)       | 1.0.6   | Composer                                                       |
| [kartik-v/dependent-dropdown](https://github.com/kartik-v/dependent-dropdown)         | 1.4.9   | Composer                                                       |
| [kartik-v/yii2-krajee-base](https://github.com/kartik-v/yii2-krajee-base)             | 3.0.5   | Composer                                                       |
| [yiisoft/yii2-bootstrap5](https://github.com/yiisoft/yii2-bootstrap5)                 | ^2.0.50 | Composer; Krajee widgets require a Bootstrap extension         |
| [TomSelect](https://github.com/orchidjs/tom-select)                                   | 2.7.0   | npm (`tom-select`), complete build                             |
| [Inputmask](https://github.com/RobinHerbots/Inputmask)                                | 5.0.10  | Composer (`bower-asset/inputmask`), jQuery build               |
| [kartik-v/yii2-widget-datepicker](https://github.com/kartik-v/yii2-widget-datepicker) | 1.4.8   | Composer; bundles bootstrap-datepicker 1.8.0 as `kvDatepicker` |
| [kartik-v/yii2-widget-timepicker](https://github.com/kartik-v/yii2-widget-timepicker) | 1.0.5   | Composer; bundles bootstrap-timepicker                         |
| [kartik-v/yii2-widget-fileinput](https://github.com/kartik-v/yii2-widget-fileinput)   | 1.1.1   | Composer; installs bootstrap-fileinput 5.5.4                   |
| [kartik-v/yii2-widget-touchspin](https://github.com/kartik-v/yii2-widget-touchspin)   | 1.2.4   | Composer; bundles Bootstrap TouchSpin 4.2.5                    |
| [kartik-v/yii2-money](https://github.com/kartik-v/yii2-money)                         | 1.2.3   | Composer; bundles jquery-maskmoney 3.1.1                       |
| [kartik-v/yii2-number](https://github.com/kartik-v/yii2-number)                       | 1.0.5   | Composer; masks through Inputmask                              |

Other versions are not covered by these tests, nor are the DatePicker `TYPE_BUTTON` and `TYPE_RANGE` layouts and DepDrop
controls inside nested widgets. Kartik ColorInput (Spectrum) has no handling: since 1.0.1 it renders no
`data-krajee-spectrum` marker.

Inputmask 5.0.10 binds a `submit` and a `reset` handler on the form for every input it masks, and its `remove()` does
not unbind them; the handlers of the masked inputs of a deleted row therefore stay bound to the form.

With `YII_DEBUG=false`, Kartik registers `depdrop.min.js` of yii2-widget-depdrop 1.0.6, an older build that listens to
event names dependent-dropdown 1.4.9 no longer triggers; its Select2 loading handling therefore does not run in the
`rendered-production` browser project, for original and inserted rows alike.

## Minified asset

Regenerate the committed `src/assets/yii2-dynamic-form.min.js` after editing the plugin; the `assets` workflow fails
when the committed file differs from a fresh build.

```bash
npm run build
```

[Back to documentation](/docs/extensions/dynamicform/index.md#documentation)