Welcome to AWS CDK test Synth’s documentation!

This package contains the classes for managing the testing of your AWS CDK code.

Getting started

AWS CDK test Synth package is implemented for helping you to test your AWS CDK code.

The goal is to cover the missing of an official testing infrastructure for Python as exists for TypeScript using Jest.

It is part of the educational repositories to learn how to write stardard code and common uses of the TDD.

Prerequisites

This package is useful for testing your AWS CDK code, so you probably have everything you need installed already.

Installation

If you want to use this package into your code, you can install by python3-pip:

pip3 install aws_cdk_test_synth
python3
>>> import aws_cdk_test_synth.test_synth as TestSynth
>>> help(TestSynth)

Read the documentation on readthedocs for

Usage
Development

Change Log

See CHANGELOG.md for details.

License

This package is released under the MIT license. See LICENSE for details.

Usage

The class reads the yaml template saved, synthesizes the new template and compares between them.

You have to import the class TestSynth instead of unittest.TestCase package and your TestYourClass class has to extend it.

from tests.test_synth import TestSynth
from sample.yourclass import YourClass
class TestYourClass(TestSynth):

The method named __init__ has to call the class named TestSynth with the relative path of yaml template saved.

def __init__(self, *args, **kwargs):
    TestSynth.__init__(self, 'tests/yourclass.yaml', *args, **kwargs)

There is the method named synth with the initialization of YourClass

def synth(self, app):
    YourClass(app, id="name-of-your-stack")

If you have to manage more YourClass, you can use the method synthesizes

def your_synth(self, app):
    YourClass(app, id="name-of-your-stack")

def test_your_synth(self):
    self.synthesizes('your_synth')

It you have to manage more templates, you can use the method load_template

def your_synth(self, app):
    YourClass(app, id=self.id)

def test_your_synth(self):
    self.id = "name-of-your-synth"
    self.load_template('tests/yoursynth.yaml')
    self.synthesizes('your_synth')

Example

When you create your stack.py file, you can create your test_stack.py like the example in the tests folder of this repository. In that example, you can find

s3_stack.py, the example of your stack implementation
test_s3_stack.py, the example of your unittest class
s3.yaml, the template saved

When you run the unittest (see the Development Section),

before, you have to create a file empty named s3.yaml
the first time, you have to fill it with the first version
the times after, if the templates saved and new are different, so the unittest fails, you can evaluate if you have to save a new version or fix your change

You can find other examples in the repositories below:

Development

This package is used only for testing your AWS CDK code, so it is useful for helping you to implement your TDD.

If you want to use this package with your AWS CDK code, you can find an example in the tests folder of this repository.

Run tests

cd aws-cdk-test-synth/
pip3 install --upgrade -r requirements.txt
python3 -m unittest discover -v

Template saved

If the unittest fails, the class prints the yaml files. So, if you will have implemented more unittests classes, it will be simple to run one unittest at a time:

cd aws-cdk-test-synth/
python3 -m unittest discover -v -p test_s3_stack.py

And if you will want to compare what it is different with the template saved, you can save the new template:

cd aws-cdk-test-synth/
python3 -m unittest discover -v -p test_s3_stack.py > tests/s3.yaml.2

This approach is comfortable for running your program for comparison, like Meld, diff or fc:

cd aws-cdk-test-synth/
diff tests/s3.yaml tests/s3.yaml.2