Repository navigation
The Test Database
The tests of an app run on a database of their own, and each test runs in a transaction that is rolled back at its end: the rows a test writes are gone after it, and tests never see each other's rows or yours. This page sets that database up, and says what the test bootstrap does with the settings. Since 2.18.0.
/caligrafy-quill:db create the test database: caligrafy_test, with the framework tables, my tables and the migrations
Check before you say OK: php caligrafer.php migrate status --env .env.testing lists every migration as ran, and
php caligrafer.php test passes twice in a row.
Run the commands in the Docker server (docker compose exec dev-box ...; without Docker, drop it and use your MySQL).
-
Its settings. Copy
.envand change one line:cp .env .env.testing
DB_DATABASE=caligrafy_test.env.testingholds the same secrets as.env: the project's.gitignoreleaves out every.env.*file but.env.example(2.19.1). -
The database and its tables.
docker compose exec mysql mysql -uroot -proot -e "CREATE DATABASE IF NOT EXISTS caligrafy_test" docker compose exec dev-box php caligrafer.php platform install --env .env.testing docker compose exec dev-box php caligrafer.php sql application/models/Bookshelf/create_db.sql --env .env.testing docker compose exec dev-box php caligrafer.php migrate --env .env.testing
Runapplication/models/Bookshelf/create_db.sql run on caligrafy_test 1 migration(s) run on caligrafy_testsqlfor eachapplication/models/<folder>/create_db.sqlof the app. -
Run the tests.
docker compose exec dev-box php caligrafer.php test
Check: after the tests, the rows they wrote are not in the test database:
docker compose exec mysql mysql -uroot -proot caligrafy_test -e "SELECT COUNT(*) FROM books WHERE title = 'Tehanu'"
gives 0.
After every new migration, run migrate --env .env.testing again: the tests use the tables as they are.
php caligrafer.php test runs PHPUnit with framework/testing/bootstrap.php, which:
- loads
vendor/autoload.php; - reads
.env, then.env.testingwhen it exists: its settings win; - when
DB_TEST_DATABASEis set (and not empty), puts it in place ofDB_DATABASEfor the tests; - sets
CALIGRAFY_TESTING=true; - loads the framework as the command line does (
Caligrafer::run(): the settings as constants, the helpers, the class map; notapplication/config/config.php), thenCaligrafy\Testing\TestCase.
So there are two ways to point the tests at their database:
| Way | Where | For the commands that prepare it |
|---|---|---|
.env.testing with its own DB_DATABASE (and any other setting) |
a file next to .env
|
--env .env.testing |
DB_TEST_DATABASE=caligrafy_test |
one line in .env
|
still a settings file: the commands read DB_DATABASE, so --env with a file that names it |
With DB_ACTIVATE=true, before each test TestCase opens a transaction on the connection, and after it rolls it back.
Also before each test: the container is reset and booted, the cache's in-memory copies are cleared, and the query
shapes the N+1 warning counts are forgotten.
-
A
CREATE,ALTERorDROPin a test ends the transaction: MySQL commits it at once (G121), and the rows the test wrote before stay. Create tables increate_db.sqland migrations, before the tests. -
A test without a transaction:
protected $transactions = false;in the class. It then cleans up after itself. -
The cache store
database(caligrafy_cache) is in the same transaction: values a test puts there are rolled back too.
-
Tests on your development database: without
.env.testingorDB_TEST_DATABASE, the tests run on the database of.env. The transactions keep its rows, but the tests pass or fail with what is there. -
The test database is behind: a new migration ran on the development database only, and a test fails on a
missing column.
migrate --env .env.testing. -
migrate "" --env .env.testing: the empty word was needed before 2.19.1. -
.env.testingin git: a project made before 2.19.1 adds/.env.*and!/.env.exampleto its.gitignore. -
Snap or token tests fail on a missing table:
platform install --env .env.testingcreates the framework tables (tokens, audit, jobs, cache, migrations, Snap) in the test database.
- Testing your app
- Testing capabilities · Testing pages, forms and actions
- Migrations
- Caligrafer: data commands
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)