Refactor test infrastructure and consolidate test utilities

Modernize the test infrastructure by consolidating test helpers into a
shared testutil package and enhancing connection reliability:

- Move test utilities from internal/test to opensearchutil/testutil for
  broader reusability across the project and external packages
- Remove obsolete internal/test/config.go in favor of improved helper
  functions with better error handling and connection management
- Add dynamic field filtering for JSON comparison tests to handle
  version-specific and environment-dependent OpenSearch responses
- Enhance connection robustness with improved readiness checks and
  health monitoring in opensearchtransport layer
- Update all integration tests across opensearchapi, plugins, and
  transport packages to use the new unified test infrastructure
- Add comprehensive documentation and examples for the new test utilities

This refactor provides a more maintainable foundation for testing across
different OpenSearch versions and environments while reducing code
duplication and improving test reliability.

Signed-off-by: Sean Chittenden <sean.chittenden@crowdstrike.com>

Author: sean-

CHANGELOG.md

@@ -5,7 +5,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Added
-- Enhanced cluster readiness checking for improved test reliability: `ostest.NewClient()` now includes readiness validation (health + cluster state + nodes info)
+- Enhanced cluster readiness checking for improved test reliability: `testutil.NewClient()` now includes readiness validation (health + cluster state + nodes info)
 - Configuration option `IncludeDedicatedClusterManagers` for controlling cluster manager node routing ([#765](https://github.com/opensearch-project/opensearch-go/issues/765))
 - Add connection pool health probes with cluster-aware resurrection timing ([#786](https://github.com/opensearch-project/opensearch-go/pull/786))
 
@@ -16,6 +16,10 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - **BREAKING**: Enhanced node discovery to match OpenSearch server behavior ([#765](https://github.com/opensearch-project/opensearch-go/issues/765))
   - Dedicated cluster manager nodes are now excluded from client request routing by default (best practice)
   - Node selection logic now matches Java client `NodeSelector.SKIP_DEDICATED_CLUSTER_MASTERS` behavior
+- **BREAKING**: Migrate `signer/aws` package from AWS SDK v1 to AWS SDK v2 due to AWS SDK v1 reaching end-of-support on July 31, 2025
+  - Constructor now takes `aws.Config` instead of `session.Options`
+  - See USER_GUIDE.md for details required to migrate
+  - Users who need access to the existing `signer/awsv2` API can still use it, however they are encouraged to migrate to `signer/aws`
 
 ### Deprecated
 
@@ -265,7 +269,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 - Updates workflow action versions ([#488](https://github.com/opensearch-project/opensearch-go/pull/488))
 - Changes integration tests to work with secure and unsecure OpenSearch ([#488](https://github.com/opensearch-project/opensearch-go/pull/488))
-- Moves functions from `opensearch/internal/test` to `internal/test` for more general test uses ([#488](https://github.com/opensearch-project/opensearch-go/pull/488))
+- Moves functions from `opensearch/internal/test` to `opensearchutil/testutil` for shared test utilities ([#488](https://github.com/opensearch-project/opensearch-go/pull/488))
 - Changes `custom_foldername` field to pointer as it can be `null` ([#488](https://github.com/opensearch-project/opensearch-go/pull/488))
 - Changs cat indices Primary and Replica field to pointer as it can be `null` ([#488](https://github.com/opensearch-project/opensearch-go/pull/488))
 - Replaces `ioutil` with `io` in examples and integration tests [#495](https://github.com/opensearch-project/opensearch-go/pull/495)

Makefile

@@ -227,8 +227,8 @@ cluster.scale.3: ## Start full 3-node cluster
 
 cluster.get-cert:
 	@if [[ -v SECURE_INTEGRATION ]] && [[ $$SECURE_INTEGRATION == "true" ]]; then \
-		docker cp $$(docker compose --project-directory .ci/opensearch ps --format '{{.Name}}'):/usr/share/opensearch/config/kirk.pem admin.pem && \
-		docker cp $$(docker compose --project-directory .ci/opensearch ps --format '{{.Name}}'):/usr/share/opensearch/config/kirk-key.pem admin.key; \
+		docker cp $$(docker compose --project-directory .ci/opensearch ps --format '{{.Name}}' | head -1):/usr/share/opensearch/config/kirk.pem admin.pem && \
+		docker cp $$(docker compose --project-directory .ci/opensearch ps --format '{{.Name}}' | head -1):/usr/share/opensearch/config/kirk-key.pem admin.key; \
 	fi
 
 

USER_GUIDE.md

@@ -210,13 +210,19 @@ Before starting, we strongly recommend reading the full AWS documentation regard
 >
 > See [Managed Domains signing-service requests.](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#managedomains-signing-service-requests)
 
-Depending on the version of AWS SDK used, import the v1 or v2 request signer from `signer/aws` or `signer/awsv2` respectively. Both signers are equivalent in their functionality, they provide AWS Signature Version 4 (SigV4).
+Depending on the version of AWS SDK used, import the request signer from `signer/aws` (recommended) or `signer/awsv2`. Both signers use AWS SDK v2 and provide AWS Signature Version 4 (SigV4).
+
+**BREAKING CHANGE**: As of this version, the main `signer/aws` package has been migrated from AWS SDK v1 to AWS SDK v2 due to AWS SDK v1 reaching end-of-support on July 31, 2025.
 
 To read more about SigV4 see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)
 
 Here are some Go samples that show how to sign each OpenSearch request and automatically search for AWS credentials from the ~/.aws folder or environment variables:
 
-### AWS SDK v1
+### AWS SDK v2 (Recommended)
+
+**Migration Note**: If you were previously using `signer/aws` with AWS SDK v1, you need to update your imports and configuration as shown below.
+
+**Credential Caching**: The signer automatically enables credential caching for improved performance, especially when using STS credentials (assume role, web identity, etc.). This reduces API calls to AWS STS and improves signing performance.
 
 ```go
 package main
@@ -226,7 +232,8 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/aws/aws-sdk-go/aws/session"
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/config"
 	requestsigner "github.com/opensearch-project/opensearch-go/v4/signer/aws"
 
 	"github.com/opensearch-project/opensearch-go/v4"
@@ -245,16 +252,22 @@ func main() {
 const endpoint = "" // e.g. https://opensearch-domain.region.com
 
 func example() error {
-	// Create an AWS request Signer and load AWS configuration using default config folder or env vars.
-	// See https://docs.aws.amazon.com/opensearch-service/latest/developerguide/request-signing.html#request-signing-go
-	signer, err := requestsigner.NewSignerWithService(
-		session.Options{SharedConfigState: session.SharedConfigEnable},
-		requestsigner.OpenSearchService, // Use requestsigner.OpenSearchServerless for Amazon OpenSearch Serverless.
-	)
+	ctx := context.Background()
+
+	// Load AWS configuration
+	awsCfg, err := config.LoadDefaultConfig(ctx)
 	if err != nil {
 		return err
 	}
-	// Create an opensearch client and use the request-signer.
+
+	// Create an AWS request Signer
+	signer, err := requestsigner.NewSignerWithService(awsCfg, requestsigner.OpenSearchService)
+	// Use requestsigner.OpenSearchServerless for Amazon OpenSearch Serverless
+	if err != nil {
+		return err
+	}
+
+	// Create an opensearch client and use the request-signer
 	client, err := opensearchapi.NewClient(
 		opensearchapi.Config{
 			Client: opensearch.Config{
@@ -267,20 +280,18 @@ func example() error {
 		return err
 	}
 
-	ctx := context.Background()
-    
-    ping, err := client.Ping(ctx, nil)
-    if err != nil {
-        return err
-    }
+	ping, err := client.Ping(ctx, nil)
+	if err != nil {
+		return err
+	}
 
-    fmt.Println(ping)
+	fmt.Println(ping)
 
 	return nil
 }
 ```
 
-### AWS SDK v2
+### Alternative: Using signer/awsv2
 
 Use the AWS SDK v2 for Go to authenticate with Amazon OpenSearch service.
 

error_test.go

@@ -50,7 +50,7 @@ func TestError(t *testing.T) {
 			assert.True(t, resp.IsError())
 			err := opensearch.ParseError(resp)
 			var testError *opensearch.StructError
-			require.True(t, errors.As(err, &testError))
+			require.ErrorAs(t, err, &testError)
 			assert.Equal(t, http.StatusBadRequest, testError.Status)
 			assert.Equal(t, "resource_already_exists_exception", testError.Err.Type)
 			assert.Equal(t, "index [test/HU2mN_RMRXGcS38j3yV-VQ] already exists", testError.Err.Reason)
@@ -92,7 +92,7 @@ func TestError(t *testing.T) {
 			assert.True(t, resp.IsError())
 			err := opensearch.ParseError(resp)
 			var testError *opensearch.StructError
-			require.True(t, errors.As(err, &testError))
+			require.ErrorAs(t, err, &testError)
 			assert.Equal(t, http.StatusBadRequest, testError.Status)
 			assert.Equal(t, "illegal_argument_exception", testError.Err.Type)
 			assert.Equal(t, "composable template [posts] template after composition is invalid", testError.Err.Reason)
@@ -117,14 +117,14 @@ func TestError(t *testing.T) {
 					}`),
 				)
 				body, err := io.ReadAll(reader)
-				require.Nil(t, err)
+				require.NoError(t, err)
 
 				var errStruct *opensearch.StructError
 				err = json.Unmarshal(body, &errStruct)
-				assert.NotNil(t, err)
+				assert.Error(t, err)
 
 				var jsonError *json.UnmarshalTypeError
-				assert.True(t, errors.As(err, &jsonError))
+				assert.ErrorAs(t, err, &jsonError)
 			})
 			t.Run("string", func(t *testing.T) {
 				reader := io.NopCloser(
@@ -134,14 +134,14 @@ func TestError(t *testing.T) {
 					}`),
 				)
 				body, err := io.ReadAll(reader)
-				require.Nil(t, err)
+				require.NoError(t, err)
 
 				var errStruct *opensearch.StructError
 				err = json.Unmarshal(body, &errStruct)
-				assert.NotNil(t, err)
+				assert.Error(t, err)
 
 				var errStr *opensearch.StringError
-				require.True(t, errors.As(err, &errStr))
+				require.ErrorAs(t, err, &errStr)
 			})
 		})
 	})
@@ -159,7 +159,7 @@ func TestError(t *testing.T) {
 		assert.True(t, resp.IsError())
 		err := opensearch.ParseError(resp)
 		var testError *opensearch.StringError
-		require.True(t, errors.As(err, &testError))
+		require.ErrorAs(t, err, &testError)
 		assert.Equal(t, http.StatusMethodNotAllowed, testError.Status)
 		assert.Contains(t, testError.Err, "Incorrect HTTP method for uri")
 		_ = fmt.Sprintf("%s", testError)
@@ -175,7 +175,7 @@ func TestError(t *testing.T) {
 		assert.True(t, resp.IsError())
 		err := opensearch.ParseError(resp)
 		var testError *opensearch.StringError
-		require.True(t, errors.As(err, &testError))
+		require.ErrorAs(t, err, &testError)
 		assert.Equal(t, http.StatusNotFound, testError.Status)
 		assert.Contains(t, testError.Err, "{\"_index\":\"index\",\"_id\":\"2\",\"matched\":false}")
 		_ = fmt.Sprintf("%s", testError)
@@ -193,7 +193,7 @@ func TestError(t *testing.T) {
 		assert.True(t, resp.IsError())
 		err := opensearch.ParseError(resp)
 		var testError *opensearch.Error
-		require.True(t, errors.As(err, &testError))
+		require.ErrorAs(t, err, &testError)
 		assert.Contains(t, testError.Err, "no handler found for uri [/_plugins/_security/xxx] and method [GET]")
 		_ = fmt.Sprintf("%s", testError)
 	})
@@ -214,7 +214,7 @@ func TestError(t *testing.T) {
 		assert.True(t, resp.IsError())
 		err := opensearch.ParseError(resp)
 		var testError *opensearch.ReasonError
-		require.True(t, errors.As(err, &testError))
+		require.ErrorAs(t, err, &testError)
 		assert.Equal(t, "error", testError.Status)
 		assert.Contains(t, testError.Reason, "Invalid configuration")
 		_ = fmt.Sprintf("%s", testError)
@@ -230,7 +230,7 @@ func TestError(t *testing.T) {
 		assert.True(t, resp.IsError())
 		err := opensearch.ParseError(resp)
 		var testError *opensearch.MessageError
-		require.True(t, errors.As(err, &testError))
+		require.ErrorAs(t, err, &testError)
 		assert.Equal(t, "BAD_REQUEST", testError.Status)
 		assert.Contains(t, testError.Message, "Wrong request body")
 		_ = fmt.Sprintf("%s", testError)
@@ -277,7 +277,7 @@ func TestError(t *testing.T) {
 			t.Run(tt.Name, func(t *testing.T) {
 				err := opensearch.ParseError(tt.Resp)
 				for _, wantedError := range tt.WantedErrors {
-					assert.True(t, errors.Is(err, wantedError))
+					assert.ErrorIs(t, err, wantedError)
 				}
 			})
 		}
@@ -289,7 +289,7 @@ func TestError(t *testing.T) {
 			}
 			assert.True(t, resp.IsError())
 			err := opensearch.ParseError(resp)
-			assert.True(t, errors.Is(err, opensearch.ErrJSONUnmarshalBody))
+			assert.ErrorIs(t, err, opensearch.ErrJSONUnmarshalBody)
 		})
 		t.Run("too many requests", func(t *testing.T) {
 			resp := &opensearch.Response{
@@ -298,7 +298,7 @@ func TestError(t *testing.T) {
 			}
 			assert.True(t, resp.IsError())
 			err := opensearch.ParseError(resp)
-			assert.True(t, errors.Is(err, opensearch.ErrJSONUnmarshalBody))
+			assert.ErrorIs(t, err, opensearch.ErrJSONUnmarshalBody)
 		})
 	})
 }

go.mod

@@ -3,15 +3,15 @@ module github.com/opensearch-project/opensearch-go/v4
 go 1.24.0
 
 require (
-	github.com/aws/aws-sdk-go v1.55.8
 	github.com/aws/aws-sdk-go-v2 v1.41.1
 	github.com/aws/aws-sdk-go-v2/config v1.32.7
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.7
 	github.com/stretchr/testify v1.11.1
 	github.com/wI2L/jsondiff v0.7.0
+	golang.org/x/mod v0.32.0
 )
 
 require (
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.7 // indirect
 	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.17 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.17 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.17 // indirect
@@ -24,7 +24,6 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/sts v1.41.6 // indirect
 	github.com/aws/smithy-go v1.24.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/jmespath/go-jmespath v0.4.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/tidwall/gjson v1.18.0 // indirect
 	github.com/tidwall/match v1.1.1 // indirect

go.sum

@@ -1,5 +1,3 @@
-github.com/aws/aws-sdk-go v1.55.8 h1:JRmEUbU52aJQZ2AjX4q4Wu7t4uZjOu71uyNmaWlUkJQ=
-github.com/aws/aws-sdk-go v1.55.8/go.mod h1:ZkViS9AqA6otK+JBBNH2++sx1sgxrPKcSzPPvQkUtXk=
 github.com/aws/aws-sdk-go-v2 v1.41.1 h1:ABlyEARCDLN034NhxlRUSZr4l71mh+T5KAeGh6cerhU=
 github.com/aws/aws-sdk-go-v2 v1.41.1/go.mod h1:MayyLB8y+buD9hZqkCW3kX1AKq07Y5pXxtgB+rRFhz0=
 github.com/aws/aws-sdk-go-v2/config v1.32.7 h1:vxUyWGUwmkQ2g19n7JY/9YL8MfAIl7bTesIUykECXmY=
@@ -28,16 +26,10 @@ github.com/aws/aws-sdk-go-v2/service/sts v1.41.6 h1:5fFjR/ToSOzB2OQ/XqWpZBmNvmP/
 github.com/aws/aws-sdk-go-v2/service/sts v1.41.6/go.mod h1:qgFDZQSD/Kys7nJnVqYlWKnh0SSdMjAi0uSwON4wgYQ=
 github.com/aws/smithy-go v1.24.0 h1:LpilSUItNPFr1eY85RYgTIg5eIEPtvFbskaFcmmIUnk=
 github.com/aws/smithy-go v1.24.0/go.mod h1:LEj2LM3rBRQJxPZTB4KuzZkaZYnZPnvgIhb4pu07mx0=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/jmespath/go-jmespath v0.4.0 h1:BEgLn5cpjn8UN1mAw4NjwDrS35OdebyEtFe+9YPoQUg=
-github.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo=
-github.com/jmespath/go-jmespath/internal/testify v1.5.1 h1:shLQSRRSCCPj3f2gpwzGwWFoC7ycTf1rcQZHOlsJ6N8=
-github.com/jmespath/go-jmespath/internal/testify v1.5.1/go.mod h1:L3OGu8Wl2/fWfCI6z80xFu9LTZmf1ZRjMHUOPmWr69U=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/tidwall/gjson v1.14.2/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
@@ -52,9 +44,9 @@ github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
 github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
 github.com/wI2L/jsondiff v0.7.0 h1:1lH1G37GhBPqCfp/lrs91rf/2j3DktX6qYAKZkLuCQQ=
 github.com/wI2L/jsondiff v0.7.0/go.mod h1:KAEIojdQq66oJiHhDyQez2x+sRit0vIzC9KeK0yizxM=
+golang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
+golang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10=
-gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=