You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- `name`: snake_case name of the example. This corresponds to the configuration file in
363
+
[mmv1/templates/terraform/examples](https://github.com/GoogleCloudPlatform/magic-modules/tree/main/mmv1/templates/terraform/examples) (excluding the `.go.tmpl` suffix) and is used to generate the test name and the documentation header.
364
+
- `primary_resource_id`: The id of the resource under test. This is used by tests to automatically run additional checks.
365
+
Configuration files should reference this to avoid getting out of sync. For example:
- `bootstrap_iam`: specify member/role pairs that should always exist. `{project_number}` will be replaced with the
368
+
default project's project number. This avoids race conditions when modifying the IAM permissions for the default test project.
369
+
Permissions attached to resources created _in_ a test should instead be provisioned with standard terraform resources.
370
+
- `vars`: Key/value pairs of variables to inject into the configuration file. These can be referenced in the configuration file
371
+
with `{{index $.Vars "key"}}`. All resource IDs (even for resources not under test) should be declared with variables that
372
+
contain a `-` or `_`; this will ensure that, in tests, the resources are created with a `tf-test` prefix to allow automatic cleanup of dangling resources and a random suffix to avoid name collisions.
373
+
- `test_env_vars`: Key/value pairs of variable names and special values indicating variables that should be pulled from the
374
+
environment during tests. These will receive a neutral default value in documentation. Common special values include:
375
+
`PROJECT_NAME`, `REGION`, `ORG_ID`, `BILLING_ACCT`, `SERVICE_ACCT` (the test runner service account).
376
+
- `test_vars_overrides`: Key/value pairs of literal overrides for variables used in tests. This can be used to call functions to
377
+
generate or determine a variable's value.
378
+
- `min_version`: Set this to `beta` if the resource is in the `google` provider but the example will only work with the
379
+
`google-beta`provider (for example, because it includes a beta-only field.)
380
+
- `ignore_read_extra`: Properties to not check on import. This should be used in cases where a property will not be set on import,
381
+
for example write-only fields.
382
+
- `exclude_test`: If set to `true`, no test will be generated based on this example.
383
+
- `exclude_docs`: If set to `true`, no documentation will be generated based on this example.
384
+
- `exclude_import_test`: If set to `true`, no import test will be generated for this example.
385
+
- `skip_vcr`: See [Skip tests in VCR replaying mode]({{< ref "/test/test#skip-vcr" >}}) for more information about this flag.
386
+
- `skip_test`: If not empty, the test generated based on this example will always be skipped. In most cases, the value should be a
387
+
link to a ticket explaining the issue that needs to be resolved before the test can be unskipped.
388
+
- `external_providers`: A list of external providers that are needed for the testcase. This does add some latency to the testcase,
389
+
so only use if necessary. Common external providers: `random`, `time`.
Copy file name to clipboardExpand all lines: docs/content/test/test.md
+33-35
Original file line number
Diff line number
Diff line change
@@ -46,27 +46,37 @@ A create test is a test that creates the target resource and immediately destroy
46
46
47
47
{{< tabs "create" >}}
48
48
{{< tab "MMv1" >}}
49
-
1. Using an editor of your choice, create a `*.tf.tmpl` file in [`mmv1/templates/terraform/examples/`](https://github.com/GoogleCloudPlatform/magic-modules/tree/main/mmv1/templates/terraform/examples). The name of the file should include the service name, resource name, and a descriptor. For example, `compute_subnetwork_basic.tf.tmpl`.
50
-
2. Write the Terraform configuration for your test. This should include all of the required dependencies. For example, `google_compute_subnetwork` has a dependency on `google_compute_network`:
51
-
```tf
52
-
resource "google_compute_subnetwork" "primary" {
53
-
name = "my-subnet"
54
-
ip_cidr_range = "10.1.0.0/16"
55
-
region = "us-central1"
56
-
network = google_compute_network.network.name
57
-
}
58
-
59
-
resource "google_compute_network" "network" {
60
-
name = "my-network"
61
-
auto_create_subnetworks = false
62
-
}
49
+
1. Add an entry to your `RESOURCE_NAME.yaml` file's `examples`. The fields listed here are the most commonly-used. For a comprehensive reference, see [MMv1 resource reference: `examples` ↗]({{<ref "/reference/resource#examples" >}}).
50
+
```yaml
51
+
examples:
52
+
# name must correspond to a configuration file that you'll create in the next step.
53
+
# The name should include the product name, resource name, and a basic description
54
+
# of the test. This will be used to generate the test name and the documentation
55
+
# header.
56
+
- name: "PRODUCT_RESOURCE_basic"
57
+
# primary_resource_id will be used for the Terraform resource id in the configuration file.
58
+
primary_resource_id: "example"
59
+
# vars contains key/value pairs of variables to inject into the configuration file.
60
+
# These can be referenced in the configuration file as a key inside `{{$.Vars}}`.
61
+
# All resource IDs (even for resources not under test) should be declared
62
+
# with variables that contain a `-` or `_`; this will ensure that, in tests,
63
+
# the resources are created with a `tf-test` prefix to allow automatic cleanup
64
+
# of dangling resources and a random suffix to avoid name collisions.
65
+
vars:
66
+
network_name: "example-network"
67
+
# test_vars_overrides contains key/value pairs of literal overrides for
68
+
# variables used in tests. This can be used to call functions to
69
+
# generate or determine a variable's value – for example, bootstrapping
70
+
# a shared network for your product to avoid test failures due to limits
# Set min_version: beta if the resource is not beta-only and any beta-only fields are being tested.
75
+
min_version: beta
63
76
```
64
-
3. If beta-only fields are being tested:
65
-
- Add `provider = google-beta` to every resource in the file.
66
-
4. Modify the configuration to use templated values.
67
-
- Replace the id of the primary resource you are testing with `{{$.PrimaryResourceId}}`.
68
-
- Replace fields that are identifiers, like `id` or `name`, with an appropriately named variable. For example, `{{index $.Vars "subnetwork_name"}}`.
69
-
- The resulting configuration for the above example would look like this:
77
+
78
+
2. Create a `.tf.tmpl` file in [`mmv1/templates/terraform/examples/`](https://github.com/GoogleCloudPlatform/magic-modules/tree/main/mmv1/templates/terraform/examples). The name of the file should match the name of the example created in the previous step. For example, `PRODUCT_RESOURCE_basic.tf.tmpl`.
79
+
3. In that file, write the Terraform configuration for your test. This should include all of the required dependencies. For example, `google_compute_subnetwork` has a dependency on `google_compute_network`:
@@ -80,20 +90,8 @@ A create test is a test that creates the target resource and immediately destroy
80
90
auto_create_subnetworks = false
81
91
}
82
92
```
83
-
5. Modify the relevant `RESOURCE_NAME.yaml` file under [magic-modules/mmv1/products](https://github.com/GoogleCloudPlatform/magic-modules/tree/main/mmv1/products) to include an [`examples`](https://github.com/GoogleCloudPlatform/magic-modules/blob/main/mmv1/api/resource/examples.go) block with your test. The `name` must match the name of your `*.tf.tmpl` file. For example:
84
-
```yaml
85
-
examples:
86
-
- name: "compute_subnetwork_basic"
87
-
primary_resource_id: "example"
88
-
vars:
89
-
subnetwork_name: "example-subnet"
90
-
network_name: "example-network"
91
-
```
92
-
{{< hint warning >}}
93
-
**Warning:** Values in `vars` must include a `-` (or `_`). They [trigger the addition of a `tf-test` prefix](https://github.com/GoogleCloudPlatform/magic-modules/blob/main/mmv1/api/resource/examples.go#L224), which the sweeper uses to clean them up after tests run.
94
-
{{< /hint >}}
95
-
6. If beta-only fields are being tested:
96
-
- Add `min_version: 'beta'` to the `examples` block in `RESOURCE_NAME.yaml`.
93
+
4. If the resource or the example is beta-only:
94
+
- Add `provider = google-beta` to every resource in the file.
97
95
{{< /tab >}}
98
96
{{< tab "Handwritten" >}}
99
97
This section assumes you've used the [Add a resource]({{< ref "/develop/add-resource" >}}) guide to create your handwritten resource, and you have a working MMv1 config.
Acceptance tests are run in VCR replaying mode on PRs (using pre-recorded HTTP requests and responses) to reduce the time it takes to present results to contributors. However, not all resources or tests are possible to run in replaying mode. Incompatible tests should be skipped during VCR replaying mode. They will still run in our nightly test suite.
0 commit comments