From 046f5313142db4cd368392c391bb0938749f32bb Mon Sep 17 00:00:00 2001 From: Ben Kraft Date: Thu, 28 Jul 2022 16:31:55 -0700 Subject: [PATCH] Add more information about updating snapshots (#211) The generated files for integration tests aren't strictly snapshots and so `UPDATE_SNAPSHOTS=1` won't work (maybe we should make it work?). Instead you also need to `go generate ./...`. This came up in #209. --- docs/CONTRIBUTING.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 13c5728..d8147a3 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -35,11 +35,15 @@ Go style should generally follow the conventions of [Effective Go](https://golan To run tests and lint, `make check`. (GitHub Actions also runs them.) Notes for contributors: -- Most of the tests are snapshot-based; see `generate/generate_test.go`. All new code-generation logic should be snapshot-tested. Some code additionally has standalone unit tests, when convenient. The snapshot tests use [cupaloy](https://github.com/bradleyjkemp/cupaloy); to update the snapshots run e.g. `UPDATE_SNAPSHOTS=1 go test ./...`. +- Most of the tests are snapshot-based; see `generate/generate_test.go`. All new code-generation logic should be snapshot-tested. Some code additionally has standalone unit tests, when convenient. - Integration tests run against a gqlgen server in `internal/integration/integration_test.go`, and should cover everything that snapshot tests can't, including the GraphQL client code and JSON marshaling. - If `GITHUB_TOKEN` is available in the environment, it also checks that the example returns the expected output when run against the real API. This is configured automatically in GitHub Actions, but you can also use a [personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with no scopes. There's no need for this to cover anything in particular; it's just to make sure the example in fact works. - Tests should use `testify/assert` and `testify/require` where convenient (when making many simple assertions). +If you update any code-generation logic or templates, even if no new tests are needed you'll likely need to: +- Run `UPDATE_SNAPSHOTS=1 go test ./...` to update the [cupaloy](https://github.com/bradleyjkemp/cupaloy) snapshots. +- Run `go generate ./...` to update the genqlient-generated files used in integration tests and documentation. + ## Finding your way around If you're new to genqlient, start out by reading the source of `generate.Generate`, whose comments describe most of the high-level operation of genqlient. In general, the code is documented inline, often with an introductory comment at the top of the file. See [DESIGN.md](DESIGN.md) for documentation of major design decisions, which is a good way to get a sense of why genqlient is structured the way it is.