Add contract testing to plugin (#102)

* Add testEvent type so that contract test events can be unmarshalled

* Create an entry point for contract test and return a ProgressEvent

* Add testEventFunc type for contract testing

* Add two entry points to allow the CLI to perform contract test

* Update the docs

* Update SAM template with testing environment variables

Author: brianterry

cfn/cfn.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"log"
+	"os"
 	"time"
 
 	"github.com/aws-cloudformation/cloudformation-cli-go-plugin/cfn/callback"
@@ -67,8 +68,22 @@ type InvokeScheduler interface {
 }
 
 // Start is the entry point called from a resource's main function
+//
+// We define two lambda entry points; MakeEventFunc is the entry point to all
+// invocations of a custom resource and MakeTestEventFunc is the entry point that
+// allows the CLI's contract testing framework to invoke the resource's CRUDL handlers.
 func Start(h Handler) {
-	lambda.Start(makeEventFunc(h))
+
+	// MODE is an environment variable that is set ONLY
+	// when contract test are performed.
+	if mode, ok := os.LookupEnv("MODE"); ok == true {
+		if mode == "Test" {
+			lambda.Start(makeTestEventFunc(h))
+
+		} else {
+			lambda.Start(makeEventFunc(h))
+		}
+	}
 }
 
 // Tags are stored as key/value paired strings
@@ -77,6 +92,10 @@ type tags map[string]string
 // eventFunc is the function signature required to execute an event from the Lambda SDK
 type eventFunc func(ctx context.Context, event *event) (response, error)
 
+// testEventFunc is the function signature required to execute an event from the Lambda SDK
+// and is only used in contract testing
+type testEventFunc func(ctx context.Context, event *testEvent) (handler.ProgressEvent, error)
+
 // handlerFunc is the signature required for all actions
 type handlerFunc func(request handler.Request) handler.ProgressEvent
 
@@ -330,3 +349,28 @@ func makeEventFunc(h Handler) eventFunc {
 		}
 	}
 }
+
+// MakeTestEventFunc is the entry point that allows the CLI's
+// contract testing framework to invoke the resource's CRUDL handlers.
+func makeTestEventFunc(h Handler) testEventFunc {
+	return func(ctx context.Context, event *testEvent) (handler.ProgressEvent, error) {
+
+		handlerFn, err := router(event.Action, h)
+
+		if err != nil {
+			return handler.NewFailedEvent(err), err
+		}
+
+		request := handler.NewRequest(
+			event.Request.LogicalResourceIdentifier,
+			event.CallbackContext,
+			credentials.SessionFromCredentialsProvider(&event.Credentials),
+			event.Request.PreviousResourceState,
+			event.Request.DesiredResourceState,
+		)
+
+		progEvt := handlerFn(request)
+
+		return progEvt, nil
+	}
+}

cfn/cfn_test.go

@@ -233,3 +233,88 @@ func loadEvent(path string, evt *event) *event {
 	}
 	return evt
 }
+
+func TestMakeTestEventFunc(t *testing.T) {
+	start := time.Now()
+	future := start.Add(time.Minute * 15)
+
+	tc, cancel := context.WithDeadline(context.Background(), future)
+
+	defer cancel()
+
+	lc := lambdacontext.NewContext(tc, &lambdacontext.LambdaContext{})
+
+	f1 := func(callback map[string]interface{}, s *session.Session) handler.ProgressEvent {
+		response := handler.ProgressEvent{
+			OperationStatus: handler.Success,
+			Message:         "Create complete",
+		}
+		return response
+	}
+
+	type args struct {
+		h     Handler
+		ctx   context.Context
+		event *testEvent
+	}
+	tests := []struct {
+		name    string
+		args    args
+		want    handler.ProgressEvent
+		wantErr bool
+	}{
+		{"Test simple CREATE", args{&MockHandler{f1}, lc, loadTestEvent("test.create.json", &testEvent{})}, handler.ProgressEvent{
+			OperationStatus: handler.Success,
+			Message:         "Create complete",
+		}, false},
+		{"Test simple READ", args{&MockHandler{f1}, lc, loadTestEvent("test.read.json", &testEvent{})}, handler.ProgressEvent{
+			OperationStatus: handler.Success,
+			Message:         "Create complete",
+		}, false},
+		{"Test simple DELETE", args{&MockHandler{f1}, lc, loadTestEvent("test.delete.json", &testEvent{})}, handler.ProgressEvent{
+			OperationStatus: handler.Success,
+			Message:         "Create complete",
+		}, false},
+		{"Test simple INVALID", args{&MockHandler{f1}, lc, loadTestEvent("test.invalid.json", &testEvent{})}, handler.ProgressEvent{
+			OperationStatus: handler.Failed,
+			Message:         "InvalidRequest: No action/invalid action specified",
+		}, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f := makeTestEventFunc(tt.args.h)
+			got, err := f(tt.args.ctx, tt.args.event)
+
+			if (err != nil) != tt.wantErr {
+				t.Errorf("makeEventFunc() = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+
+			switch tt.wantErr {
+			case true:
+				if tt.want.OperationStatus != got.OperationStatus {
+					t.Errorf("response = %v; want %v", got.OperationStatus, tt.want.OperationStatus)
+				}
+
+			case false:
+				if !reflect.DeepEqual(tt.want, got) {
+					t.Errorf("response = %v; want %v", got, tt.want)
+				}
+
+			}
+		})
+	}
+}
+
+//loadEvent is a helper function that unmarshal the event from a file.
+func loadTestEvent(path string, evt *testEvent) *testEvent {
+	validevent, err := openFixture(path)
+	if err != nil {
+		log.Fatalf("Unable to read fixture: %v", err)
+	}
+
+	if err := json.Unmarshal(validevent, evt); err != nil {
+		log.Fatalf("Marshaling error with event: %v", err)
+	}
+	return evt
+}

cfn/event.go

@@ -63,3 +63,27 @@ func validateEvent(event *event) error {
 
 	return nil
 }
+
+// testEvent base structure, it will be internal to the RPDK.
+type testEvent struct {
+	Action          string                                        `json:"action"`
+	Credentials     credentials.CloudFormationCredentialsProvider `json:"credentials"`
+	CallbackContext map[string]interface{}                        `json:"callbackContext"`
+
+	Request resourceHandlerRequest
+}
+
+// resourceHandlerRequest is internal to the RPDK. It contains a number of fields that are for
+// internal contract testing use only.
+type resourceHandlerRequest struct {
+	ClientRequestToken        string          `json:"clientRequestToken"`
+	DesiredResourceState      json.RawMessage `json:"desiredResourceState"`
+	PreviousResourceState     json.RawMessage `json:"previousResourceState"`
+	DesiredResourceTags       tags            `json:"desiredResourceTags"`
+	SystemTags                tags            `json:"systemTags"`
+	AWSAccountID              string          `json:"awsAccountId"`
+	AwsPartition              string          `json:"awsPartition"`
+	LogicalResourceIdentifier string          `json:"logicalResourceIdentifier"`
+	NextToken                 string          `json:"nextToken"`
+	Region                    string          `json:"region"`
+}

cfn/handler/event.go

@@ -4,32 +4,38 @@ import "github.com/aws-cloudformation/cloudformation-cli-go-plugin/cfn/cfnerr"
 
 // ProgressEvent represent the progress of CRUD handlers.
 type ProgressEvent struct {
-	// The status indicates whether the handler has reached a terminal state or is
+	// OperationStatus indicates whether the handler has reached a terminal state or is
 	// still computing and requires more time to complete.
-	OperationStatus Status
+	OperationStatus Status `json:"status,omitempty"`
 
-	// If OperationStatus is FAILED or IN_PROGRESS, an error code should be provided.
-	HandlerErrorCode ErrorCode
+	// HandlerErrorCode should be provided when OperationStatus is FAILED or IN_PROGRESS.
+	HandlerErrorCode ErrorCode `json:"errorCode,omitempty"`
 
-	// The handler can (and should) specify a contextual information message which
-	// can be shown to callers to indicate the nature of a progress transition or
-	// callback delay; for example a message indicating "propagating to edge."
-	Message string
+	// Message which can be shown to callers to indicate the
+	//nature of a progress transition or callback delay; for example a message
+	//indicating "propagating to edge."
+	Message string `json:"message,omitempty"`
 
-	// The callback context is an arbitrary datum which the handler can return in an
+	// CallbackContext is an arbitrary datum which the handler can return in an
 	// IN_PROGRESS event to allow the passing through of additional state or
 	// metadata between subsequent retries; for example to pass through a Resource
 	// identifier which can be used to continue polling for stabilization
-	CallbackContext map[string]interface{}
+	CallbackContext map[string]interface{} `json:"callbackContext,omitempty"`
 
-	// A callback will be scheduled with an initial delay of no less than the number
+	// CallbackDelaySeconds will be scheduled with an initial delay of no less than the number
 	// of seconds specified in the progress event. Set this value to <= 0 to
 	// indicate no callback should be made.
-	CallbackDelaySeconds int64
+	CallbackDelaySeconds int64 `json:"callbackDelaySeconds,omitempty"`
 
-	// The output resource instance populated by a READ/LIST for synchronous results
+	// ResourceModel is the output resource instance populated by a READ/LIST for synchronous results
 	// and by CREATE/UPDATE/DELETE for final response validation/confirmation
-	ResourceModel interface{}
+	ResourceModel interface{} `json:"resourceModel,omitempty"`
+
+	// ResourceModels is the output resource instances populated by a LIST for synchronous results
+	ResourceModels []interface{} `json:"resourceModels,omitempty"`
+
+	// NextToken is the token used to request additional pages of resources for a LIST operation
+	NextToken string `json:"nextToken,omitempty"`
 }
 
 // NewProgressEvent creates a new event with

cfn/response.go

@@ -8,11 +8,32 @@ import (
 // cloudformation service from a resource handler.
 // The zero value is ready to use.
 type response struct {
-	Message         string            `json:"message,omitempty"`
-	OperationStatus handler.Status    `json:"operationStatus,omitempty"`
-	ResourceModel   interface{}       `json:"resourceModel,omitempty"`
-	ErrorCode       handler.ErrorCode `json:"errorCode,omitempty"`
-	BearerToken     string            `json:"bearerToken,omitempty"`
+	// Message which can be shown to callers to indicate the nature of a
+	//progress transition or callback delay; for example a message
+	//indicating "propagating to edge"
+	Message string `json:"message,omitempty"`
+
+	//The operationStatus indicates whether the handler has reached a terminal
+	//state or is still computing and requires more time to complete
+	OperationStatus handler.Status `json:"operationStatus,omitempty"`
+
+	//ResourceModel it The output resource instance populated by a READ/LIST for
+	//synchronous results and by CREATE/UPDATE/DELETE for final response
+	//validation/confirmation
+	ResourceModel interface{} `json:"resourceModel,omitempty"`
+
+	// ErrorCode is used to report granular failures back to CloudFormation
+	ErrorCode handler.ErrorCode `json:"errorCode,omitempty"`
+
+	// BearerToken is used to report progress back to CloudFormation and is
+	//passed back to CloudFormation
+	BearerToken string `json:"bearerToken,omitempty"`
+
+	// ResourceModels is the output resource instances populated by a LIST for synchronous results
+	ResourceModels []interface{} `json:"resourceModels,omitempty"`
+
+	// NextToken the token used to request additional pages of resources for a LIST operation
+	NextToken string `json:"nextToken,omitempty"`
 }
 
 // newFailedResponse returns a response pre-filled with the supplied error
@@ -33,6 +54,8 @@ func newResponse(pevt *handler.ProgressEvent, bearerToken string) (response, err
 		Message:         pevt.Message,
 		OperationStatus: pevt.OperationStatus,
 		ResourceModel:   pevt.ResourceModel,
+		ResourceModels:  pevt.ResourceModels,
+		NextToken:       pevt.NextToken,
 	}
 
 	if pevt.HandlerErrorCode != "" {

cfn/test/data/test.INVALID.json

@@ -0,0 +1,21 @@
+{
+    "action": "INVALID",
+    "credentials": {
+        "accessKeyId": "123456789",
+        "secretAccessKey": "1234566",
+        "sessionToken": "1234567"
+    },
+    "callbackContext": null,
+    "Request": {
+        "clientRequestToken": "17603535-aefd-4820-ad48-55739e0d571b",
+        "desiredResourceState": {},
+        "previousResourceState": {},
+        "desiredResourceTags": null,
+        "systemTags": null,
+        "awsAccountId": "",
+        "awsPartition": "",
+        "logicalResourceIdentifier": "",
+        "nextToken": "",
+        "region": ""
+    }
+}

cfn/test/data/test.create.json

@@ -0,0 +1,21 @@
+{
+    "action": "CREATE",
+    "credentials": {
+        "accessKeyId": "123456789",
+        "secretAccessKey": "1234566",
+        "sessionToken": "1234567"
+    },
+    "callbackContext": null,
+    "Request": {
+        "clientRequestToken": "17603535-aefd-4820-ad48-55739e0d571b",
+        "desiredResourceState": {},
+        "previousResourceState": {},
+        "desiredResourceTags": null,
+        "systemTags": null,
+        "awsAccountId": "",
+        "awsPartition": "",
+        "logicalResourceIdentifier": "",
+        "nextToken": "",
+        "region": ""
+    }
+}

cfn/test/data/test.delete.json

@@ -0,0 +1,21 @@
+{
+    "action": "DELETE",
+    "credentials": {
+        "accessKeyId": "123456789",
+        "secretAccessKey": "1234566",
+        "sessionToken": "1234567"
+    },
+    "callbackContext": null,
+    "Request": {
+        "clientRequestToken": "17603535-aefd-4820-ad48-55739e0d571b",
+        "desiredResourceState": {},
+        "previousResourceState": {},
+        "desiredResourceTags": null,
+        "systemTags": null,
+        "awsAccountId": "",
+        "awsPartition": "",
+        "logicalResourceIdentifier": "",
+        "nextToken": "",
+        "region": ""
+    }
+}

cfn/test/data/test.read.json

@@ -0,0 +1,21 @@
+{
+    "action": "READ",
+    "credentials": {
+        "accessKeyId": "123456789",
+        "secretAccessKey": "1234566",
+        "sessionToken": "1234567"
+    },
+    "callbackContext": null,
+    "Request": {
+        "clientRequestToken": "17603535-aefd-4820-ad48-55739e0d571b",
+        "desiredResourceState": {},
+        "previousResourceState": {},
+        "desiredResourceTags": null,
+        "systemTags": null,
+        "awsAccountId": "",
+        "awsPartition": "",
+        "logicalResourceIdentifier": "",
+        "nextToken": "",
+        "region": ""
+    }
+}