Local development stack and tests

For engineers changing the module or the Conviro Magento backend. The authoritative how-to for the Docker stack is undefined (../dev/README.md); this page is the map.

Local Magento stack

integrations/magento2/dev/ — a disposable Docker Compose project (conviro-magento-test):

The module is bind-mounted read-only at app/code/Conviro/AiChat. MSI is enabled. Magento lives in a named volume, never in the git tree.

cd integrations/magento2/dev
./install-magento.sh   # stack + Mage-OS + setup:install (module disabled)
./module-verify.sh     # enable module, setup:upgrade, setup:di:compile, schema checks
./serve.sh             # php -S on :8089  (./serve.sh stop)

tests/mock-conviro.mjs plays Conviro (API and the connect approval page); tests/harness.php runs inside the PHP container for fixtures and direct service calls.

Acceptance scripts

Run with the stack up and serve.sh running. Latest recorded results are from the commit messages (3bb49b22, 2026-09-24).

Version matrix (release gates R1 / R2)

integrations/magento2/dev/matrix/run.sh <version> [phases] builds one disposable stack per Magento release (targets/*.env), installs Magento from mirror.mage-os.org, then runs the upgrade path (the released 1.3.5 zip, configured like a live store against the mock, then this code as 1.4.0) and the fresh path (a clean store, this code as 1.4.0), each followed by the dev suite below and a scan of the PHP and Magento logs. hyva adds the open-source Hyvä theme. Results go to dev/matrix/results/<version>/ (git-ignored); usage in the header of undefined (../dev/matrix/run.sh). The machine it runs on is shared: one core for PHP, one script at a time with pauses, real-browser scripts alone.

Results 2026-09-26 (branch feat/magento-matrix), PASS/FAIL counts per script, upgrade path / fresh install:

Hyvä on 2.4.9 (default theme 1.5.2, magento2-luma-checkout 1.1.7, no licence needed): storefront-browser 12/0 in production mode (every Hyvä page without RequireJS; checkout is the Luma fallback, CSP enforced there), fpc-privacy 7/0, attribution 40/0 (consent accepted through Hyvä's own cookie banner), widget-identity 6/0. Hyvä Checkout is licensed and was not tested.

No deprecation, notice or warning from 1.4.0 code in any run's logs. Every other script failure on the way was traced and is fixed in the module, the backend, the harness or the docs (commits 6aaa1215 → the matrix branch head).

Package install test (release gate R4, 2026-09-26)

run.sh 2.4.7-p4 (target targets/2.4.7-p4.env, Mage-OS 1.0.6 = Magento 2.4.7-p4 on PHP 8.3) installs the exact zip the registry serves (MODULE_ARTIFACT=conviro-module-aichat-1.4.0-RC1.zip from apps/api/src/assets/composer, its sha1 checked against packages.json) through a local Composer artifact repository — not a worktree snapshot. The platform is copied from the dev stack's volume (nothing downloaded). Results, feat/magento-10-10 at d4502bb9:

• Upgrade 1.3.5 → 1.4.0-RC1: the released 1.3.5 zip configured like a live store (auto-connected to the mock, product saved, guest order), then — with both zips in the repository — composer require 'conviro/module-aichat:^1.3' and composer update conviro/module-aichat keep 1.3.5 (minimum-stability stable, prefer-stable); then composer require conviro/module-aichat:1.4.0-RC1, setup:upgrade, setup:di:compile, static deploy, production mode: all OK; setup:db:status up to date; package 1.4.0-RC1, setup_module 1.4.0; the 1.3.5 settings kept; storefront and admin 200; the bearer store re-registered with OAuth 1.0a by cron. Dev scripts on that store: storefront-browser 13/0 (production mode, Luma), oauth-roundtrip 73/0 (+1 note: 1.3.5 left the store-wide bearer switch on), outbox-e2e 25/0, admin-health 42/0. Logs: 0 PHP notices / warnings / deprecations; 18 Magento log entries ≥ WARNING, none mentioning Conviro.
• Fresh install of 1.4.0-RC1 on the clean platform: composer require, module:enable, setup:upgrade, setup:di:compile, static deploy, production mode, setup:db:status, module state, storefront 200, admin 200 — all OK; logs clean (0 / 0).

Unit tests and static analysis

• PHPUnit (AiChat/Test/Unit, standalone bootstrap, no Magento needed): 204 tests / 1460 assertions, and php -l on all 180 PHP / PHTML files, pass on PHP 7.4.33 and 8.2.34 (php:7.4-cli, php:8.2-cli, PHPUnit 9.6; 2026-09-26). After the R4 changes (2026-09-26): 207 tests / 1488 assertions and php -l on 181 files, PHP 7.4.33 and 8.3.
• dev/quality.sh: php -l, Magento Coding Standard at severity 10 (must be 0 errors), PHPStan level 6 with bitexpert/phpstan-magento (must be 0). Output below severity 10 (docblocks, line length) remains.
• CI: .github/workflows/test-magento-module.yml (1db89666) — php -l + PHPUnit on PHP 7.4 and 8.3, and the coding standard + PHPStan against the Magento 2.4.7-p4 code. It has not run on GitHub yet (Actions on the account is blocked by billing at times); its steps were executed locally on PHP 8.3 only. No Docker Magento install or version matrix in CI yet.

Backend tests

Jest suites under apps/api/src/modules/magento/__tests__, apps/api/src/modules/ai-actions/__tests__, apps/api/src/modules/commerce-trust/__tests__ and apps/api/src/modules/temporal/commerce. Opt-in real-Postgres specs: magento-commerce-sync.pg.spec.ts (COMMERCE_SYNC_PG_URL) and the AI action store spec (AI_ACTIONS_PG_URL).

Releasing

apps/api/src/modules/magento/COMPOSER-REGISTRY.md, "Cutting a new release": bump composer.json + etc/module.xml and commit → node scripts/build-composer-registry.mjs → commit src/assets/composer/ and deploy the API → check the zip answers 200 → only then bump MagentoService.MODULE_LATEST_VERSION and deploy. The registry script refuses to drop published versions, to rebuild a published version with different bytes, and to ship CRLF. For 1.4.0 the backend (with migrations 0219–0229) must be live before the package is published — see Release notes.