From 86a77164095f92b25324a0256c4efb7c5637634d Mon Sep 17 00:00:00 2001 From: "Stephen Lewis (Burrows)" Date: Tue, 8 Oct 2024 14:09:58 -0700 Subject: [PATCH] Added information about VCR tests (#11943) --- docs/content/contribute/create-pr.md | 3 ++- docs/content/develop/test/test.md | 7 +++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/content/contribute/create-pr.md b/docs/content/contribute/create-pr.md index 3b2617016c25..4c8c24b95138 100644 --- a/docs/content/contribute/create-pr.md +++ b/docs/content/contribute/create-pr.md @@ -17,8 +17,9 @@ weight: 10 ## Code review 1. A reviewer will automatically be assigned to your PR. -1. Creating a new pull request or pushing a new commit automatically triggers our CI pipelines and workflows. After CI starts, downstream diff generation takes about 10 minutes; VCR tests can take up to 2 hours. If you are a community contributor, some tests will only run after approval from a reviewer. +1. Creating a new pull request or pushing a new commit automatically triggers our CI pipelines and workflows. After CI starts, downstream diff generation takes about 10 minutes; [VCR tests]({{< ref "/develop/test/test.md" >}}) can take up to 2 hours. If you are a community contributor, some tests will only run after approval from a reviewer. - While convenient, relying on CI to test iterative changes to PRs often adds extreme latency to reviews if there are errors in test configurations or at runtime. We **strongly** recommend you [test your changes locally before pushing]({{< ref "/develop/test/run-tests" >}}) even after the initial change. + - VCR tests will first attempt to play back recorded HTTP requests (REPLAYING mode). If any tests fail, they will run in RECORDING mode to generate a new cassette; then, the same tests will run again in REPLAYING mode to detect any nondeterministic behavior in the test (which can cause flaky tests.) 1. If your assigned reviewer does not respond to changes on a pull request within two US business days, ping them on the pull request. {{< hint info >}} diff --git a/docs/content/develop/test/test.md b/docs/content/develop/test/test.md index 38754fdff36a..69f97e9dd679 100644 --- a/docs/content/develop/test/test.md +++ b/docs/content/develop/test/test.md @@ -15,6 +15,13 @@ aliases: This page describes how to add tests to a new resource in the `google` or `google-beta` Terraform provider. +The providers have two basic types of tests: + +- Unit tests: test specific functions thoroughly. Unit tests do not interact with GCP APIs. +- Acceptance tests (aka VCR tests, or create and update tests): test that resources interact as expected with the APIs. Acceptance tests interact with GCP APIs, but should only test the provider's behavior in constructing the API requests and parsing the responses. + +Acceptance tests are also called "VCR tests" because they use [`go-vcr`](https://github.com/dnaeon/go-vcr) to record and play back HTTP requests. This allows tests to run more quickly on PRs because the resources don't actually need to be created, updated, or destroyed by the live API. + For more information about testing, see the [official Terraform documentation](https://developer.hashicorp.com/terraform/plugin/sdkv2/testing/acceptance-tests). ## Before you begin