AWS cdk documentation change
Summary
Updated punctuation and formatting (curly quotes, ellipses, apostrophes) throughout the documentation. Fixed code syntax examples (Java braces). Minor grammatical improvements.
Security assessment
Changes are purely editorial/formatting in nature. No security-related content was added or modified. Focus remains on testing methodologies without addressing vulnerabilities, security controls, or security features.
Diff
diff --git a/cdk/v2/guide/testing.md b/cdk/v2/guide/testing.md index 65b04acb0..bb878b26b 100644 --- a//cdk/v2/guide/testing.md +++ b//cdk/v2/guide/testing.md @@ -11 +11 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -With the AWS CDK, your infrastructure can be as testable as any other code you write. You can test in the cloud and locally. This topic addresses how to test in the cloud. For guidance on local testing see [Locally test and build AWS CDK applications with the AWS SAM CLI](./testing-locally.html). The standard approach to testing AWS CDK apps uses the AWS CDK's [assertions](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions-readme.html) module and popular test frameworks like [Jest](https://jestjs.io/) for TypeScript and JavaScript or [Pytest](https://docs.pytest.org/en/6.2.x/) for Python. +With the AWS CDK, your infrastructure can be as testable as any other code you write. You can test in the cloud and locally. This topic addresses how to test in the cloud. For guidance on local testing see [Locally test and build AWS CDK applications with the AWS SAM CLI](./testing-locally.html). The standard approach to testing AWS CDK apps uses the AWS CDK’s [assertions](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions-readme.html) module and popular test frameworks like [Jest](https://jestjs.io/) for TypeScript and JavaScript or [Pytest](https://docs.pytest.org/en/6.2.x/) for Python. @@ -15 +15 @@ There are two categories of tests that you can write for AWS CDK apps. - * **Fine-grained assertions** test specific aspects of the generated AWS CloudFormation template, such as "this resource has this property with this value." These tests can detect regressions. They're also useful when you're developing new features using test-driven development. (You can write a test first, then make it pass by writing a correct implementation.) Fine-grained assertions are the most frequently used tests. + * **Fine-grained assertions** test specific aspects of the generated AWS CloudFormation template, such as "this resource has this property with this value." These tests can detect regressions. They’re also useful when you’re developing new features using test-driven development. (You can write a test first, then make it pass by writing a correct implementation.) Fine-grained assertions are the most frequently used tests. @@ -17 +17 @@ There are two categories of tests that you can write for AWS CDK apps. - * **Snapshot tests** test the synthesized AWS CloudFormation template against a previously stored baseline template. Snapshot tests let you refactor freely, since you can be sure that the refactored code works exactly the same way as the original. If the changes were intentional, you can accept a new baseline for future tests. However, CDK upgrades can also cause synthesized templates to change, so you can't rely only on snapshots to make sure that your implementation is correct. + * **Snapshot tests** test the synthesized AWS CloudFormation template against a previously stored baseline template. Snapshot tests let you refactor freely, since you can be sure that the refactored code works exactly the same way as the original. If the changes were intentional, you can accept a new baseline for future tests. However, CDK upgrades can also cause synthesized templates to change, so you can’t rely only on snapshots to make sure that your implementation is correct. @@ -28 +28 @@ Complete versions of the TypeScript, Python, and Java apps used as examples in t -To illustrate how to write these tests, we'll create a stack that contains an AWS Step Functions state machine and an AWS Lambda function. The Lambda function is subscribed to an Amazon SNS topic and simply forwards the message to the state machine. +To illustrate how to write these tests, we’ll create a stack that contains an AWS Step Functions state machine and an AWS Lambda function. The Lambda function is subscribed to an Amazon SNS topic and simply forwards the message to the state machine. @@ -30 +30 @@ To illustrate how to write these tests, we'll create a stack that contains an AW -First, create an empty CDK application project using the CDK Toolkit and installing the libraries we'll need. The constructs we'll use are all in the main CDK package, which is a default dependency in projects created with the CDK Toolkit. However, you must install your testing framework. +First, create an empty CDK application project using the CDK Toolkit and installing the libraries we’ll need. The constructs we’ll use are all in the main CDK package, which is a default dependency in projects created with the CDK Toolkit. However, you must install your testing framework. @@ -45 +45 @@ Create a directory for your tests. -Edit the project's `package.json` to tell NPM how to run Jest, and to tell Jest what kinds of files to collect. The necessary changes are as follows. +Edit the project’s `package.json` to tell NPM how to run Jest, and to tell Jest what kinds of files to collect. The necessary changes are as follows. @@ -56 +56 @@ Edit the project's `package.json` to tell NPM how to run Jest, and to tell Jest -These changes are shown in the following outline. Place the new text where indicated in `package.json`. The "..." placeholders indicate existing parts of the file that should not be changed. +These changes are shown in the following outline. Place the new text where indicated in `package.json`. The "…" placeholders indicate existing parts of the file that should not be changed. @@ -88 +88 @@ Create a directory for your tests. -Edit the project's `package.json` to tell NPM how to run Jest, and to tell Jest what kinds of files to collect. The necessary changes are as follows. +Edit the project’s `package.json` to tell NPM how to run Jest, and to tell Jest what kinds of files to collect. The necessary changes are as follows. @@ -99 +99 @@ Edit the project's `package.json` to tell NPM how to run Jest, and to tell Jest -These changes are shown in the following outline. Place the new text where indicated in `package.json`. The "..." placeholders indicate existing parts of the file that shouldn't be changed. +These changes are shown in the following outline. Place the new text where indicated in `package.json`. The "…" placeholders indicate existing parts of the file that shouldn’t be changed. @@ -151 +151 @@ Right-click `TestProject1` and choose **Add** > **Project Reference** , and add -Here's the stack that will be tested in this topic. As we've previously described, it contains a Lambda function and a Step Functions state machine, and accepts one or more Amazon SNS topics. The Lambda function is subscribed to the Amazon SNS topics and forwards them to the state machine. +Here’s the stack that will be tested in this topic. As we’ve previously described, it contains a Lambda function and a Step Functions state machine, and accepts one or more Amazon SNS topics. The Lambda function is subscribed to the Amazon SNS topics and forwards them to the state machine. @@ -153 +153 @@ Here's the stack that will be tested in this topic. As we've previously describe -You don't have to do anything special to make the app testable. In fact, this CDK stack is not different in any important way from the other example stacks in this Guide. +You don’t have to do anything special to make the app testable. In fact, this CDK stack is not different in any important way from the other example stacks in this Guide. @@ -390 +390 @@ C# -We'll modify the app's main entry point so that we don't actually instantiate our stack. We don't want to accidentally deploy it. Our tests will create an app and an instance of the stack for testing. This is a useful tactic when combined with test-driven development: make sure that the stack passes all tests before you enable deployment. +We’ll modify the app’s main entry point so that we don’t actually instantiate our stack. We don’t want to accidentally deploy it. Our tests will create an app and an instance of the stack for testing. This is a useful tactic when combined with test-driven development: make sure that the stack passes all tests before you enable deployment. @@ -481 +481 @@ Our example stack includes a Lambda function that starts our state machine. We m - * Create the folder `start-state-machine` in the app's main directory. + * Create the folder `start-state-machine` in the app’s main directory. @@ -489 +489 @@ Our example stack includes a Lambda function that starts our state machine. We m -However, any file will work, since we won't actually be deploying the stack. +However, any file will work, since we won’t actually be deploying the stack. @@ -496 +496 @@ However, any file will work, since we won't actually be deploying the stack. -For reference, here are the commands you use to run tests in your AWS CDK app. These are the same commands that you'd use to run the tests in any project using the same testing framework. For languages that require a build step, include that to make sure that your tests have compiled. +For reference, here are the commands you use to run tests in your AWS CDK app. These are the same commands that you’d use to run the tests in any project using the same testing framework. For languages that require a build step, include that to make sure that your tests have compiled. @@ -534 +534 @@ Or: -The first step for testing a stack with fine-grained assertions is to synthesize the stack, because we're writing assertions against the generated AWS CloudFormation template. +The first step for testing a stack with fine-grained assertions is to synthesize the stack, because we’re writing assertions against the generated AWS CloudFormation template. @@ -536 +536 @@ The first step for testing a stack with fine-grained assertions is to synthesize -Our `StateMachineStackStack` requires that we pass it the Amazon SNS topic to be forwarded to the state machine. So in our test, we'll create a separate stack to contain the topic. +Our `StateMachineStackStack` requires that we pass it the Amazon SNS topic to be forwarded to the state machine. So in our test, we’ll create a separate stack to contain the topic. @@ -538 +538 @@ Our `StateMachineStackStack` requires that we pass it the Amazon SNS topic to be -Ordinarily, when writing a CDK app, you can subclass `Stack` and instantiate the Amazon SNS topic in the stack's constructor. In our test, we instantiate `Stack` directly, then pass this stack as the `Topic`'s scope, attaching it to the stack. This is functionally equivalent and less verbose. It also helps make stacks that are used only in tests "look different" from the stacks that you intend to deploy. +Ordinarily, when writing a CDK app, you can subclass `Stack` and instantiate the Amazon SNS topic in the stack’s constructor. In our test, we instantiate `Stack` directly, then pass this stack as the `Topic`'s scope, attaching it to the stack. This is functionally equivalent and less verbose. It also helps make stacks that are used only in tests "look different" from the stacks that you intend to deploy. @@ -569,3 +569,2 @@ TypeScript - - - } + }) + }) @@ -602 +601,2 @@ JavaScript - + }) + }) @@ -673,0 +674,2 @@ Java + } + } @@ -794,2 +796 @@ C# - -Our Lambda function test asserts that two particular properties of the function resource have specific values. By default, the `hasResourceProperties` method performs a partial match on the resource's properties as given in the synthesized CloudFormation template. This test requires that the provided properties exist and have the specified values, but the resource can also have other properties, which are not tested. +Our Lambda function test asserts that two particular properties of the function resource have specific values. By default, the `hasResourceProperties` method performs a partial match on the resource’s properties as given in the synthesized CloudFormation template. This test requires that the provided properties exist and have the specified values, but the resource can also have other properties, which are not tested. @@ -799 +800 @@ Our Amazon SNS assertion asserts that the synthesized template contains a subscr -### Matchers +**Matchers** @@ -801 +801,0 @@ Our Amazon SNS assertion asserts that the synthesized template contains a subscr -The default partial matching behavior of `hasResourceProperties` can be changed using _matchers_ from the [`Match`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#methods) class. @@ -803 +803,3 @@ The default partial matching behavior of `hasResourceProperties` can be changed -Matchers range from lenient (`Match.anyValue`) to strict (`Match.objectEquals`). They can be nested to apply different matching methods to different parts of the resource properties. Using `Match.objectEquals` and `Match.anyValue` together, for example, we can test the state machine's IAM role more fully, while not requiring specific values for properties that may change. +The default partial matching behavior of `hasResourceProperties` can be changed using _matchers_ from the ` [Match](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#methods) ` class. + +Matchers range from lenient (`Match.anyValue`) to strict (`Match.objectEquals`). They can be nested to apply different matching methods to different parts of the resource properties. Using `Match.objectEquals` and `Match.anyValue` together, for example, we can test the state machine’s IAM role more fully, while not requiring specific values for properties that may change. @@ -961 +963 @@ Many CloudFormation resources include serialized JSON objects represented as str -For example, Step Functions state machines are defined using a string in the JSON-based [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html). We'll use `Match.serializedJson()` to make sure that our initial state is the only step. Again, we'll use nested matchers to apply different kinds of matching to different parts of the object. +For example, Step Functions state machines are defined using a string in the JSON-based [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html). We’ll use `Match.serializedJson()` to make sure that our initial state is the only step. Again, we’ll use nested matchers to apply different kinds of matching to different parts of the object. @@ -1089 +1090 @@ C# -### Capturing +**Capturing** @@ -1091 +1091,0 @@ C# -It's often useful to test properties to make sure they follow specific formats, or have the same value as another property, without needing to know their exact values ahead of time. The `assertions` module provides this capability in its [`Capture`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Capture.html) class. @@ -1093 +1093,3 @@ It's often useful to test properties to make sure they follow specific formats, -By specifying a `Capture` instance in place of a value in `hasResourceProperties`, that value is retained in the `Capture` object. The actual captured value can be retrieved using the object's `as` methods, including `asNumber()`, `asString()`, and `asObject`, and subjected to test. Use `Capture` with a matcher to specify the exact location of the value to be captured within the resource's properties, including serialized JSON properties. +It’s often useful to test properties to make sure they follow specific formats, or have the same value as another property, without needing to know their exact values ahead of time. The `assertions` module provides this capability in its ` [Capture](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Capture.html) ` class. + +By specifying a `Capture` instance in place of a value in `hasResourceProperties`, that value is retained in the `Capture` object. The actual captured value can be retrieved using the object’s `as` methods, including `asNumber()`, `asString()`, and `asObject`, and subjected to test. Use `Capture` with a matcher to specify the exact location of the value to be captured within the resource’s properties, including serialized JSON properties. @@ -1224 +1224 @@ C# -In _snapshot testing_ , you compare the entire synthesized CloudFormation template against a previously stored baseline (often called a "master") template. Unlike fine-grained assertions, snapshot testing isn't useful in catching regressions. This is because snapshot testing applies to the entire template, and things besides code changes can cause small (or not-so-small) differences in synthesis results. These changes may not even affect your deployment, but they will still cause a snapshot test to fail. +In _snapshot testing_ , you compare the entire synthesized CloudFormation template against a previously stored baseline (often called a "master") template. Unlike fine-grained assertions, snapshot testing isn’t useful in catching regressions. This is because snapshot testing applies to the entire template, and things besides code changes can cause small (or not-so-small) differences in synthesis results. These changes may not even affect your deployment, but they will still cause a snapshot test to fail. @@ -1226 +1226 @@ In _snapshot testing_ , you compare the entire synthesized CloudFormation templa -For example, you might update a CDK construct to incorporate a new best practice, which can cause changes to the synthesized resources or how they're organized. Alternatively, you might update the CDK Toolkit to a version that reports additional metadata. Changes to context values can also affect the synthesized template. +For example, you might update a CDK construct to incorporate a new best practice, which can cause changes to the synthesized resources or how they’re organized. Alternatively, you might update the CDK Toolkit to a version that reports additional metadata. Changes to context values can also affect the synthesized template. @@ -1455 +1454 @@ Remember, your tests will live just as long as the code they test, and they will -Don't copy and paste setup lines or common assertions. Instead, refactor this logic into fixtures or helper functions. Use good names that reflect what each test actually tests. +Don’t copy and paste setup lines or common assertions. Instead, refactor this logic into fixtures or helper functions. Use good names that reflect what each test actually tests. @@ -1457 +1456 @@ Don't copy and paste setup lines or common assertions. Instead, refactor this lo -Don't try to do too much in one test. Preferably, a test should test one and only one behavior. If you accidentally break that behavior, exactly one test should fail, and the name of the test should tell you what failed. This is more an ideal to be striven for, however; sometimes you will unavoidably (or inadvertently) write tests that test more than one behavior. Snapshot tests are, for reasons we've already described, especially prone to this problem, so use them sparingly. +Don’t try to do too much in one test. Preferably, a test should test one and only one behavior. If you accidentally break that behavior, exactly one test should fail, and the name of the test should tell you what failed. This is more an ideal to be striven for, however; sometimes you will unavoidably (or inadvertently) write tests that test more than one behavior. Snapshot tests are, for reasons we’ve already described, especially prone to this problem, so use them sparingly.