Update README.md

Author: dchakrav-github

.gitignore

@@ -1,2 +1,20 @@
+# macOS
+.DS_Store
+._*
+
+# Maven outputs
+.classpath
+
+# IntelliJ
+*.iml
+.idea
+out.java
+out/
+.settings
+.project
+
+# auto-generated files
 target/
-~*
+
+# our logs
+rpdk.log

.pre-commit-config.yaml

@@ -15,5 +15,3 @@ repos:
     - --indent=2
     - --no-sort-keys
   - id: check-merge-conflict
-  - id: check-yaml
-    exclude: codebuild-ci.yaml

README.md

@@ -1,26 +1,28 @@
 ## AWS CloudFormation Java Plugin Test Framework
 
-This provides an easier foundation for testing handlers for CRUD along with integated support for KMS. Developers 
-can easily write sequence of CRUD lifecycle test with expectations and will be tested. There is also a mock based 
+This provides an easier foundation for testing handlers for CRUD along with integated support for KMS. Developers
+can easily write sequence of CRUD lifecycle test with expectations and will be tested. There is also a mock based
 test based for local unit testing.
 
-The framework leverages support for [Named Profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) that allows 
-developers to test using roles and credentials, to test the exact way in which they expect to work inside CFN for their handlers. Here is the
-sample for now this can be used for injecting credentials using the role based profile specified. 
+The framework leverages support for [Named Profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) that allows
+developers to test using roles and credentials, to test the exact way in which they expect to work inside CloudFormation for their handlers. Here is the
+sample for now this can be used for injecting credentials using the role based profile specified.
 
 **Sample AWS Named Profile Setup**
 
+```
  ~/.aws/credentials
  ...
- **cfn-assume-role**
+ [cfn-assume-role]
  aws_access_key_id=[YOUR_ACCESS_KEY_ID]
  aws_secret_access_key=[YOUR_SECRET_ACCESS_KEY]
  ...
- 
+
  ~/.aws/config
- [profilei **cfn-integration**]
+ [profilei cfn-integration]
  role_arn = arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ROLE_NAME>
- source_profile = *cfn-assume-role*
+ source_profile = cfn-assume-role
+```
 
 **Using the named profile for testing**
 
@@ -30,7 +32,6 @@ sample for now this can be used for injecting credentials using the role based p
     <li><u>Create a Managed Policy for the user</u>
         Here the credentials section has an user credentials that is provided with only sts:assumeRole
         permission. Here is the policy that is associated with cfn-assume-role user in the account.
-
         <pre>
         {
             "Version": "2012-10-17",
@@ -48,9 +49,9 @@ sample for now this can be used for injecting credentials using the role based p
     <li><u>Create a Managed Policy for the services you are testing with</u>
             This is needed to test all integration for CRUD+L needed for logs. You can always narrow it down further.
             Recommended approach is to define the above policies as customer managed policies in IAM in the account and
-            associate with the role and users as appropriate. This is an example policy to test CloudWatch LogGroup
-            and KMS integration
-
+            associate with the role and users as appropriate. This is an example policy to test, replace
+            [INSERT_YOUR_SERVICE] with the service you are integrating with and need KMS integration. E.g.
+            use _logs_ as the service name for integrating with CloudWatch Logs service.
          <pre>
             {
                 "Version": "2012-10-17",
@@ -68,44 +69,41 @@ sample for now this can be used for injecting credentials using the role based p
             }
          </pre>
      </li>
-     <li><u>Create a user cfn-assume-role with Managed Policy create in (1)</u>
+     <li><u>Create a user cfn-assume-role with Managed Policy create in Step (1)</u>
             Download the access_key, secret_key for this user and add it to the credentials file under
             cfn-assume-role
      </li>
-     <li><u>Create cfn-integration role with the con</u></li>
+     <li><u>Create cfn-integration role with the reference to the managed policy we created above.</u></li>
      <li><u>Update your poml.xml</u>
             Here is how to use this for unit testing. First add the dependency to you maven <u>pom.xml</u>
-
-            <pre>{@code
-                <!-- for sts support to assume role setup above -->
-                <dependency>
-                    <groupId>software.amazon.awssdk</groupId>
-                    <artifactId>sts</artifactId>
-                    <version>2.10.91</version>
-                    <scope>test</scope>
-                </dependency>
-
-               <!-- for kms key handling support -->
-               <dependency>
-                    <groupId>software.amazon.awssdk</groupId>
-                    <artifactId>kms</artifactId>
-                    <version>2.10.91</version>
-               </dependency>
-
-                <dependency>
-                    <groupId>software.amazon.cloudformation.test</groupId>
-                    <artifactId>cloudformation-cli-java-plugin-testing-support</artifactId>
-                    <version>1.0-SNAPSHOT</version>
-                    <scope>test</scope>
-                </dependency>
-           }</pre>
+            <pre><code>
+                &lt;!-- for sts support to assume role setup above --&gt;
+                &lt;dependency&gt;
+                    &lt;groupId&gt;software.amazon.awssdk&lt;/groupId&gt;
+                    &lt;artifactId&gt;sts&lt;/artifactId&gt;
+                    &lt;version&gt;2.10.91&lt;/version&gt;
+                    &lt;scope&gt;test&lt;/scope&gt;
+                &lt;/dependency&gt;
+               &lt;!-- for kms key handling support --&gt;
+               &lt;dependency&gt;
+                    &lt;groupId&gt;software.amazon.awssdk&lt;/groupId&gt;
+                    &lt;artifactId&gt;kms&lt;/artifactId&gt;
+                    &lt;version&gt;2.10.91&lt;/version&gt;
+               &lt;/dependency&gt;
+                &lt;dependency&gt;
+                    &lt;groupId&gt;software.amazon.cloudformation.test&lt;/groupId&gt;
+                    &lt;artifactId&gt;cloudformation-cli-java-plugin-testing-support&lt;/artifactId&gt;
+                    &lt;version&gt;1.0.0&lt;/version&gt;
+                    &lt;scope&gt;test&lt;/scope&gt;
+                &lt;/dependency&gt;
+           </code></pre>
       </li>
 </ol>
 
 <b>How to use it?</b>
 <p>
 Sample code illustrating how to use this setup with KMS. To make scheduling the key for delete in case of abort to
-testing the key is aliased using the alias name [KEY_ALIAS](src/software/amazon/cloudformation/test/KMSKeyEnabledServiceIntegrationTestBase.java)
+testing the key is aliased using the alias name [KEY_ALIAS](src/main/software/amazon/cloudformation/test/KMSKeyEnabledServiceIntegrationTestBase.java)
 The test when it runs to completion will automatically move the KMS key for delete. If test is rerun
 the KMS key will be made active again for the duration of he test run and disable and scheduled to be deleted.
 Regardless of how many times we run these tests there is only one key with the alias managed in the account.
@@ -114,8 +112,8 @@ To ensure that this test does not run for build environments like Travis etc. we
 {@link org.junit.jupiter.api.condition.EnabledIfSystemProperty}. To run the test with maven we would
 use
 
-```
-    mvn -Ddesktop=true test
+```sh
+mvn -Ddesktop=true test
 ```
 
 to run the test code shown below
@@ -156,8 +154,8 @@ to run the test code shown below
             String kmsKeyArn = getKmsKeyArn();
             // Add your service to use KMS key
             addServiceAccess("logs", kmsKeyId);
-            model.setKMSKey(kmsKeyArn);
-            ProgressEvent&lt;ResourceModel, CallbackContext&gt; event = new UpdateHandler()
+            model.setKMSKeyArn(kmsKeyArn);
+            ProgressEvent<ResourceModel, CallbackContext> event = new UpdateHandler()
                 .handleRequest(getProxy(), createRequest(model, current), null, getLoggerProxy());
             assertThat(event.isSuccess()).isTrue();
             model = event.getResourceModel();
@@ -167,10 +165,101 @@ to run the test code shown below
     }
 ```
 
+**Example Lifecycle Testing with KMS Support**
+
+```java
+@ExtendWith(InjectProfileCredentials.class)
+@EnabledIfSystemProperty(named = "desktop", matches = "true")
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+public class CRUDLifecycleTest extends CRUDLifecycleTestBase<ResourceModel, CallbackContext> {
+
+    private final ReadHandler readHandler = new ReadHandler();
+    private final DeleteHandler deleteHandler = new DeleteHandler();
+    private final UpdateHandler updateHandler = new UpdateHandler();
+    private final CreateHandler createHandler = new CreateHandler();
+    private final Map<Action, HandlerInvoke<ResourceModel, CallbackContext>> handlers =
+        ImmutableMap.<Action, HandlerInvoke<ResourceModel, CallbackContext>>builder()
+            .put(Action.CREATE, createHandler::handleRequest)
+            .put(Action.READ, readHandler::handleRequest)
+            .put(Action.UPDATE, updateHandler::handleRequest)
+            .put(Action.DELETE, deleteHandler::handleRequest)
+        .build();
+
+    private final String logGroupName = "logGroup-TEST-DELETE-" + UUID.randomUUID().toString();
+
+    static final Delay override = Constant.of().delay(Duration.ofSeconds(1))
+        .timeout(Duration.ofSeconds(10)).build();
+    public CRUDLifecycleTest(@InjectSessionCredentials(profile = "cfn-integ") AwsSessionCredentials sessionCredentials) {
+        super(sessionCredentials, ((apiCall, provided) -> override));
+    }
+
+    @Override
+    protected List<ResourceModels> testSeed() {
+        final String kmsKeyId = getKmsKeyId();
+        final String kmsKeyArn = getKmsKeyArn();
+        List<ResourceModels> testGroups = new ArrayList<>(1);
+
+        testGroups.add(
+            newStepBuilder()
+                .group("simple_normal")
+                .create(ResourceModel.builder().logGroupName(logGroupName).build())
+                .update(ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7).build())
+                .delete(ResourceModel.builder().logGroupName(logGroupName).build()));
+
+        testGroups.add(
+            newStepBuilder()
+                .group("complex_with_failed_kms")
+                .create(ResourceModel.builder().logGroupName(logGroupName).build())
+                .createFail(ResourceModel.builder().logGroupName(logGroupName).build())
+                .updateFail(ResourceModel.builder().logGroupName(logGroupName).retentionInDays(10).build())
+                .update(ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7).build())
+                .updateFail(
+                    ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7)
+                        .kMSKey("kmsKeyDoesNotExist").build())
+                //
+                // can not access logs service
+                //
+                .updateFail(() -> {
+                    removeServiceAccess("logs", kmsKeyId, Region.US_EAST_2);
+                    return ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7)
+                        .kMSKey(kmsKeyArn).build();
+                })
+                .update(() -> {
+                    addServiceAccess("logs", kmsKeyId, Region.US_EAST_2);
+                    return ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7)
+                        .kMSKey(kmsKeyArn).build();
+                })
+                .delete(ResourceModel.builder().logGroupName(logGroupName).build()));
+        return testGroups;
+    }
+
+    @Override
+    protected Map<Action, HandlerInvoke<ResourceModel, CallbackContext>> handlers() {
+        return handlers;
+    }
+
+    @Override
+    protected CallbackContext context() {
+        return new CallbackContext();
+    }
+}
+
+```
+
 **See Also**
 
-software.amazon.cloudformation.test.KMSKeyEnabledServiceIntegrationTestBase
-software.amazon.cloudformation.test.AbstractLifecycleTestBase
+*Lifecycle Testing*
+
+These classes use the annotation and named profiles described above to make testing against live AWS services easy.
+
+[software.amazon.cloudformation.test.KMSKeyEnabledServiceIntegrationTestBase](src/main/software/amazon/cloudformation/test/KMSKeyEnabledServiceIntegrationTestBase.java)
+[software.amazon.cloudformation.test.AbstractLifecycleTestBase](src/main/software/amazon/cloudformation/test/AbstractLifecycleTestBase.java)
+
+*Local Unit Testing*
+
+This class provides the step plumbing
+
+[software.amazon.cloudformation.test.AbstractMockTestBase](src/main/software/amazon/cloudformation/test/AbstractMockTestBase.java)
 
 
 ## License

buildspec.yaml

@@ -10,4 +10,3 @@ phases:
     commands:
       - pre-commit run --all-files
       - mvn clean verify --no-transfer-progress
-      - mvn clean verify --no-transfer-progress

pom.xml

@@ -8,7 +8,7 @@
     <groupId>software.amazon.cloudformation.test</groupId>
     <artifactId>cloudformation-cli-java-plugin-testing-support</artifactId>
     <name>aws-cloudformation-local-test</name>
-    <version>1.0</version>
+    <version>1.0.0</version>
     <packaging>jar</packaging>
 
     <properties>
@@ -81,7 +81,7 @@
         <dependency>
             <groupId>software.amazon.cloudformation</groupId>
             <artifactId>aws-cloudformation-rpdk-java-plugin</artifactId>
-            <version>1.0.3</version>
+            <version>1.0.4</version>
         </dependency>
 
         <dependency>
@@ -145,7 +145,7 @@
                 <version>${maven-javadoc-plugin.version}</version>
                 <configuration>
                     <show>public</show>
-                    <bottom><![CDATA[Copyright &#169; 2019 Amazon Web Services, Inc. All Rights Reserved.]]></bottom>
+                    <bottom><![CDATA[Copyright &#169; Amazon Web Services, Inc. All Rights Reserved.]]></bottom>
                 </configuration>
                 <executions>
                     <execution>

src/main/java/software/amazon/cloudformation/test/CRUDLifecycleTestBase.java

@@ -6,7 +6,6 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
-import org.opentest4j.AssertionFailedError;
 import software.amazon.awssdk.auth.credentials.AwsSessionCredentials;
 import software.amazon.cloudformation.Action;
 import software.amazon.cloudformation.exceptions.ResourceNotFoundException;
@@ -27,8 +26,6 @@
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
-import java.util.stream.Stream;
-
 
 @NotThreadSafe
 @TestInstance(TestInstance.Lifecycle.PER_CLASS)
@@ -230,6 +227,15 @@ final List<DynamicTest> CRUD_Tests() {
                             }
                         )
                     );
+                    //
+                    // https://junit.org/junit5/docs/5.0.2/api/org/junit/jupiter/api/DynamicTest.html. This is verifying
+                    // that reading the state after Create(C)/Update(U) operation is consistent with the desired state that we
+                    // sent in. If the C/U is expected to fail, then we check to see that the previous desired state is
+                    // indeed equal. The other thing this forces is it ensures that C/U handlers do delegate to Read(R)
+                    // handlers post application of configuration. This prevents the set of bugs like missing primary
+                    // identifiers etc. that R always provides ensuring all read-only attributes are being communicated
+                    // post a C/U operation.
+                    //
                     if (step.action != Action.DELETE) {
                         tests.add(
                             //

src/main/java/software/amazon/cloudformation/test/package-info.java

@@ -74,7 +74,7 @@
  *             Download the access_key, secret_key for this user and add it to the credentials file under
  *             cfn-assume-role
  *      </li>
- *      <li><u>Create cfn-integration role with the con</u></li>
+ *      <li><u>Create cfn-integration role with the reference to the managed policy we created above.</u></li>
  *      <li><u>Update your poml.xml</u>
  *             Here is how to use this for unit testing. First add the dependency to you maven <u>pom.xml</u>
  *