Skip to content

Commit 6860fec

Browse files
kaizencckaizencc
authored
docs(assertions): publish migration script (#18653)
Publishing our internal migration script written by @rix0rrr for others to benefit. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent 009d689 commit 6860fec

File tree

3 files changed

+241
-0
lines changed

3 files changed

+241
-0
lines changed

‎packages/@aws-cdk/assertions/MIGRATING.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Migrating to Assertions
2+
3+
Most of the APIs in the old `assert` module has a corresponding API in `assertions`.
4+
Make the following modifications to your CDK test files to migrate to the
5+
`@aws-cdk/assertions` module.
6+
7+
For a migration script that handles most common use cases for you, see
8+
[Migration Script](migration-script).
9+
10+
## Translation Guide
11+
12+
- Rewrite module imports that use `@aws-cdk/aws-assert` to `@aws-cdk/aws-assertions`.
13+
For example:
14+
15+
```ts
16+
import '@aws-cdk/assert/jest';
17+
import { ABSENT, SynthUtils, ResourcePart } from '@aws-cdk/assert';
18+
```
19+
20+
...becomes...
21+
22+
```ts
23+
import { Template } from '@aws-cdk/assertions';
24+
import { Match, Template } from '@aws-cdk/assertions';
25+
```
26+
27+
- Replace instances of `toHaveResource()` with `hasResourceProperties()` or `hasResource()`.
28+
For example:
29+
30+
```ts
31+
expect(stack).toHaveResource('FOO::BAR', {/*...*/});
32+
expect(stack).toHaveResource('FOO::BAR', {/*...*/}, ResourcePart.CompleteDefinition);
33+
```
34+
35+
...becomes...
36+
37+
```ts
38+
Template.fromStack(stack).hasResourceProperties('FOO::BAR', {/*...*/});
39+
Template.fromStack(stacK).hasResource('FOO::BAR', {/*...*/});
40+
```
41+
42+
- Replace instances of `toCountResources()` with `resourceCountIs`. For example:
43+
44+
```ts
45+
expect(stack).toCountResources('FOO::BAR', 1);
46+
```
47+
48+
...becomes...
49+
50+
```ts
51+
Template.fromStack(stack).resourceCountIs('FOO::BAR', 1);
52+
```
53+
- Replace instances of `toMatchTemplate()` with `templateMatches()`. For example:
54+
55+
```ts
56+
expect(stack).toMatchTemplate({/*...*/});
57+
```
58+
59+
...becomes...
60+
61+
```ts
62+
Template.fromStack(stack).templateMatches({/*...*/});
63+
```
64+
65+
- Replace `arrayWith()` with `Match.arrayWith()`, `objectLike()` with `Match.objectLike()`, and
66+
`ABSENT` with `Match.absent()`.
67+
68+
- `not` can be replaced with `Match.not()` _or_ `resourceCountIs()` depending on the use case.
69+
70+
```ts
71+
// asserting that the stack does not have a particular resource.
72+
expect(stack).not.toHaveResource('FOO::BAR');
73+
```
74+
75+
...becomes...
76+
77+
```ts
78+
Template.fromStack(stack).resourceCountIs('FOO::BAR', 0);
79+
```
80+
81+
```ts
82+
// asserting that the stack does not have a resource with these properties
83+
expect(stack).not.toHaveResource('FOO::BAR', {
84+
prop: 'does not exist',
85+
});
86+
```
87+
88+
...becomes...
89+
90+
```ts
91+
Template.fromStack(stack).hasResourceProperties('FOO::BAR', Match.not({
92+
prop: 'does not exist',
93+
}));
94+
```
95+
96+
- `SynthUtils.synthesize(stack)` can be replaced as well. For example:
97+
98+
```ts
99+
expect(SynthUtils.synthesize(stack).template).toEqual(/*...*/);
100+
SynthUtils.syntesize(stack);
101+
```
102+
103+
...becomes...
104+
105+
```ts
106+
expect(Template.fromStack(stack).toJSON()).toEqual(/*...*/);
107+
App.of(stack).synth();
108+
```
109+
110+
## Migration Script
111+
112+
> NOTE: We have some code rewrite rules that will make it easier to migrate from one library
113+
> to the other. This tool will not do a complete rewrite and is not guaranteed to produce
114+
> compilable code! It will just save you the effort of performing a lot of code substitutions
115+
> you would otherwise have to do by hand.
116+
117+
Comby is a tool used to do structured code rewriting. You can install it
118+
[here](https://comby.dev/). Download the [rewrite.toml](rewrite.toml) file from our GitHub
119+
repository, and run the following command in the root directory of your project:
120+
121+
```bash
122+
comby -config ~/rewrite.toml -f .ts -d test -in-place -timeout 10
123+
```

‎packages/@aws-cdk/assertions/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@
99

1010
<!--END STABILITY BANNER-->
1111

12+
If you're migrating from the old `assert` library, the migration guide can be found in
13+
[our GitHub repository](https://github.com/aws/aws-cdk/blob/master/packages/@aws-cdk/assertions/MIGRATING.md).
14+
1215
Functions for writing test asserting against CDK applications, with focus on CloudFormation templates.
1316

1417
The `Template` class includes a set of methods for writing assertions against CloudFormation templates. Use one of the `Template.fromXxx()` static methods to create an instance of this class.

‎packages/@aws-cdk/assertions/rewrite.toml

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# comby -config ~/rewrite.toml -f .ts -d test -in-place -timeout 10
2+
3+
[000_import]
4+
match="import '@aws-cdk/assert-internal/jest'"
5+
rewrite="import { Template } from '@aws-cdk/assertions'"
6+
7+
[000_import2]
8+
match="import :[_] from '@aws-cdk/assert-internal'"
9+
rewrite="import { Template } from '@aws-cdk/assertions'"
10+
11+
[100_jest_toHaveResourceLike_CompleteDefinition]
12+
match="expect(:[stack]).toHaveResourceLike(:[args], ResourcePart.CompleteDefinition)"
13+
rewrite="Template.fromStack(:[stack]).hasResource(:[args])"
14+
15+
[100_assert_toHaveResourceLike_CompleteDefinition]
16+
match=":[[expect]](:[stack]).to(haveResourceLike(:[args], ResourcePart.CompleteDefinition))"
17+
rewrite="Template.fromStack(:[stack]).hasResource(:[args])"
18+
rule='''where match :[expect] {
19+
| "expect" -> true
20+
| "cdkExpect" -> true
21+
| ":[_]" -> false
22+
}'''
23+
24+
[100_jest_toHaveResource_CompleteDefinition]
25+
match="expect(:[stack]).toHaveResource(:[args], ResourcePart.CompleteDefinition)"
26+
rewrite="Template.fromStack(:[stack]).hasResource(:[args])"
27+
28+
[100_assert_toHaveResource_CompleteDefinition]
29+
match=":[[expect]](:[stack]).to(haveResource(:[args], ResourcePart.CompleteDefinition))"
30+
rewrite="Template.fromStack(:[stack]).hasResource(:[args])"
31+
rule='''where match :[expect] {
32+
| "expect" -> true
33+
| "cdkExpect" -> true
34+
| ":[_]" -> false
35+
}'''
36+
37+
[200_jest_toHaveResourceLike]
38+
match="expect(:[stack]).toHaveResourceLike(:[args])"
39+
rewrite="Template.fromStack(:[stack]).hasResourceProperties(:[args])"
40+
41+
[200_assert_toHaveResourceLike]
42+
match=":[[expect]](:[stack]).to(haveResourceLike(:[args]))"
43+
rewrite="Template.fromStack(:[stack]).hasResourceProperties(:[args])"
44+
rule='''where match :[expect] {
45+
| "expect" -> true
46+
| "cdkExpect" -> true
47+
| ":[_]" -> false
48+
}'''
49+
50+
[200_jest_toHaveResource]
51+
match="expect(:[stack]).toHaveResource(:[args])"
52+
rewrite="Template.fromStack(:[stack]).hasResourceProperties(:[args])"
53+
54+
[200_assert_toHaveResource]
55+
match=":[[expect]](:[stack]).to(haveResource(:[args]))"
56+
rewrite="Template.fromStack(:[stack]).hasResourceProperties(:[args])"
57+
rule='''where match :[expect] {
58+
| "expect" -> true
59+
| "cdkExpect" -> true
60+
| ":[_]" -> false
61+
}'''
62+
63+
[200_jest_toCountResources]
64+
match="expect(:[stack]).toCountResources"
65+
rewrite="Template.fromStack(:[stack]).resourceCountIs"
66+
67+
[200_assert_toCountResources2]
68+
match=":[[expect]](:[stack]).to(countResources(:[args]))"
69+
rewrite="Template.fromStack(:[stack]).resourceCountIs(:[args])"
70+
rule='''where match :[expect] {
71+
| "expect" -> true
72+
| "cdkExpect" -> true
73+
| ":[_]" -> false
74+
}'''
75+
76+
[200_jest_toMatchTemplate]
77+
match="expect(:[stack]).toMatchTemplate"
78+
rewrite="Template.fromStack(:[stack]).templateMatches"
79+
80+
[200_assert_toMatchTemplate]
81+
match=":[[expect]](:[stack]).toMatchTemplate"
82+
rewrite="Template.fromStack(:[stack]).templateMatches"
83+
rule='''where match :[expect] {
84+
| "expect" -> true
85+
| "cdkExpect" -> true
86+
| ":[_]" -> false
87+
}'''
88+
89+
[300_notToHaveResourceLike]
90+
match="expect(:[stack]).not.toHaveResourceLike(:[args])"
91+
rewrite="Template.fromStack(:[stack]).resourceCountIs(:[args], 0)"
92+
93+
[300_notToHaveResource]
94+
match="expect(:[stack]).not.toHaveResource(:[args])"
95+
rewrite="Template.fromStack(:[stack]).resourceCountIs(:[args], 0)"
96+
97+
[arrayWith]
98+
match="arrayWith(:[args])"
99+
rewrite="Match.arrayWith([:[args]])"
100+
101+
[objectLike]
102+
match="objectLike"
103+
rewrite="Match.objectLike"
104+
105+
[absent]
106+
match="ABSENT"
107+
rewrite="Match.absent()"
108+
109+
[400_synthutils_template]
110+
match="SynthUtils.synthesize(:[stack]).template"
111+
rewrite="Template.fromStack(:[stack]).toJSON()"
112+
113+
[401_synthutils_assembly]
114+
match="SynthUtils.synthesize(:[stack])"
115+
rewrite="App.of(:[stack]).synth()"

0 commit comments

Comments
 (0)