Add resource tests#

Steps#

1. Add an entry to your RESOURCE_NAME.yaml file’s samples list. Each sample can contain multiple steps. The first step will generate a create test, and any subsequent steps will generate update tests. For a comprehensive reference, see MMv1 sample reference ↗.

   When defining variables for your steps, follow these guidelines:

   • Use resource_id_vars for resource identifiers (like names or IDs) that need to be unique. Values automatically receive a tf-test prefix and random suffix, unless they contain an underscore _, in which case they receive a tf_test prefix and random suffix. If a resource name doesn’t support hyphens - or underscores _, use test_vars_overrides instead. For non-identifier variables, use vars.
   • Use vars only for fields that vary between steps (for example, to test the update functionality of specific fields).
   • Hardcode all other values directly in the .tf.tmpl configuration file. Don’t use vars for values that remain constant across all steps.

   samples:
     # name is used to generate the test name.
     - name: "pubsub_topic_update"
       # primary_resource_id will be used for the Terraform resource id in the configuration file.
       primary_resource_id: "default"
       # min_version can be set at the top level if it applies to all steps.
       min_version: beta
       steps:
         # The first step defines the initial create configuration.
         # Step name: Matches the template file name by default (for example, pubsub_topic_minimal.tf.tmpl). Use config_path to override this.
         - name: "pubsub_topic_minimal" 
           # resource_id_vars contains key/value pairs to inject into the configuration file.
           # These can be referenced as a key inside `{{$.ResourceIdVars}}`.
           resource_id_vars:
             resource_name: "example-resource"
             network_name: "example-network"
           # test_vars_overrides contains literal overrides for variables in tests.
           test_vars_overrides:
             network_name: 'servicenetworking.BootstrapSharedServiceNetworkingConnection(t, "pubsub-topic-network-config")'
         # Subsequent steps define update configurations.
         - name: "pubsub_topic_full"
           resource_id_vars:
             resource_name: "example-resource"
             network_name: "example-network"
           test_vars_overrides:
             network_name: 'servicenetworking.BootstrapSharedServiceNetworkingConnection(t, "pubsub-topic-network-config")'
           # vars should ONLY be used for fields that vary between steps.
           # Fields that stay constant across steps should be hardcoded in the .tf.tmpl file.
           vars: 
             display_name: "Display Name"
         - name: "pubsub_topic_full"
           resource_id_vars:
             resource_name: "example-resource"
             network_name: "example-network"
           test_vars_overrides:
             network_name: 'servicenetworking.BootstrapSharedServiceNetworkingConnection(t, "pubsub-topic-network-config")'
           vars:
             display_name: "Updated Display Name" # The new value for the updatable field

2. Create one or more .tf.tmpl files in mmv1/templates/terraform/samples/services/SERVICE_NAME/. The file names should match the step name (for example, pubsub_topic_minimal.tf.tmpl and pubsub_topic_full.tf.tmpl).

3. In those files, write the Terraform configuration for your test steps. This should include all required dependencies.

pubsub_topic_minimal.tf.tmpl:

resource "google_pubsub_topic" "{{.PrimaryResourceId}}" {
  name          = "{{index $.ResourceIdVars "resource_name"}}"
  network       = google_compute_network.network.name

  labels = {
    env = "test"
  }
}

resource "google_compute_network" "network" {
  name                    = "{{index $.ResourceIdVars "network_name"}}"
  auto_create_subnetworks = false
  routing_mode            = "REGIONAL"
}

pubsub_topic_full.tf.tmpl: (This file added the display_name variable).

resource "google_pubsub_topic" "{{.PrimaryResourceId}}" {
  name          = "{{index $.ResourceIdVars "resource_name"}}"

  # This is an example of a field whose value changes between steps
  # to test update functionality of display_name
  display_name  = "{{index $.Vars "display_name"}}"
  
  # The rest of the fields can be baked in the configuration directly
  message_retention_duration = "86600s"
  labels = {
    env = "test"
  }
  
  network       = google_compute_network.network.name
}

resource "google_compute_network" "network" {
  name                    = "{{index $.ResourceIdVars "network_name"}}"
  auto_create_subnetworks = false
  routing_mode            = "REGIONAL"
}

4. For beta-only resources or features:
   • If the resource or the whole test is beta-only
     • Add provider = google-beta to every resource in the file.
     • Add min_version: beta at the top sample level
   • If only a single test step is beta-only
     • Add min_version: beta at the individual step level

This workflow is an alternative for when the recommended samples generator framework is insufficient (for example, when you require a custom CheckFunction or other complex test assertions).

An update test ensures that updatable fields can be changed without recreating the entire resource. All updatable fields must be covered by at least one update test (often a single update step covering all fields is sufficient).

1. Generate the beta provider.
2. From the beta provider, copy and paste the generated *_generated_test.go file into the appropriate service folder inside magic-modules/mmv1/third_party/terraform/services as a new file call *_test.go.
3. Using an editor of your choice, delete the *DestroyProducer function, and all but one test. The remaining test should be the “full” test, or if there is no “full” test, the “basic” test. This will be the starting point for your new update test.
4. Modify the TestAcc* test function to support updates.
   • Change the suffix of the test function to _update.
   • Copy the 2 TestStep blocks and paste them immediately after, so that there are 4 total test steps.
   • Change the suffix of the first Config value to _full (or _basic).
   • Change the suffix of the second Config value to _update.
   • Add ConfigPlanChecks to the update step of the test to ensure the resource is updated in-place.
   • The resulting test function would look similar to this:

   import "github.com/hashicorp/terraform-plugin-testing/plancheck"
   
   func TestAccPubsubTopic_update(t *testing.T) {
      ...
      acctest.VcrTest(t, resource.TestCase{
         ...
         Steps: []resource.TestStep{
            {
               Config: testAccPubsubTopic_full(...),
            },
            {
               ...
            },
            {
               Config: testAccPubsubTopic_update(...),
               ConfigPlanChecks: resource.ConfigPlanChecks{
                  PreApply: []plancheck.PlanCheck{
                     plancheck.ExpectResourceAction("google_pubsub_topic.foo", plancheck.ResourceActionUpdate),
                  },
               },
            },
            {
               ...
            },
         },
      })
   }

5. Modify the testAcc* Terraform template function to support updates.
   • Copy the template function and paste it immediately after so that there are 2 template functions.
   • Change the suffix of the first template function to _full (or _basic).
   • Change the suffix of the second template function to _update.
   • The resulting template functions would look similar to this:

   func testAccPubsubTopic_full(...) string {
       ...
   }
   
   func testAccPubsubTopic_update(...) string {
       ...
   }

6. Modify the test as needed.
   • Replace all occurrences of github.com/hashicorp/terraform-provider-google-beta/google-beta with github.com/hashicorp/terraform-provider-google/google
   • Modify the template function ending in _update so that updatable fields are changed or removed. This may require additions to the context map in the test function.
   • Remove the comments at the top of the file.
   • If beta-only fields are being tested, do the following:
     • Change the file suffix to .go.tmpl
     • Wrap each beta-only test in a separate version guard: {{- if ne $.TargetVersionName "ga" -}}...{{- else }}...{{- end }}
     • In each beta-only test, ensure that the TestCase sets ProtoV5ProviderFactories: acctest.ProtoV5ProviderBetaFactories(t)
     • In each beta-only test, ensure that all Terraform resources in all configs have provider = google-beta set

Skipping acceptance tests that are generated from example files can be achieved by adding skip_vcr: true in the example’s YAML:

samples:
- name: 'bigtable_app_profile_anycluster'
   ...

   # bigtable instance does not use the shared HTTP client, this test creates an instance
   skip_vcr: true
   steps:
     - name: service_resource_basic

If you skip a test in VCR mode, include a code comment explaining the reason for skipping (for example, a link to a GitHub issue.)

Skipping acceptance tests that are handwritten can be achieved by adding acctest.SkipIfVcr(t) at the start of the test:

func TestAccPubsubTopic_update(t *testing.T) {
      acctest.SkipIfVcr(t) // See: https://github.com/hashicorp/terraform-provider-google/issues/9999
      acctest.VcrTest(t, resource.TestCase{ ... })
}

If you skip a test in VCR mode, include a code comment explaining the reason for skipping (for example, a link to a GitHub issue.)

Skipping acceptance tests that are generated from example files can be achieved by adding skip_func: acctest.SkipTestUntil(t, "YYYY-MM-DD") in the example’s YAML:

samples:
- name: 'compute_address_basic'
   ...
  skip_func: acctest.SkipTestUntil(t, "2026-01-31")  # waiting for rollout
  steps:
    - name: service_resource_basic

Skipping acceptance tests that are handwritten can be achieved by adding acctest.SkipTestUntil(t, "YYYY-MM-DD") at the start of the test:

func TestAccPubsubTopic_update(t *testing.T) {
      acctest.SkipTestUntil(t, "2026-01-31") // b/1234567890
      acctest.VcrTest(t, resource.TestCase{ ... })
}