メニュー
Classification decision tree and remediation strategies for diagnosing Terraform acceptance test failures across all workflows.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SOC 職業分類に基づく
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/GoogleCloudPlatform/magic-modules --skill test-failure-decision-treeコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
Plan a remediation strategy after a test failure.
Workflow for triaging, planning, fixing, and verifying reported provider bugs.
Opt resource into MMv1 list-resource generation by setting `generate_list_resource: true` and validate it locally with generated tests. Invoke when the user asks to add list-resource support for a specific MMv1 resource or to enable `generate_list_resource` for an eligible resource.
| name | test-failure-decision-tree |
| description | Classification decision tree and remediation strategies for diagnosing Terraform acceptance test failures across all workflows. |
test-failure-decision-treeThis document provides a standardized classification catalog for diagnosing, isolating, and fixing failing Terraform acceptance tests in magic-modules. It is designed to be consulted by any workflow (test_fix, new_resource, add_list_resource, default) whenever make testacc fails.
Every Terraform resource and acceptance test in magic-modules is either Generated (MMv1) or Handwritten (Go overrides) as documented in docs/content/test/test.md. Before applying any remediation recipe in this catalog, always verify whether the source is generated (schemas in mmv1/products/, tests in mmv1/templates/terraform/samples/) or handwritten (Go code and tests in mmv1/third_party/terraform/services/) so you edit the correct source files. Consult docs/content/develop/diffs.md for diff resolutions, docs/content/test/test.md for test conventions, and docs/content/test/run-tests.md for compilation and execution guides.
For generated acceptance tests (MMv1 samples in mmv1/templates/terraform/samples/), Magic Modules automatically generates test function names (TestAcc...) during make provider.
However, when adding any new handwritten Go test function (resource_PRODUCT_RESOURCE_test.go or other *_test.go files under mmv1/third_party/terraform/services/<service>/), always verify that the test function name matches its execution tier:
Test<FunctionName> (e.g., TestDiscoveryEngineSearchEngineFeaturesDiffSuppress) without the TestAcc prefix.TestAcc<Resource>_<Scenario>.TestAcc is strictly reserved for acceptance tests run via make testacc. Naming a handwritten unit test with TestAcc causes it to be filtered out of standard unit test runs and misclassified by CI.
| Scenario ID | Symptom / Error Pattern | Root Cause Category | Primary File Location & Remedy |
|---|---|---|---|
| Scenario 1 | gRPC Code 8 (RESOURCE_EXHAUSTED) / HTTP 429 (Quota limit exceeded/Quota exhausted), gRPC Code 13 (INTERNAL) / Code 14 (UNAVAILABLE) / HTTP 500/502/503 (An internal error has occurred), or API backend crash | Non-Remediable GCP Backend / Quota Environment Error | Early Exit & Handoff: Do NOT edit magic-modules. Report failure as a GCP service-side internal error or test environment quota exhaustion requiring human investigation by the Terraform team. (Excludes HTTP 403 SERVICE_DISABLED -> see Scenario 8) |
| Scenario 2 | State drift, ImportStateVerify mismatch, non-empty plan after Apply, or server-injected metadata diffs (e.g. run.googleapis.com/...) | State Normalization / Default Mismatch / Server-Injected Annotation | Edit product YAML mmv1/products/<product>/<Resource>.yaml (for generated resources) or edit handwritten Go code mmv1/third_party/terraform/services/<service>/resource_<resource_name>.go (for handwritten resources) to add diff suppress (including regex suppression), adjust state reader, or handle defaults |
| Scenario 3 | HTTP 400 InvalidArgument, Unknown Field, or field serialization error | API Request Payload Schema Mismatch | Compare POST request JSON against API proto schema; fix field camelCase/snake_case mapping, decoder/expander, or send_empty_value |
| Scenario 4 | HTTP 404 immediately post-Create, eventual consistency delay, or 409 conflict | LRO / Eventual Consistency Timing | Configure async: / autogen_async in YAML, add retry handlers (transport_tpg.SendRequestWithTimeout), or polling waiter logic in handwritten overrides |
RESOURCE_EXHAUSTED / Quota limit exceeded / HTTP 429), or internal errors (gRPC Code 13 INTERNAL / Code 14 UNAVAILABLE / HTTP 500/502/503).
INTERNAL) or HTTP 500 error as a non-remediable Scenario 1 crash, inspect the error message carefully. If the message references specific schema fields, parameters, or value constraints (e.g. invalid value, missing field foo, cannot be parsed), it is likely a client-side payload error that triggered a backend crash. Classify it as Scenario 3 (Payload Mismatch) instead of exiting.SERVICE_DISABLED or API Not Enabled errors as Scenario 1; those must be classified as Scenario 8 (API Service Not Enabled) for automated remediation.magician), Quota errors are classified as Terraform Team Owned Errors (teamOwnedErrorTypes: "Quota"), which automatically label tickets with service/terraform and assign them to the Release Shepherd.magic-modules. Report failure to human maintainers as a non-remediable test environment or service-side error.stdout plan diff, and outline.txt.docs/content/develop/diffs.md for tabbed code examples of MMv1 and Handwritten diff suppression, default values, and ignore_read.default_from_api: true): For existing/dynamic fields where the API returns a server-side default if unset, set default_from_api: true in product YAML (converts to Optional: true, Computed: true in schema).default_value: ...): Use default_value only for static, stable default values that match the API default.default_if_empty.tmpl): If the API returns empty/nil when default value is sent, use custom_flatten: 'templates/terraform/custom_flatten/default_if_empty.tmpl' (or check v == nil || IsEmptyValue in handwritten flatteners).diff_suppress_func):
tpgresource.CaseDiffSuppress for capitalization normalization differences.tpgresource.DurationDiffSuppress for duration format differences ("60.0s" vs "60s" for google.protobuf.Duration fields).tpgresource.ProjectNumberDiffSuppress for project ID vs project number diffs.ignore_read: true): For fields never returned in GET responses (passwords, secrets), set ignore_read: true and sensitive: true in YAML. In handwritten tests, set flattened value from d.Get(...) and add the field to ImportStateVerifyIgnore.tpgresource.SortStringsByConfigOrder or tpgresource.SortMapsByConfigOrder so API response ordering matches user config order.DiffSuppressFunc: EmptyOrDefaultStringSuppress(...) if it suppresses configured values on resource creation, causing state drift.01_POST_request.json against the GCP REST/gRPC schema or inspect custom decoder logic.api_name vs name).send_empty_value: true if empty strings/zero-values are required by the API.templates/terraform/decoders/ or templates/terraform/expanders/ if array indexing or struct mapping corrupts request payloads or state.POST and subsequent GET requests in outline.txt, or inspect 409/404 retry backtraces.autogen_async: true and async: settings in YAML for long-running operations.templates/terraform/post_create/sleep.go.tmpl, sleep_2_min.go.tmpl, or sleep_5_min.go.tmpl in custom_code.post_create to allow API propagation.transport_tpg.SendRequestWithTimeout / time.Sleep) in handwritten overrides (mmv1/third_party/terraform/services/<service>/).mmv1/templates/terraform/samples/<service>/<sample>.tf.tmpl) or Handwritten (mmv1/third_party/terraform/services/<service>/<resource>_test.go).target_provider: "ga") with a lockfile/provider error (e.g. provider registry.terraform.io/hashicorp/google-beta: required by this configuration), or if the tested resource has min_version: beta in mmv1/products/<product>/<Resource>.yaml, immediately check if the handwritten test file in mmv1/third_party/terraform/services/<product>/ is named *.go instead of *.go.tmpl. Do NOT attempt to promote the resource to GA or modify provider HCL blocks.docs/content/test/test.md for tabbed code examples of MMv1 and Handwritten test naming, randomization, dependency bootstrapping, and VCR mode skipping.{{index $.ResourceIdVars "var_name"}}.resource_id_vars in the resource's product YAML (mmv1/products/<product>/<Resource>.yaml) to generate unique per-test identifiers.bootstrap_iam in YAML for project/org IAM bindings; use kms.BootstrapKMSKey(t) for KMS keys; use tpgcompute.BootstrapSharedTestNetwork(t, "identifier") for networks.skip_vcr: true for tests incompatible with HTTP recording. Set skip_func: acctest.SkipTestUntil(t, "YYYY-MM-DD") for unreleased features.acctest.RandString(t, 10) in test contexts ("instance_name": fmt.Sprintf("tf-test-%s", acctest.RandString(t, 10))) or %{random_suffix} variables.kms.BootstrapKMSKey(t), tpgcompute.BootstrapSharedTestNetwork(t, ...), and .oggoracle:21.18... or deprecated image families)..tf.tmpl or handwritten test context maps to valid, active supported versions.Error 403: ... API has not been used in project ... before or it is disabled) targets our shared CI test project (ci-test-project-nightly-ga, ci-test-project-nightly-beta, or standard shared test runner project) versus a secondary or custom test project created within the test itself.magician), API enablement errors are classified as Terraform Team Owned Errors (teamOwnedErrorTypes: "API enablement (Test environment)"), which automatically label tickets with service/terraform and assign them to the Release Shepherd.ci-test-project-nightly-ga / ci-test-project-nightly-beta): Automatically execute gcloud services enable <service.googleapis.com> --project=<ci-project> via run_command to enable the API directly in the target CI project. Do not modify test code in magic-modules for shared CI project API enablement.mmv1/templates/terraform/samples/<service>/<sample>.tf.tmpl or handwritten Go test mmv1/third_party/terraform/services/<service>/<resource>_test.go.tmpl) to include a google_project_service resource or call test bootstrapping helper functions (EnableServiceUsageProjectServices / bootstrap_test_utils) so that the Terraform test itself enables the required API in that project.When a new failure pattern is identified:
| Scenario 5 | Resource name collision (alreadyExists), static string reuse, or test dependency setup bug | Acceptance Test Naming & Setup Bug | Edit sample .tf.tmpl + resource YAML (for generated tests) or edit Go test .go (for handwritten tests) to use dynamic random strings and bootstrap dependencies |
| Scenario 6 | HTTP 400 InvalidParameter: ... Not valid version or outdated image/version string | Outdated / Deprecated API Parameter Version | Update outdated version strings in sample .tf.tmpl or handwritten test context maps to currently supported API versions |
| Scenario 7 | HTTP 400 managedZoneDnsNameNotAvailable or domain allocation limit error across concurrent tests | Shared Resource / Domain Allocation Conflict | Consolidate multiple separate test functions into a single acceptance test function that reuses the managed domain/resource |
| Scenario 8 | HTTP 403 SERVICE_DISABLED or error indicating API service has not been used in project before / is disabled | API Service Not Enabled in Target Project | For shared CI test projects (ci-test-project-nightly-ga/beta): run gcloud services enable <service.googleapis.com> --project=<ci-project>. For test-created or secondary projects: use Terraform resources (google_project_service / Go bootstrap utilities) in test config. |
run.googleapis.com/...-disabled or default feature flags):
ignore_read: true on KeyValuePairs / map attributes, as that disables drift detection for legitimate user-initiated modifications.diff_suppress_func in custom_code.constants (constants/<resource>.go.tmpl) that returns true when the key matches a server-provided key AND new == "", and also returns true for the map item count delta (strings.Contains(k, "map_field.%")). For all other keys or explicit user modifications (new != ""), return false.custom_code): When adding constants: or other hooks to product YAML files, check if a custom_code: block already exists (e.g. for encoder:/decoder:). Merge into the existing block instead of adding a duplicate custom_code: root key.mmv1/third_party/terraform/services/<service>/resource_<resource_name>.go), directly edit the schema definition or CRUD method implementation in the Go file to add DiffSuppressFunc, adjust the Read function, or handle defaults in the resource map.resourcemanager.BootstrapIamMembers(t, ...)acctest.SkipIfVcr(t) or acctest.SkipTestUntil(t, "YYYY-MM-DD").min_version: beta), rename the file from .go to .go.tmpl and wrap the test implementation with {{ if ne $.TargetVersionName "ga" }} ... {{ end }} (do not generate an {{ else }} placeholder comment in GA).