Integration & Automation

Introducing TaskCat v0.9


TaskCat is an open-source tool that is used for testing Amazon Web Services (AWS) CloudFormation templates. It was originally developed by the AWS Quick Start team, which works with AWS Partner Network (APN) Partners to publish AWS CloudFormation reference architectures. The team built TaskCat to provide the means to test Quick Starts during development. It also plays a role in the Quick Start team’s continuous delivery pipeline.

After TaskCat was initially released through GitHub, customers who wanted to improve the reliability of their production templates started to use this tool. The 0.9 release brings some significant changes that aim to make TaskCat a general-purpose AWS CloudFormation testing tool.

In this post, we discuss the changes and new features in TaskCat that are pertinent to both new and existing TaskCat users. TaskCat requires Python 3.6 or higher and runs on macOS and Linux operating systems. For installation instructions, see the TaskCat installation documentation.


If you are a first-time user of TaskCat, we recommend that you begin by reading the TaskCat

To upgrade from a previous version, run the following:

pip3 install taskcat --upgrade

New command line interface

The new command line interface (CLI) has been redesigned to make it easier to add new commands and reduce the complexity of common operations. Compare this command for executing a test in TaskCat:

taskcat -c ./ci/taskcat.yml

In version 0.9, this command simplifies to the following:

taskcat test run

This illustrates the new CLI structure of <command> <subcommand>. To discover available commands and switches, use --help at any level. For example, look at the available subcommands for test:

taskcat test –-help

usage: taskcat [args] test [args] [subcommand] [args]

Performs functional tests on CloudFormation templates.

optional arguments:
  -h, --help — show this help message and exit

  clean — removes stacks created by previous tests (use ALL to remove all stacks found)
  list — all commercial regions
  resume — resumes monitoring a previously started test run
  run — tests if CloudFormation templates can launch successfully

This displays some interesting new subcommands that we discuss next.

Asynchronous operations

Upon examining the help output, notice that test has new subcommands: clean, list, resume, and run. These subcommands enable asynchronous use of TaskCat. For example, you can quit TaskCat after a test is launched, and, when you’re ready to resume monitoring the test’s progress, you can use resume.

The list subcommand displays inactive tests (that is, tests that have not yet been deleted) in all Regions. The clean subcommand deletes stacks that are associated with an individual test (or all tests by adding ALL). Because TaskCat is stateless, these operations do not necessarily need to run from the same computer or terminal session. For example, a test started on a developer’s laptop can be continued from a different workstation.

Configuration file format

The configuration file format has also been overhauled to be more concise and flexible. Its schema is now based in JavaScript Object Notation (JSON), so integrated development environments that support schema validation can be validated in real time.

The default location for a project configuration file is ./.taskcat.yml, which is relative to the root of the CloudFormation project. A global configuration file can be provided to override account-specific parameters or to set general properties, such as specifying an Amazon Simple Storage Service (Amazon S3) bucket to use when staging tests. For a detailed example that outlines all the configuration properties, see the TaskCat GitHub repository.

Multi-account testing

This feature was born out of the need to test a Quick Start in different partitions, such as AWS GovCloud (US) and AWS China, with a single TaskCat test. This also allows customers to use different accounts for different Regions within the same partition.

To set up different accounts, first set up AWS Command Line Interface (AWS CLI)–named profiles for the accounts by following the AWS CLI documentation. In this example, I use a profile called mes1 that was created for the Middle East (Bahrain) Region. All other Regions use the default credentials that are set up in the AWS CLI. Because profiles are user specific, we recommend that you set your account configuration in the global configuration file (~/.taskcat.yml). This ensures that your project remains portable for others to test, without the need to provide profiles with the same name.

    default: default
    me-south-1: mes1

With this configuration, any test that includes the Middle East (Bahrain) Region will launch using the mes1 account. All other Regions will use the default profile.


With this new version of TaskCat, there are also some prerelease features available (use taskcat --help). We’ll dive into those in future posts.

In the meantime, you can go through the self-paced TaskCat Workshop or send us your impressions by commenting either here or through GitHub.