deprecate collections and environment packages (#1837)

* deprecate collections and environment, migrate internal callers

Per the Terratest V2 proposal, the collections and environment packages are
scheduled for removal in v2 because the standard library now covers them.

- Add // Deprecated: notices to every exported symbol in both packages,
  pointing at the stdlib replacement (slices, strings, os.Getenv).
- Migrate the in-repo callers off them so the deprecations do not trip
  staticcheck SA1019 in CI: aws, azure, gcp, k8s, and test-structure now use
  the standard library directly via small local helpers.

No behavior change. The packages keep working for the rest of v1.

* test: cover GetNameFromResourceIDE error path

GetNameFromResourceIDE now owns its error construction instead of delegating
to the deprecated collections package, so add a direct test for both the
success and the no-separator error path.

* refactor: share list helpers via internal/collections

Replace the per-package listIntersection/listSubtract helpers with a single
internal/collections package (generic Intersection/Subtract over slices),
imported by aws, azure, gcp, and test-structure. Keeps the logic in one tested
place without re-exposing it as public API.

* Address review feedback on deprecations and helpers

- internal/collections: switch Intersection/Subtract to map lookups; table-driven tests + Example tests
- azure: typed ResourceIDNameNotFoundError; resolve name via strings.LastIndex instead of strings.Split; require over assert for error checks
- collections/environment: deprecation comments now show the concrete stdlib replacement inline
- gcp: use require.NotEmptyf instead of t.Fatalf

* azure: treat trailing-slash resource IDs as parse errors

A value like "foo/bar/" previously returned an empty name with a nil error; return the not-found error when the final segment is empty too. (CodeRabbit review.)

* Address review follow-ups from two-agent review

- azure: export ResourceIDNameNotFoundError.ResourceID so callers can inspect it; cover the trailing-slash behavior change with tests and assert the typed error via errors.As
- internal/collections: add nil-input and duplicate-in-list2 test cases; comment the delete-based dedup
- collections: note the error/bounds semantics the stringslice deprecation snippets don't reproduce
- environment: finish the dangling GetFirstNonEmptyEnvVarOrFatal doc sentence
- gcp: mark firstNonEmptyEnvVarOrFatal as a test helper

* collections: clarify deprecation has no public replacement

ListIntersection/ListSubtract are not re-exposed publicly in v2 (the package is dropped); say so explicitly so the inline slices guidance reads as intentional rather than hiding a replacement.

* Fix lint failures: wsl whitespace and deprecated environment usage

- gcp/provider.go, azure/resourceid_test.go: add the blank lines wsl_v5 requires after t.Helper()/t.Parallel() before the following assignment
- slack/validate_test.go: stop calling the now-deprecated environment.RequireEnvVar (SA1019); use require.NotEmptyf with os.Getenv directly
Verified with golangci-lint 2.11.3: 0 issues.

Author: james00012

internal/collections/collections.go

@@ -0,0 +1,43 @@
+// Package collections holds small generic slice helpers shared across
+// Terratest's own packages. It is internal and not part of the public API; the
+// public modules/collections package is deprecated and scheduled for removal in
+// v2.
+package collections
+
+// Intersection returns the items present in both lists, de-duplicated, in the
+// order they appear in list1.
+func Intersection[T comparable](list1 []T, list2 []T) []T {
+	lookups := make(map[T]struct{}, len(list2))
+	for _, item := range list2 {
+		lookups[item] = struct{}{}
+	}
+
+	out := make([]T, 0, min(len(list1), len(list2)))
+
+	for _, item := range list1 {
+		if _, found := lookups[item]; found {
+			out = append(out, item)
+			delete(lookups, item) // delete so a repeated list1 item isn't emitted twice
+		}
+	}
+
+	return out
+}
+
+// Subtract returns the items in list1 that are not in list2.
+func Subtract[T comparable](list1 []T, list2 []T) []T {
+	lookups := make(map[T]struct{}, len(list2))
+	for _, item := range list2 {
+		lookups[item] = struct{}{}
+	}
+
+	out := make([]T, 0, len(list1))
+
+	for _, item := range list1 {
+		if _, found := lookups[item]; !found {
+			out = append(out, item)
+		}
+	}
+
+	return out
+}

internal/collections/collections_test.go

@@ -0,0 +1,74 @@
+package collections_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/gruntwork-io/terratest/internal/collections"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIntersection(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		list1 []string
+		list2 []string
+		want  []string
+	}{
+		{"common items, ordered by list1", []string{"a", "b", "c"}, []string{"b", "c", "d"}, []string{"b", "c"}},
+		{"dedups output", []string{"a", "a"}, []string{"a"}, []string{"a"}},
+		{"dedups duplicates in list2", []string{"a"}, []string{"a", "a"}, []string{"a"}},
+		{"no overlap returns empty, not nil", []string{"a"}, []string{"b"}, []string{}},
+		{"nil inputs return empty, not nil", nil, nil, []string{}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tc.want, collections.Intersection(tc.list1, tc.list2))
+		})
+	}
+}
+
+func TestSubtract(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		list1 []string
+		list2 []string
+		want  []string
+	}{
+		{"removes list2 items", []string{"a", "b", "c"}, []string{"b", "c"}, []string{"a"}},
+		{"everything removed returns empty, not nil", []string{"a", "b"}, []string{"a", "b"}, []string{}},
+		{"nil list1 returns empty, not nil", nil, []string{"a"}, []string{}},
+		{"nil list2 keeps list1", []string{"a", "b"}, nil, []string{"a", "b"}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tc.want, collections.Subtract(tc.list1, tc.list2))
+		})
+	}
+}
+
+func TestSubtractDoesNotMutateInput(t *testing.T) {
+	t.Parallel()
+
+	in := []string{"a", "b"}
+	collections.Subtract(in, []string{"a"})
+	assert.Equal(t, []string{"a", "b"}, in, "does not mutate the input slice")
+}
+
+func ExampleIntersection() {
+	fmt.Println(collections.Intersection([]int{1, 2, 3}, []int{2, 3, 4}))
+	// Output: [2 3]
+}
+
+func ExampleSubtract() {
+	fmt.Println(collections.Subtract([]int{1, 2, 3}, []int{2, 3}))
+	// Output: [1]
+}

modules/aws/region.go

@@ -8,7 +8,7 @@ import (
 	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go-v2/service/ec2"
 	"github.com/aws/aws-sdk-go-v2/service/ssm"
-	"github.com/gruntwork-io/terratest/modules/collections"
+	"github.com/gruntwork-io/terratest/internal/collections"
 	"github.com/gruntwork-io/terratest/modules/logger"
 	"github.com/gruntwork-io/terratest/modules/random"
 	"github.com/gruntwork-io/terratest/modules/testing"
@@ -53,11 +53,11 @@ func GetRandomStableRegionContextE(t testing.TestingT, ctx context.Context, appr
 	regionsToPickFrom := stableRegions
 
 	if len(approvedRegions) > 0 {
-		regionsToPickFrom = collections.ListIntersection(regionsToPickFrom, approvedRegions)
+		regionsToPickFrom = collections.Intersection(regionsToPickFrom, approvedRegions)
 	}
 
 	if len(forbiddenRegions) > 0 {
-		regionsToPickFrom = collections.ListSubtract(regionsToPickFrom, forbiddenRegions)
+		regionsToPickFrom = collections.Subtract(regionsToPickFrom, forbiddenRegions)
 	}
 
 	return GetRandomRegionContextE(t, ctx, regionsToPickFrom, nil)
@@ -122,7 +122,7 @@ func GetRandomRegionContextE(t testing.TestingT, ctx context.Context, approvedRe
 		regionsToPickFrom = allRegions
 	}
 
-	regionsToPickFrom = collections.ListSubtract(regionsToPickFrom, forbiddenRegions)
+	regionsToPickFrom = collections.Subtract(regionsToPickFrom, forbiddenRegions)
 	region := random.RandomString(regionsToPickFrom)
 
 	logger.Default.Logf(t, "Using region %s", region)

modules/azure/errors.go

@@ -72,6 +72,21 @@ func (e *UnknownEnvironmentError) Error() string {
 		e.EnvironmentName)
 }
 
+// ResourceIDNameNotFoundError is returned when a name cannot be resolved from an Azure resource ID.
+// The offending ID is exported so callers can inspect it via errors.As.
+type ResourceIDNameNotFoundError struct {
+	ResourceID string
+}
+
+func (err ResourceIDNameNotFoundError) Error() string {
+	return fmt.Sprintf("could not resolve name from resource ID %q", err.ResourceID)
+}
+
+// NewResourceIDNameNotFoundError creates a ResourceIDNameNotFoundError for the given resource ID.
+func NewResourceIDNameNotFoundError(resourceID string) ResourceIDNameNotFoundError {
+	return ResourceIDNameNotFoundError{ResourceID: resourceID}
+}
+
 // ResourceNotFoundErrorExists checks the Service Error Code for the 'Resource Not Found' error.
 func ResourceNotFoundErrorExists(err error) bool {
 	if err == nil {

modules/azure/region.go

@@ -3,7 +3,7 @@ package azure
 import (
 	"context"
 
-	"github.com/gruntwork-io/terratest/modules/collections"
+	"github.com/gruntwork-io/terratest/internal/collections"
 	"github.com/gruntwork-io/terratest/modules/random"
 	"github.com/gruntwork-io/terratest/modules/testing"
 	"github.com/stretchr/testify/require"
@@ -72,11 +72,11 @@ func GetRandomStableRegionContext(t testing.TestingT, ctx context.Context, appro
 	regionsToPickFrom := stableRegions
 
 	if len(approvedRegions) > 0 {
-		regionsToPickFrom = collections.ListIntersection(regionsToPickFrom, approvedRegions)
+		regionsToPickFrom = collections.Intersection(regionsToPickFrom, approvedRegions)
 	}
 
 	if len(forbiddenRegions) > 0 {
-		regionsToPickFrom = collections.ListSubtract(regionsToPickFrom, forbiddenRegions)
+		regionsToPickFrom = collections.Subtract(regionsToPickFrom, forbiddenRegions)
 	}
 
 	return GetRandomRegionContext(t, ctx, regionsToPickFrom, nil, subscriptionID) //nolint:staticcheck
@@ -145,7 +145,7 @@ func GetRandomRegionContextE(t testing.TestingT, ctx context.Context, approvedRe
 		regionsToPickFrom = allRegions
 	}
 
-	regionsToPickFrom = collections.ListSubtract(regionsToPickFrom, forbiddenRegions)
+	regionsToPickFrom = collections.Subtract(regionsToPickFrom, forbiddenRegions)
 	region := random.RandomString(regionsToPickFrom)
 
 	return region, nil

modules/azure/resourceid.go

@@ -1,6 +1,8 @@
 package azure
 
-import "github.com/gruntwork-io/terratest/modules/collections"
+import (
+	"strings"
+)
 
 // GetNameFromResourceID gets the Name from an Azure Resource ID.
 func GetNameFromResourceID(resourceID string) string {
@@ -15,10 +17,10 @@ func GetNameFromResourceID(resourceID string) string {
 // GetNameFromResourceIDE gets the Name from an Azure Resource ID.
 // This function would fail the test if there is an error.
 func GetNameFromResourceIDE(resourceID string) (string, error) {
-	id, err := collections.GetSliceLastValueE(resourceID, "/")
-	if err != nil {
-		return "", err
+	i := strings.LastIndex(resourceID, "/")
+	if i == -1 || i == len(resourceID)-1 {
+		return "", NewResourceIDNameNotFoundError(resourceID)
 	}
 
-	return id, nil
+	return resourceID[i+1:], nil
 }

modules/azure/resourceid_test.go

@@ -5,14 +5,57 @@ import (
 
 	"github.com/gruntwork-io/terratest/modules/azure"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestGetNameFromResourceID(t *testing.T) {
 	t.Parallel()
 
-	resultSuccess := azure.GetNameFromResourceID("this/is/a/long/slash/separated/string/ResourceID")
-	assert.Equal(t, "ResourceID", resultSuccess)
+	tests := []struct {
+		name       string
+		resourceID string
+		want       string
+	}{
+		{"normal resource ID", "this/is/a/long/slash/separated/string/ResourceID", "ResourceID"},
+		{"no separator", "noresourcepresent", ""},
+		{"trailing slash", "this/is/a/ResourceID/", ""},
+		{"empty", "", ""},
+	}
 
-	resultBadSeparator := azure.GetNameFromResourceID("noresourcepresent")
-	assert.Empty(t, resultBadSeparator)
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tc.want, azure.GetNameFromResourceID(tc.resourceID))
+		})
+	}
+}
+
+func TestGetNameFromResourceIDE(t *testing.T) {
+	t.Parallel()
+
+	name, err := azure.GetNameFromResourceIDE("this/is/a/long/slash/separated/string/ResourceID")
+	require.NoError(t, err)
+	assert.Equal(t, "ResourceID", name)
+
+	tests := []struct {
+		name       string
+		resourceID string
+	}{
+		{"no separator", "noresourcepresent"},
+		{"trailing slash", "this/is/a/ResourceID/"},
+		{"empty", ""},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := azure.GetNameFromResourceIDE(tc.resourceID)
+			require.Error(t, err)
+
+			var notFound azure.ResourceIDNameNotFoundError
+			require.ErrorAs(t, err, &notFound)
+			assert.Equal(t, tc.resourceID, notFound.ResourceID)
+		})
+	}
 }

modules/collections/collections.go

@@ -1,2 +1,10 @@
 // Package collections allows to interact with lists of things.
+//
+// Deprecated: The collections package is scheduled for removal in Terratest v2.
+// Go's standard library covers these helpers as of Go 1.21+. Replace at the call
+// site:
+//
+//	ListContains(haystack, needle)        -> slices.Contains(haystack, needle)
+//	ListIntersection / ListSubtract       -> a short slices.Contains loop (see each function)
+//	GetSliceLastValueE / GetSliceIndexValueE -> strings.Split, then index the result
 package collections

modules/collections/errors.go

@@ -1,6 +1,8 @@
 package collections
 
 // SliceValueNotFoundError is returned when a provided values file input is not found on the host path.
+//
+// Deprecated: scheduled for removal in Terratest v2 along with the collections package.
 type SliceValueNotFoundError struct {
 	sourceString string
 }
@@ -10,6 +12,8 @@ func (err SliceValueNotFoundError) Error() string {
 }
 
 // NewSliceValueNotFoundError creates a new slice found error
+//
+// Deprecated: scheduled for removal in Terratest v2 along with the collections package.
 func NewSliceValueNotFoundError(sourceString string) SliceValueNotFoundError {
 	return SliceValueNotFoundError{sourceString}
 }

modules/collections/lists.go

@@ -4,6 +4,17 @@ import "slices"
 
 // ListIntersection returns all the items in both list1 and list2. Note that this will dedup the items so that the
 // output is more predictable. Otherwise, the end list depends on which list was used as the base.
+//
+// Deprecated: scheduled for removal in Terratest v2. The collections package is being
+// dropped, so there is no drop-in public replacement; build it inline with the slices
+// package (Go 1.21+) at the call site, e.g.:
+//
+//	out := []T{}
+//	for _, x := range list1 {
+//		if slices.Contains(list2, x) && !slices.Contains(out, x) {
+//			out = append(out, x)
+//		}
+//	}
 func ListIntersection[T comparable](list1 []T, list2 []T) []T {
 	out := []T{}
 
@@ -18,6 +29,17 @@ func ListIntersection[T comparable](list1 []T, list2 []T) []T {
 }
 
 // ListSubtract removes all the items in list2 from list1.
+//
+// Deprecated: scheduled for removal in Terratest v2. The collections package is being
+// dropped, so there is no drop-in public replacement; build it inline with the slices
+// package (Go 1.21+) at the call site, e.g.:
+//
+//	out := []T{}
+//	for _, x := range list1 {
+//		if !slices.Contains(list2, x) {
+//			out = append(out, x)
+//		}
+//	}
 func ListSubtract[T comparable](list1 []T, list2 []T) []T {
 	out := []T{}
 
@@ -32,7 +54,8 @@ func ListSubtract[T comparable](list1 []T, list2 []T) []T {
 
 // ListContains returns true if the given list of strings (haystack) contains the given string (needle).
 //
-// Deprecated: Use slices.Contains instead.
+// Deprecated: scheduled for removal in Terratest v2. Replace at the call site with
+// slices.Contains(haystack, needle) (Go 1.21+).
 func ListContains(haystack []string, needle string) bool {
 	return slices.Contains(haystack, needle)
 }