{"id":18940778,"url":"https://github.com/aws-cloudformation/cloudformation-cli-java-plugin-testing-support","last_synced_at":"2025-04-15T19:31:36.719Z","repository":{"id":54299422,"uuid":"252536930","full_name":"aws-cloudformation/cloudformation-cli-java-plugin-testing-support","owner":"aws-cloudformation","description":"Testing Framework for the CloudFormation Provider Development Toolkit Java Plugin allows you to autogenerate java code based on an input schema.","archived":false,"fork":false,"pushed_at":"2022-11-16T01:19:41.000Z","size":71,"stargazers_count":3,"open_issues_count":1,"forks_count":4,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-29T01:42:14.532Z","etag":null,"topics":["cloudformation-cli","java","resources"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-cloudformation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-02T18:36:23.000Z","updated_at":"2023-05-27T12:25:10.000Z","dependencies_parsed_at":"2022-08-13T11:20:43.908Z","dependency_job_id":null,"html_url":"https://github.com/aws-cloudformation/cloudformation-cli-java-plugin-testing-support","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-cloudformation%2Fcloudformation-cli-java-plugin-testing-support","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-cloudformation%2Fcloudformation-cli-java-plugin-testing-support/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-cloudformation%2Fcloudformation-cli-java-plugin-testing-support/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-cloudformation%2Fcloudformation-cli-java-plugin-testing-support/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-cloudformation","download_url":"https://codeload.github.com/aws-cloudformation/cloudformation-cli-java-plugin-testing-support/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249138799,"owners_count":21218950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudformation-cli","java","resources"],"created_at":"2024-11-08T12:24:12.486Z","updated_at":"2025-04-15T19:31:36.459Z","avatar_url":"https://github.com/aws-cloudformation.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"## AWS CloudFormation Java Plugin Test Framework\n\nThis provides an easier foundation for testing handlers for CRUD along with integated support for KMS. Developers\ncan easily write sequence of CRUD lifecycle test with expectations and will be tested. There is also a mock based\ntest based for local unit testing.\n\nThe framework leverages support for [Named Profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) that allows\ndevelopers 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\nsample for now this can be used for injecting credentials using the role based profile specified.\n\n**Sample AWS Named Profile Setup**\n\n```\n ~/.aws/credentials\n ...\n [cfn-assume-role]\n aws_access_key_id=[YOUR_ACCESS_KEY_ID]\n aws_secret_access_key=[YOUR_SECRET_ACCESS_KEY]\n ...\n\n ~/.aws/config\n [profile cfn-integration]\n role_arn = arn:aws:iam::\u003cAWS_ACCOUNT_ID\u003e:role/\u003cROLE_NAME\u003e\n source_profile = cfn-assume-role\n```\n\n**Using the named profile for testing**\n\n\u003cb\u003eHow to setup IAM managed policies, user and role credentials for above setup\u003c/b\u003e\n\n\u003col\u003e\n    \u003cli\u003e\u003cu\u003eCreate a Managed Policy for the user\u003c/u\u003e\n        Here the credentials section has an user credentials that is provided with only sts:assumeRole\n        permission. Here is the policy that is associated with cfn-assume-role user in the account.\n        \u003cpre\u003e\n        {\n            \"Version\": \"2012-10-17\",\n            \"Statement\": [\n                {\n                    \"Sid\": \"VisualEditor0\",\n                    \"Effect\": \"Allow\",\n                    \"Action\": \"sts:AssumeRole\",\n                    \"Resource\": \"*\"\n                }\n            ]\n        }\n        \u003c/pre\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003cu\u003eCreate a Managed Policy for the services you are testing with\u003c/u\u003e\n            This is needed to test all integration for CRUD+L needed for logs. You can always narrow it down further.\n            Recommended approach is to define the above policies as customer managed policies in IAM in the account and\n            associate with the role and users as appropriate. This is an example policy to test, replace\n            [INSERT_YOUR_SERVICE] with the service you are integrating with and need KMS integration. E.g.\n            use _logs_ as the service name for integrating with CloudWatch Logs service.\n         \u003cpre\u003e\n            {\n                \"Version\": \"2012-10-17\",\n                \"Statement\": [\n                    {\n                        \"Sid\": \"VisualEditor0\",\n                        \"Effect\": \"Allow\",\n                        \"Action\": [\n                            \"kms:*\",\n                            \"[INSERT_YOUR_SERVICE]:*\"\n                        ],\n                        \"Resource\": \"*\"\n                    }\n                ]\n            }\n         \u003c/pre\u003e\n     \u003c/li\u003e\n     \u003cli\u003e\u003cu\u003eCreate a user cfn-assume-role with Managed Policy create in Step (1)\u003c/u\u003e\n            Download the access_key, secret_key for this user and add it to the credentials file under\n            cfn-assume-role\n     \u003c/li\u003e\n     \u003cli\u003e\u003cu\u003eCreate cfn-integration role with the reference to the managed policy we created above.\u003c/u\u003e\u003c/li\u003e\n     \u003cli\u003e\u003cu\u003eUpdate your poml.xml\u003c/u\u003e\n            Here is how to use this for unit testing. First add the dependency to you maven \u003cu\u003epom.xml\u003c/u\u003e\n            \u003cpre\u003e\u003ccode\u003e\n                \u0026lt;!-- for sts support to assume role setup above --\u0026gt;\n                \u0026lt;dependency\u0026gt;\n                    \u0026lt;groupId\u0026gt;software.amazon.awssdk\u0026lt;/groupId\u0026gt;\n                    \u0026lt;artifactId\u0026gt;sts\u0026lt;/artifactId\u0026gt;\n                    \u0026lt;version\u0026gt;2.10.91\u0026lt;/version\u0026gt;\n                    \u0026lt;scope\u0026gt;test\u0026lt;/scope\u0026gt;\n                \u0026lt;/dependency\u0026gt;\n               \u0026lt;!-- for kms key handling support --\u0026gt;\n               \u0026lt;dependency\u0026gt;\n                    \u0026lt;groupId\u0026gt;software.amazon.awssdk\u0026lt;/groupId\u0026gt;\n                    \u0026lt;artifactId\u0026gt;kms\u0026lt;/artifactId\u0026gt;\n                    \u0026lt;version\u0026gt;2.10.91\u0026lt;/version\u0026gt;\n               \u0026lt;/dependency\u0026gt;\n                \u0026lt;dependency\u0026gt;\n                    \u0026lt;groupId\u0026gt;software.amazon.cloudformation.test\u0026lt;/groupId\u0026gt;\n                    \u0026lt;artifactId\u0026gt;cloudformation-cli-java-plugin-testing-support\u0026lt;/artifactId\u0026gt;\n                    \u0026lt;version\u0026gt;1.0.0\u0026lt;/version\u0026gt;\n                    \u0026lt;scope\u0026gt;test\u0026lt;/scope\u0026gt;\n                \u0026lt;/dependency\u0026gt;\n           \u003c/code\u003e\u003c/pre\u003e\n      \u003c/li\u003e\n\u003c/ol\u003e\n\n\u003cb\u003eHow to use it?\u003c/b\u003e\n\u003cp\u003e\nSample code illustrating how to use this setup with KMS. To make scheduling the key for delete in case of abort to\ntesting the key is aliased using the alias name [KEY_ALIAS](src/main/java/software/amazon/cloudformation/test/KMSKeyEnabledServiceIntegrationTestBase.java)\nThe test when it runs to completion will automatically move the KMS key for delete. If test is rerun\nthe KMS key will be made active again for the duration of he test run and disable and scheduled to be deleted.\nRegardless of how many times we run these tests there is only one key with the alias managed in the account.\n\nTo ensure that this test does not run for build environments like Travis etc. we enable is using system properties using\n{@link org.junit.jupiter.api.condition.EnabledIfSystemProperty}. To run the test with maven we would\nuse\n\n```sh\nmvn -Ddesktop=true test\n```\n\nto run the test code shown below\n\n```java\n\n    package software.amazon.logs.loggroup;\n\n    import org.junit.jupiter.api.*;\n    import static org.assertj.core.api.Assertions.assertThat;\n\n    import software.amazon.awssdk.auth.credentials.AwsSessionCredentials;\n    import software.amazon.cloudformation.proxy.*;\n    import software.amazon.cloudformation.test.*;\n\n    @TestMethodOrder(MethodOrderer.OrderAnnotation.class) // we order the tests to follows C to U to D\n    @ExtendWith(InjectProfileCredentials.class) // extend with profile based credentials\n    @EnabledIfSystemProperty(named = \"desktop\", matches = \"true\")\n    @TestInstance(TestInstance.Lifecycle.PER_CLASS) // IMP PER_CLASS\n    public class LifecycleTest extends KMSKeyEnabledServiceIntegrationTestBase {\n\n        //\n        // At the annotation software.amazon.cloudformation.test.annotations.InjectSessionCredentials to the\n        // constructor. This will inject the role's credentials\n        //\n        public LifecycleTest(@InjectSessionCredentials(profile = \"cfn-integration\") AwsSessionCredentials awsCredentials) {\n             super(awsCredentials, ((apiCall, provided) -\u0026gt; override));\n        }\n        ...\n        ...\n        @Order(300)\n        @Test\n        void addValidKMS() {\n            final ResourceModel current = ResourceModel.builder().arn(model.getArn())\n                .logGroupName(model.getLogGroupName()).retentionInDays(model.getRetentionInDays()).build();\n            // Access a KMS key. The test ensures to only create one key and recycles despite any number of runs\n            String kmsKeyId = getKmsKeyId();\n            String kmsKeyArn = getKmsKeyArn();\n            // Add your service to use KMS key\n            addServiceAccess(\"logs\", kmsKeyId);\n            model.setKMSKeyArn(kmsKeyArn);\n            ProgressEvent\u003cResourceModel, CallbackContext\u003e event = new UpdateHandler()\n                .handleRequest(getProxy(), createRequest(model, current), null, getLoggerProxy());\n            assertThat(event.isSuccess()).isTrue();\n            model = event.getResourceModel();\n        }\n        ...\n        ...\n    }\n```\n\n**Example Lifecycle Testing with KMS Support**\n\n```java\n@ExtendWith(InjectProfileCredentials.class)\n@EnabledIfSystemProperty(named = \"desktop\", matches = \"true\")\n@TestInstance(TestInstance.Lifecycle.PER_CLASS)\npublic class CRUDLifecycleTest extends CRUDLifecycleTestBase\u003cResourceModel, CallbackContext\u003e {\n\n    private final ReadHandler readHandler = new ReadHandler();\n    private final DeleteHandler deleteHandler = new DeleteHandler();\n    private final UpdateHandler updateHandler = new UpdateHandler();\n    private final CreateHandler createHandler = new CreateHandler();\n    private final Map\u003cAction, HandlerInvoke\u003cResourceModel, CallbackContext\u003e\u003e handlers =\n        ImmutableMap.\u003cAction, HandlerInvoke\u003cResourceModel, CallbackContext\u003e\u003ebuilder()\n            .put(Action.CREATE, createHandler::handleRequest)\n            .put(Action.READ, readHandler::handleRequest)\n            .put(Action.UPDATE, updateHandler::handleRequest)\n            .put(Action.DELETE, deleteHandler::handleRequest)\n        .build();\n\n    private final String logGroupName = \"logGroup-TEST-DELETE-\" + UUID.randomUUID().toString();\n\n    static final Delay override = Constant.of().delay(Duration.ofSeconds(1))\n        .timeout(Duration.ofSeconds(10)).build();\n    public CRUDLifecycleTest(@InjectSessionCredentials(profile = \"cfn-integ\") AwsSessionCredentials sessionCredentials) {\n        super(sessionCredentials, ((apiCall, provided) -\u003e override));\n    }\n\n    @Override\n    protected List\u003cResourceModels\u003e testSeed() {\n        final String kmsKeyId = getKmsKeyId();\n        final String kmsKeyArn = getKmsKeyArn();\n        List\u003cResourceModels\u003e testGroups = new ArrayList\u003c\u003e(1);\n\n        testGroups.add(\n            newStepBuilder()\n                .group(\"simple_normal\")\n                .create(ResourceModel.builder().logGroupName(logGroupName).build())\n                .update(ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7).build())\n                .delete(ResourceModel.builder().logGroupName(logGroupName).build()));\n\n        testGroups.add(\n            newStepBuilder()\n                .group(\"complex_with_failed_kms\")\n                .create(ResourceModel.builder().logGroupName(logGroupName).build())\n                .createFail(ResourceModel.builder().logGroupName(logGroupName).build())\n                .updateFail(ResourceModel.builder().logGroupName(logGroupName).retentionInDays(10).build())\n                .update(ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7).build())\n                .updateFail(\n                    ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7)\n                        .kMSKey(\"kmsKeyDoesNotExist\").build())\n                //\n                // can not access logs service\n                //\n                .updateFail(() -\u003e {\n                    removeServiceAccess(\"logs\", kmsKeyId, Region.US_EAST_2);\n                    return ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7)\n                        .kMSKey(kmsKeyArn).build();\n                })\n                .update(() -\u003e {\n                    addServiceAccess(\"logs\", kmsKeyId, Region.US_EAST_2);\n                    return ResourceModel.builder().logGroupName(logGroupName).retentionInDays(7)\n                        .kMSKey(kmsKeyArn).build();\n                })\n                .delete(ResourceModel.builder().logGroupName(logGroupName).build()));\n        return testGroups;\n    }\n\n    @Override\n    protected Map\u003cAction, HandlerInvoke\u003cResourceModel, CallbackContext\u003e\u003e handlers() {\n        return handlers;\n    }\n\n    @Override\n    protected CallbackContext context() {\n        return new CallbackContext();\n    }\n}\n\n```\n\n**See Also**\n\n*Lifecycle Testing*\n\nThese classes use the annotation and named profiles described above to make testing against live AWS services easy.\n\n[software.amazon.cloudformation.test.KMSKeyEnabledServiceIntegrationTestBase](src/main/java/software/amazon/cloudformation/test/KMSKeyEnabledServiceIntegrationTestBase.java)\n[software.amazon.cloudformation.test.AbstractLifecycleTestBase](src/main/java/software/amazon/cloudformation/test/AbstractLifecycleTestBase.java)\n\n*Local Unit Testing*\n\nThis class provides the step plumbing\n\n[software.amazon.cloudformation.test.AbstractMockTestBase](src/main/java/software/amazon/cloudformation/test/AbstractMockTestBase.java)\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-cloudformation%2Fcloudformation-cli-java-plugin-testing-support","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-cloudformation%2Fcloudformation-cli-java-plugin-testing-support","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-cloudformation%2Fcloudformation-cli-java-plugin-testing-support/lists"}