Merge branch 'main' into james/oss-3296-interface-to-any

Author: james00012

README.md

@@ -22,7 +22,23 @@ variety of helper functions and patterns for common infrastructure testing tasks
 - Running shell commands
 - And much more
 
-Please see the following for more info:
+## Install
+
+```bash
+go get github.com/gruntwork-io/terratest@latest
+```
+
+Requires Go 1.26 or later.
+
+## Stability and versioning
+
+Starting with v1.0.0, Terratest follows [semantic versioning](https://semver.org/). Breaking changes to the public API
+only happen in major releases (e.g. v2.0.0).
+
+Symbols renamed or replaced in v1 are kept with `// Deprecated:` annotations pointing at the new name; removals happen
+in v2. Migrating from v0.x: see [`MIGRATION.md`](./MIGRATION.md).
+
+## More info
 
 - [Terratest Website](https://terratest.gruntwork.io)
 - [Getting started with Terratest](https://terratest.gruntwork.io/docs/getting-started/quick-start/)

docs/_docs/03_migrating-to-v1/azure.md

@@ -0,0 +1,227 @@
+---
+layout: collection-browser-doc
+title: Azure modules
+category: migrating-to-v1
+excerpt: >-
+  Migrate Azure tests from Terratest pre-v1 to v1.0.0.
+tags: ["azure", "migration", "v1"]
+order: 300
+nav_title: Documentation
+nav_title_link: /docs/
+---
+
+The `modules/azure` package received the largest set of breaking changes in
+the v1.0.0 release. This guide walks through what changed and how to update
+your tests.
+
+## Why we migrated
+
+The previous version of `modules/azure` was built on
+`github.com/Azure/azure-sdk-for-go/services/...`, the legacy "track 1" Azure
+SDK. Microsoft has archived that SDK; it no longer receives feature updates,
+bug fixes, or security patches.
+
+v1.0.0 moves the entire package to
+`github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/...`, the modular,
+actively maintained "track 2" SDK. The new SDK has a different shape: typed
+resource clients are produced by a `ClientFactory`, response payloads put
+most fields on a nested `Properties` struct, and pagination uses pagers
+instead of iterators. We took the opportunity to land a few small API
+cleanups at the same time so v1.0.0 ships a coherent, stable surface.
+
+## What changed at a glance
+
+- All Azure service code now imports `sdk/resourcemanager/<service>/arm<service>` packages instead of `services/<service>/mgmt/<api-version>/<service>`.
+- Resource fields moved under `.Properties` (e.g. `vm.StorageProfile` is now `vm.Properties.StorageProfile`).
+- Iterator-based list calls (`NextWithContext`) are replaced with pagers (`NewListPager` / `More` / `NextPage`).
+- 8 deprecated `Get*ClientE` client-getter functions were removed; the `Create*ClientE` replacements have been around for a while.
+- 4 `CreateNew*ClientContextE` factories were renamed to `Create*ClientContextE`. The old names remain as deprecated aliases.
+- `NsgRuleSummary.SourceAdresssPrefixes` (triple-s typo) was renamed to `SourceAddressPrefixes`.
+- A new `*WithClient` family of functions was added so tests can inject a fake or pre-built SDK client (useful with the Azure SDK's `azfake` package).
+- `GetVirtualMachineImage` / `GetVirtualMachineImageE` now return `*VMImage` instead of `VMImage`.
+
+## Updating SDK imports
+
+Most Terratest users do not import the underlying Azure SDK directly,
+because Terratest wraps it. If you only call `terratest/modules/azure`
+helpers, you can usually skip this section. If your tests do import the SDK
+(for example to construct request objects or assert on returned types),
+update imports as follows:
+
+| Old (`services/...`) | New (`sdk/resourcemanager/...`) |
+| --- | --- |
+| `github.com/Azure/azure-sdk-for-go/services/compute/mgmt/.../compute` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute/v6` |
+| `github.com/Azure/azure-sdk-for-go/services/network/mgmt/.../network` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/network/armnetwork/v6` |
+| `github.com/Azure/azure-sdk-for-go/services/storage/mgmt/.../storage` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storage/armstorage` |
+| `github.com/Azure/azure-sdk-for-go/services/cosmos-db/mgmt/.../documentdb` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos/v3` |
+| `github.com/Azure/azure-sdk-for-go/services/servicebus/mgmt/.../servicebus` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/servicebus/armservicebus/v2` |
+| `github.com/Azure/azure-sdk-for-go/services/preview/containerservice/.../containerservice` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/containerservice/armcontainerservice/v6` |
+| `github.com/Azure/azure-sdk-for-go/services/containerregistry/mgmt/.../containerregistry` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/containerregistry/armcontainerregistry` |
+| `github.com/Azure/azure-sdk-for-go/services/containerinstance/mgmt/.../containerinstance` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/containerinstance/armcontainerinstance/v2` |
+| `github.com/Azure/azure-sdk-for-go/services/preview/operationalinsights/.../operationalinsights` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/operationalinsights/armoperationalinsights/v2` |
+| `github.com/Azure/azure-sdk-for-go/services/resources/mgmt/.../subscriptions` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/resources/armsubscriptions` |
+| `github.com/Azure/azure-sdk-for-go/services/resources/mgmt/.../resources` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/resources/armresources` |
+| `github.com/Azure/azure-sdk-for-go/services/privatedns/mgmt/.../privatedns` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/privatedns/armprivatedns` |
+| `github.com/Azure/azure-sdk-for-go/profiles/latest/frontdoor/mgmt/frontdoor` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/frontdoor/armfrontdoor` |
+| `github.com/Azure/azure-sdk-for-go/profiles/preview/preview/monitor/mgmt/insights` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/monitor/armmonitor` |
+| `github.com/Azure/azure-sdk-for-go/services/recoveryservices/mgmt/.../recoveryservices` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/recoveryservices/armrecoveryservices` |
+| `github.com/Azure/azure-sdk-for-go/services/recoveryservices/mgmt/.../backup` | `github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/recoveryservices/armrecoveryservicesbackup/v4` |
+
+Once imports are updated, expect three follow-on edits per file:
+
+1. **Type names** lose their old prefix and gain `arm`. For example
+   `compute.VirtualMachine` becomes `armcompute.VirtualMachine`,
+   `network.SecurityGroup` becomes `armnetwork.SecurityGroup`, and
+   `storage.Account` becomes `armstorage.Account`.
+2. **Field access** moves under `.Properties`. For example
+   `vm.StorageProfile` becomes `vm.Properties.StorageProfile`, and
+   `registry.LoginServer` becomes `registry.Properties.LoginServer`.
+3. **List iteration** moves to the pager pattern: replace
+   `iterator.NextWithContext(ctx)` loops with
+   `for pager.More() { page, err := pager.NextPage(ctx); ... }`.
+
+## Renamed factory functions
+
+Four client factories were renamed to drop the redundant `New` (a
+`Create*New*Client` reads as redundant). The old names remain as deprecated
+aliases for one minor release; please update at your convenience.
+
+| Old name | New name |
+| --- | --- |
+| `CreateNewNetworkInterfacesClientE` | `CreateNetworkInterfacesClientE` |
+| `CreateNewNetworkInterfacesClientContextE` | `CreateNetworkInterfacesClientContextE` |
+| `CreateNewNetworkInterfaceIPConfigurationClientE` | `CreateNetworkInterfaceIPConfigurationClientE` |
+| `CreateNewNetworkInterfaceIPConfigurationClientContextE` | `CreateNetworkInterfaceIPConfigurationClientContextE` |
+| `CreateNewSubnetClientE` | `CreateSubnetClientE` |
+| `CreateNewSubnetClientContextE` | `CreateSubnetClientContextE` |
+| `CreateNewVirtualNetworkClientE` | `CreateVirtualNetworkClientE` |
+| `CreateNewVirtualNetworkClientContextE` | `CreateVirtualNetworkClientContextE` |
+
+## Removed deprecated functions
+
+The previous release marked eight client-getter functions for removal
+("`TODO: remove in next version`"). v1.0.0 is that version. Each removed
+function has a long-standing `Create*ClientE` replacement.
+
+| Removed | Replacement |
+| --- | --- |
+| `GetAvailabilitySetClientE` | `CreateAvailabilitySetClientE` |
+| `GetDiskClientE` | `CreateDisksClientE` |
+| `GetDiagnosticsSettingsClientE` | `CreateDiagnosticsSettingsClientE` |
+| `GetVMInsightsClientE` | `CreateVMInsightsClientE` |
+| `GetActivityLogAlertsClientE` | `CreateActivityLogAlertsClientE` |
+| `GetResourceGroupClientE` | `CreateResourceGroupClientE` |
+| `GetStorageAccountClientE` | `CreateStorageAccountClientE` |
+| `GetStorageBlobContainerClientE` | `CreateStorageBlobContainerClientE` |
+
+The replacements take the same arguments and return the same client type
+(now from the new SDK). The rename is mechanical: `Get` → `Create`. Note
+that `GetDiskClientE` becomes `CreateDisksClientE` (plural) to match the
+underlying SDK's `DisksClient` type.
+
+## Typo fix on `NsgRuleSummary`
+
+`NsgRuleSummary.SourceAdresssPrefixes` (note the three s's) was renamed to
+the correctly-spelled `SourceAddressPrefixes`. The field type
+(`[]string`) is unchanged. Update any code that read or set this field:
+
+```go
+// Before
+for _, prefix := range rule.SourceAdresssPrefixes {
+    // ...
+}
+
+// After
+for _, prefix := range rule.SourceAddressPrefixes {
+    // ...
+}
+```
+
+The paired `DestinationAddressPrefixes` field was already spelled
+correctly and is unchanged.
+
+## `VMImage` is now a pointer
+
+`GetVirtualMachineImage` and `GetVirtualMachineImageE` now return
+`*VMImage` instead of `VMImage`, matching every other resource getter in
+the package.
+
+```go
+// Before
+img := azure.GetVirtualMachineImage(t, vmName, rg, sub)
+fmt.Println(img.Publisher)
+
+// After
+img := azure.GetVirtualMachineImage(t, vmName, rg, sub)
+if img != nil {
+    fmt.Println(img.Publisher)
+}
+```
+
+If the resource cannot be loaded the function still fails the test, so
+the `nil` guard is precautionary.
+
+## New `WithClient` variants for testability
+
+v1.0.0 adds a parallel family of `*WithClient` functions across all Azure
+modules. Each one accepts a pre-built SDK client and a
+`context.Context`, so you can drive Terratest helpers against the Azure
+SDK's `azfake` fake-server framework in unit tests:
+
+```go
+import (
+    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute/v6"
+    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute/v6/fake"
+)
+
+// Build a fake client that returns a canned response.
+fakeServer := fake.DisksServer{ /* ... */ }
+client, _ := armcompute.NewDisksClient("sub-id", nil, &arm.ClientOptions{
+    ClientOptions: azcore.ClientOptions{
+        Transport: fake.NewDisksServerTransport(&fakeServer),
+    },
+})
+
+disk, err := azure.GetDiskWithClient(ctx, client, resourceGroup, diskName)
+```
+
+This is purely additive: the existing `*ContextE` functions still work and
+build their own clients from ambient credentials. Use `WithClient`
+variants only if you need test injection.
+
+## Search-and-replace cheatsheet
+
+Most projects can do the bulk of the migration with a few find/replace
+passes. The snippets below cover the most common edits:
+
+```bash
+# Removed Get*ClientE functions -> Create*ClientE
+sd 'GetAvailabilitySetClientE\b'      'CreateAvailabilitySetClientE'      $(rg -l 'GetAvailabilitySetClientE')
+sd 'GetDiskClientE\b'                 'CreateDisksClientE'                $(rg -l 'GetDiskClientE')
+sd 'GetDiagnosticsSettingsClientE\b'  'CreateDiagnosticsSettingsClientE'  $(rg -l 'GetDiagnosticsSettingsClientE')
+sd 'GetVMInsightsClientE\b'           'CreateVMInsightsClientE'           $(rg -l 'GetVMInsightsClientE')
+sd 'GetActivityLogAlertsClientE\b'    'CreateActivityLogAlertsClientE'    $(rg -l 'GetActivityLogAlertsClientE')
+sd 'GetResourceGroupClientE\b'        'CreateResourceGroupClientE'        $(rg -l 'GetResourceGroupClientE')
+sd 'GetStorageAccountClientE\b'       'CreateStorageAccountClientE'       $(rg -l 'GetStorageAccountClientE')
+sd 'GetStorageBlobContainerClientE\b' 'CreateStorageBlobContainerClientE' $(rg -l 'GetStorageBlobContainerClientE')
+
+# CreateNew*Client renames
+sd 'CreateNewNetworkInterfacesClient'              'CreateNetworkInterfacesClient'              $(rg -l 'CreateNewNetworkInterfacesClient')
+sd 'CreateNewNetworkInterfaceIPConfigurationClient' 'CreateNetworkInterfaceIPConfigurationClient' $(rg -l 'CreateNewNetworkInterfaceIPConfigurationClient')
+sd 'CreateNewSubnetClient'                         'CreateSubnetClient'                         $(rg -l 'CreateNewSubnetClient')
+sd 'CreateNewVirtualNetworkClient'                 'CreateVirtualNetworkClient'                 $(rg -l 'CreateNewVirtualNetworkClient')
+
+# NsgRuleSummary typo
+sd 'SourceAdresssPrefixes' 'SourceAddressPrefixes' $(rg -l 'SourceAdresssPrefixes')
+```
+
+For the SDK migration itself we recommend doing one Azure service at a
+time, starting with the import path, then fixing the resulting compile
+errors (type names, `.Properties` access, pager loops). The Go compiler
+is the most reliable migration tool here.
+
+## Need help
+
+Open an issue on the Terratest repo with the `azure` label and a snippet
+of the failing code. If you spot a gap in this guide, please send a PR
+against `docs/_docs/03_migrating-to-v1/azure.md`.

go.mod

@@ -99,6 +99,7 @@ require (
 	github.com/lib/pq v1.10.9
 	github.com/microsoft/go-mssqldb v1.9.8
 	github.com/slack-go/slack v0.15.0
+	golang.org/x/sync v0.20.0
 	google.golang.org/grpc v1.80.0
 	gopkg.in/yaml.v3 v3.0.1
 	gotest.tools/v3 v3.5.2
@@ -223,7 +224,6 @@ require (
 	go.yaml.in/yaml/v2 v2.4.3 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/mod v0.33.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/term v0.41.0 // indirect
 	golang.org/x/text v0.35.0 // indirect

modules/aws/account.go

@@ -59,13 +59,17 @@ func GetAccountIDE(t testing.TestingT) (string, error) {
 	return GetAccountIDContextE(t, context.Background())
 }
 
+// GetAccountId gets the Account ID for the currently logged in IAM User.
+//
 // Deprecated: Use [GetAccountID] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
 func GetAccountId(t testing.TestingT) string {
 	return GetAccountID(t)
 }
 
+// GetAccountIdE gets the Account ID for the currently logged in IAM User.
+//
 // Deprecated: Use [GetAccountIDE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/ami.go

@@ -209,13 +209,19 @@ func GetMostRecentAmiIDE(t testing.TestingT, region string, ownerID string, filt
 	return GetMostRecentAmiIDContextE(t, context.Background(), region, ownerID, filters)
 }
 
+// GetMostRecentAmiId gets the ID of the most recent AMI in the given region that has the given owner and matches
+// the given filters.
+//
 // Deprecated: Use [GetMostRecentAmiID] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
 func GetMostRecentAmiId(t testing.TestingT, region string, ownerId string, filters map[string][]string) string {
 	return GetMostRecentAmiID(t, region, ownerId, filters)
 }
 
+// GetMostRecentAmiIdE gets the ID of the most recent AMI in the given region that has the given owner and matches
+// the given filters.
+//
 // Deprecated: Use [GetMostRecentAmiIDE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/auth.go

@@ -17,7 +17,9 @@ import (
 )
 
 const (
-	AuthAssumeRoleEnvVar = "TERRATEST_IAM_ROLE" // OS environment variable name through which Assume Role ARN may be passed for authentication
+	// AuthAssumeRoleEnvVar is the OS environment variable name through which an
+	// Assume Role ARN may be passed for authentication.
+	AuthAssumeRoleEnvVar = "TERRATEST_IAM_ROLE"
 )
 
 // NewAuthenticatedSessionContext creates an AWS Config following to standard AWS authentication workflow.

modules/aws/dynamodb.go

@@ -74,6 +74,8 @@ func GetDynamoDBTableTagsE(t testing.TestingT, region string, tableName string)
 	return GetDynamoDBTableTagsContextE(t, context.Background(), region, tableName)
 }
 
+// GetDynamoDbTableTags fetches resource tags of a specified dynamoDB table. This will fail the test if there are any errors.
+//
 // Deprecated: Use [GetDynamoDBTableTagsContext] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
@@ -82,6 +84,8 @@ func GetDynamoDbTableTags(t testing.TestingT, region string, tableName string) [
 	return GetDynamoDBTableTagsContext(t, context.Background(), region, tableName)
 }
 
+// GetDynamoDbTableTagsE fetches resource tags of a specified dynamoDB table.
+//
 // Deprecated: Use [GetDynamoDBTableTagsContextE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/ec2-files.go

@@ -394,6 +394,10 @@ func FetchFilesFromAsgsPE(t testing.TestingT, awsRegion string, spec *RemoteFile
 	return FetchFilesFromAsgsPContextE(t, context.Background(), awsRegion, spec)
 }
 
+// FetchFilesFromAsgs looks up the EC2 Instances in all the ASGs given in the
+// RemoteFileSpecification, downloads the matching files from each instance,
+// and stores them locally as described in [FetchFilesFromAsgsPContext].
+//
 // Deprecated: Use [FetchFilesFromAsgsPContext] instead.
 //
 //nolint:staticcheck,revive,gocritic // preserving deprecated function name
@@ -403,6 +407,8 @@ func FetchFilesFromAsgs(t testing.TestingT, awsRegion string, spec RemoteFileSpe
 	FetchFilesFromAsgsPContext(t, context.Background(), awsRegion, &spec)
 }
 
+// FetchFilesFromAsgsE is the error-returning equivalent of [FetchFilesFromAsgs].
+//
 // Deprecated: Use [FetchFilesFromAsgsPContextE] instead.
 //
 //nolint:staticcheck,revive,gocritic // preserving deprecated function name

modules/aws/errors.go

@@ -5,6 +5,8 @@ import (
 )
 
 // IpForEc2InstanceNotFound is an error that occurs when the IP for an EC2 instance is not found.
+//
+// Deprecated: Use [IPForEc2InstanceNotFound] instead.
 type IpForEc2InstanceNotFound struct { //nolint:staticcheck,revive // preserving deprecated type name
 	InstanceId string //nolint:staticcheck,revive // preserving existing field name
 	AwsRegion  string
@@ -40,6 +42,7 @@ func (err NotFoundError) Error() string {
 	return fmt.Sprintf("Object of type %s with id %s not found in region %s", err.objectType, err.objectID, err.region)
 }
 
+// NewNotFoundError returns a [NotFoundError] for the given object type, ID, and region.
 func NewNotFoundError(objectType string, objectID string, region string) NotFoundError {
 	return NotFoundError{objectType, objectID, region}
 }
@@ -60,6 +63,8 @@ func (err AsgCapacityNotMetError) Error() string {
 	)
 }
 
+// NewAsgCapacityNotMetError returns an [AsgCapacityNotMetError] describing
+// the given ASG's desired and current capacities.
 func NewAsgCapacityNotMetError(asgName string, desiredCapacity int64, currentCapacity int64) AsgCapacityNotMetError {
 	return AsgCapacityNotMetError{asgName, desiredCapacity, currentCapacity}
 }
@@ -80,6 +85,8 @@ func (err BucketVersioningNotEnabledError) Error() string {
 	)
 }
 
+// NewBucketVersioningNotEnabledError returns a [BucketVersioningNotEnabledError]
+// for the given S3 bucket, region, and observed versioning status.
 func NewBucketVersioningNotEnabledError(s3BucketName string, awsRegion string, versioningStatus string) BucketVersioningNotEnabledError {
 	return BucketVersioningNotEnabledError{s3BucketName: s3BucketName, awsRegion: awsRegion, versioningStatus: versioningStatus}
 }
@@ -99,6 +106,8 @@ func (err NoBucketPolicyError) Error() string {
 	)
 }
 
+// NewNoBucketPolicyError returns a [NoBucketPolicyError] for the given S3
+// bucket, region, and bucket policy.
 func NewNoBucketPolicyError(s3BucketName string, awsRegion string, bucketPolicy string) NoBucketPolicyError {
 	return NoBucketPolicyError{s3BucketName: s3BucketName, awsRegion: awsRegion, bucketPolicy: bucketPolicy}
 }