grandstack
docs / grandstack-web / Help

Testing

Four layers, from fastest to most realistic.

Where to run this. Commands on this page that start with npm, node or docker build run inside a clone of this repository: git clone https://github.com/grand-stack/grandstack-web, then cd grandstack-web (Node 22 or later; run npm ci once). Commands that need the running stack use the grandstack repository’s compose files: see the quickstart.

1. Type checking

npm run typecheck (also run by npm run build) runs tsc --noEmit. Because every GraphQL document is typed from the schema, using a field that is not in the query fails here.

2. Codegen as a schema check

npm run codegen reads the live schema from GRAPHQL_URL (default http://localhost:4000/graphql) and validates every graphql() document against it. An unknown field, a wrong argument type or a duplicate operation name fails the run and writes nothing. Run it after any server schema change, then commit src/graphql/generated/.

3. Unit tests

npm test (vitest) covers the pure logic: URL parsing and where/sort building for movies and people (src/lib/*.test.ts), form validation and mutation inputs including the relationship diff (src/forms/model.test.ts), and the poster generator. They need no server or browser.

4. Browser end-to-end checks

npm run e2e drives real Chrome against the running stack and checks 78 behaviours, including create, edit and delete with the stored film counts. Setup, variables and caveats are in e2e/README.md. In short: run it against a freshly seeded database, because it expects the sample data.

Continuous integration

.github/workflows/ci.yml runs install, typecheck, unit tests and a build, then builds the Docker image. Codegen and the browser checks need a running server and are not in CI yet.

When a check fails

  • codegen fails with Cannot query field "x" on type "Y": the server schema does not have the field; check the server is running the version you expect.
  • A query works in GraphiQL but codegen reports Variable "$x" of type "T" used in position expecting type "T!": the variable must be declared non-null where it is used in a non-null position.
  • e2e fails on counts: the database is not the freshly seeded sample.

Source: grandstack-web/docs/testing.md (this page is a copy; edit it in the repository)