# Acceptance Test Patterns

> Best practices for writing and organizing acceptance and unit tests in this Terraform provider. Use when creating new tests, modifying existing tests, fixing flaky tests, or reviewing test code. Covers black-box test packages, test consolidation, avoiding duplicates, plural data source ordering, and plan-only validation tests.

- Skill: `mongodb/acceptance-test-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mongodb/acceptance-test-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mongodb/acceptance-test-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: mongodb (https://skillmd.com/u/mongodb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mongodb/acceptance-test-patterns

---


# Acceptance Test Patterns

## Test Organization and Black-Box Testing

Test types, file layout, and unit test rules are defined in [contributing/testing-best-practices.md](../../../contributing/testing-best-practices.md). Read it before adding or moving tests. Black-box testing is enforced there: tests live in a separate `_test` package and reach behavior through exported identifiers.

## Test Consolidation

### Combine Resource + Data Source Basic Tests

Merge basic tests for a resource, its singular data source, and its plural data source into a **single test function** in `resource_test.go`. This reduces CI time by avoiding repeated `terraform init/plan/apply` cycles for the same infrastructure.

### Eliminate Duplicate Tests

Before adding a test, verify no existing test already covers the same configuration and assertions. Tests with identical configs and checks waste CI time.

## Optional Attribute Lifecycle Coverage

For an optional attribute on a resource, cover the configuration lifecycle, not just the happy path with a value set:

- **Omitting the value**: a config that never sets the attribute must apply cleanly and produce an empty plan afterwards. This catches attributes where the API returns a default for an omitted value, which requires marking the attribute computed (for autogen resources, a `computability` override — see the `autogen-config` skill).
- **Unsetting the value**: an update step that removes the attribute from a config that previously set it — verify the intended behavior (value cleared vs. kept by the API) and that the plan converges.

## CheckExists / CheckDestroy for Autogen Resources

Autogen resources map directly from the OpenAPI spec and avoid typed Atlas SDK methods, calling the API through the SDK's untyped client instead. Their `checkExists` / `checkDestroy` should follow the same approach: verify against Atlas with an untyped client rather than a typed SDK method. Keep these check functions in the resource's own `resource_test.go`, since they are resource-specific. Issue the untyped request with the resource's version header (see the `apiVersionHeader` const in the resource’s `resource.go`). Promoting a preview API to stable then only requires bumping the version header, not a rewrite.

## Plural Data Source Ordering

Avoid hardcoded indices (e.g., `results.0`) when asserting on plural data source results unless the parent resource is guaranteed to be unique within the test execution. When uniqueness is ensured, using `results.0` is acceptable. Otherwise, the API may return items in any order and the test resource may not be at a predictable index.

### Preferred approach (when index is not safe)

1. **`PluralResultCheck` helper** — dynamically finds the test resource by name before asserting on its attributes.

## Plan-Only Tests for Validation

Use `PlanOnly: true` with `ExpectError` for tests that validate schema-level constraints (e.g., discriminator validation, required attribute enforcement). These are fast because they don't require real infrastructure.

```go
resource.TestStep{
    Config:      configWithMissingRequiredField,
    PlanOnly:    true,
    ExpectError: regexp.MustCompile(`expected error message`),
}
```

## Test Grouping in CI

- Autogenerated resource tests that run faster belong in the `autogen_fast` CI group.
- If a prod autogenerated resource's tests take significantly longer than the `autogen_fast` average, evaluate moving it to a separate test group.