diff --git a/AGENTS.md b/AGENTS.md index 2ea77f5ca..1ad388ebe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,7 @@ Only these commands are known to work: - `./build-local.sh [version]` builds all PHP images of one version. - `make check` installs the PHP tools of `ci/` and checks the PHP code in `ci/` with GrumPHP: coding standard, PHPStan, Rector, `composer audit` and the PHPUnit tests. Run it after every change to `ci/`. GrumPHP and PHPStan only check files that Git knows (`git ls-files`), so `git add` new files first; PHPUnit runs every test anyway. `make test` runs only the tests. Changes to `ci/src` come with tests. - `make test-image IMAGE=webdevops/:` runs the image tests of that image against a container of it; `REFERENCE=` tests another image, e.g. a local build, with the same tests. It builds `ci/image-tests/Dockerfile` (`make test-image-runner`) and runs it with the Docker socket (`make test-image-run`); the CI runs `make test-image-run` after building the runner with its cache. +- In an image test, a file that a service writes as `application` and a command of the test writes as root (`docker exec`) belongs in `/app`, not in `/tmp`. The runners of GitHub Actions set `fs.protected_regular`, under which even root may not open a file of another user in a sticky directory with `O_CREAT`; a Docker host without it, as many local ones, lets such a test pass that then fails in the CI. - `make generate`, `make check` and `make test` run as your user, so the files they write belong to you. Do not write into the checkout as root. Besides `generate`, `check` and `test`, the Makefile has `structure-test`. `make structure-test` runs container-structure-test against your local images of `bootstrap`, `base`, `base-app`, `php`, `php-dev` and `php-nginx`, the images that have a suite in `tests/structure-test`. It tests only the tags in `.github/workflows/build.yaml` and fails if a test fails, if `docker` fails or if no such image exists locally; run it inside `webdevops/dockerfile-build-env` with the Docker socket mounted. The CI runs the image tests for every image except `toolbox`, and container-structure-test for the six images above; to check a change by hand, start the image and try it as described below.