A new platform for documentation and tutorials is launching soon.

We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.

Join Now
Type '/' to Search

»Unit Tests

Testing your application can give you faster feedback cycles and guard you against unwanted changes. Testing is currently supported in Typescript with jest and compatible with any testing framework that supports assertions for all other languages.

We generate all files necessary to start testing when you run cdktf init so that you can start writing tests right away.

»Add Testing to Your Application

If you would like to add testing to an existing project, refer the following resources according to your chosen language:

  • TypeScript: Follow TypeScript's Getting Started guide for testing with Jest. Then, add these lines in a setup file:

    const cdktf = require("cdktf");
cdktf.Testing.setupJest();

    const cdktf = require("cdktf");
cdktf.Testing.setupJest();

  • Python: Follow the Get Started guide for pytest. The assertions for CDKTF are available in the cdktf package under Testing.

  • Java: Follow the Using JUnit documentation. The assertions for CDKTF specific are available in the cdktf package under Testing.

  • C#: Follow the Getting Started with xUnit.net guide. The assertions for CDKTF are available in the cdktf package under Testing.

  • Go: Follow the Add a Test guide in the Go documentation. The assertions for CDKTF specific are available in the cdktf package under Testing.

»Write Assertions

The following Typescript example uses Testing.synthScope to test a part of the application. This creates a scope to test a subset of the application and returns a JSON string representing the synthesized HCL-JSON. Then it uses custom matchers to verify the code acts as intended.

The other examples use Testing.synth to test a part of the application. Given the desired scope to test, a JSON string representing the synthesized HCL-JSON is returned. Then the custom assertions under Testing in the cdktf package can be used to verify the code acts as intended.

Examples in

import { Testing } from "cdktf";
import { Image, Container } from "../.gen/providers/docker";
import MyApplicationsAbstraction from "../app"; // Could be a class extending from Construct

describe("Unit testing using assertions", () => {
  it("should contain a container", () => {
    expect(
      Testing.synthScope((scope) => {
        new MyApplicationsAbstraction(scope, "my-app", {});
      })
    ).toHaveResource(Container);
  });

  it("should use an ubuntu image", () => {
    expect(
      Testing.synthScope((scope) => {
        new MyApplicationsAbstraction(scope, "my-app", {});
      })
    ).toHaveResourceWithProperties(Image, { name: "ubuntu:latest" });
  });
});

import { Testing } from "cdktf";
import { Image, Container } from "../.gen/providers/docker";
import MyApplicationsAbstraction from "../app"; // Could be a class extending from Construct

describe("Unit testing using assertions", () => {
  it("should contain a container", () => {
    expect(
      Testing.synthScope((scope) => {
        new MyApplicationsAbstraction(scope, "my-app", {});
      })
    ).toHaveResource(Container);
  });

  it("should use an ubuntu image", () => {
    expect(
      Testing.synthScope((scope) => {
        new MyApplicationsAbstraction(scope, "my-app", {});
      })
    ).toHaveResourceWithProperties(Image, { name: "ubuntu:latest" });
  });
});

import pytest
from cdktf import Testing
from imports.docker import Image, Container
from app import MyApplicationsAbstraction # Could be a class extending from Construct

class TestApplication:

  stack = TerraformStack(Testing.app(), "stack")
  app_abstraction = MyApplicationsAbstraction(stack, "app-abstraction")
  synthesized = Testing.synth(stack)

  def test_should_contain_container(self):
    assert Testing.to_have_resource(self.synthesized, Container.TF_RESOURCE_TYPE)

  def test_should_use_an_ubuntu_image(self):
    assert Testing.to_have_resource_with_properties(self.synthesized, Image.TF_RESOURCE_TYPE, {
            "name": "ubuntu:latest",
    })

import pytest
from cdktf import Testing
from imports.docker import Image, Container
from app import MyApplicationsAbstraction # Could be a class extending from Construct

class TestApplication:

  stack = TerraformStack(Testing.app(), "stack")
  app_abstraction = MyApplicationsAbstraction(stack, "app-abstraction")
  synthesized = Testing.synth(stack)

  def test_should_contain_container(self):
    assert Testing.to_have_resource(self.synthesized, Container.TF_RESOURCE_TYPE)

  def test_should_use_an_ubuntu_image(self):
    assert Testing.to_have_resource_with_properties(self.synthesized, Image.TF_RESOURCE_TYPE, {
            "name": "ubuntu:latest",
    })

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
import com.hashicorp.cdktf.Testing;
import imports.docker.Container;
import imports.docker.Image;
import com.hashicorp.cdktf.MyApplicationsAbstraction; // Could be a class extending from Construct

public class TestApplication {

  private final TerraformStack stack = new TerraformStack(Testing.app(), "stack");
  private final MyApplicationsAbstraction appAbstraction = new MyApplicationsAbstraction(stack, "resource");
  private final String synthesized = Testing.synth(stack);

  @Test
  void shouldContainContainer() {
    assertTrue(Testing.toHaveResource(synthesized, Container.TF_RESOURCE_TYPE) );
  }

  @Test
  void shouldUseUbuntuImage() {
    assertTrue(Testing.toHaveResourceWithProperties(synthesized, Image.TF_RESOURCE_TYPE, new HashMap<String, Object>() {
                {
                    put("name", "ubuntu:latest");
                }
    }) );
  }
}

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
import com.hashicorp.cdktf.Testing;
import imports.docker.Container;
import imports.docker.Image;
import com.hashicorp.cdktf.MyApplicationsAbstraction; // Could be a class extending from Construct

public class TestApplication {

  private final TerraformStack stack = new TerraformStack(Testing.app(), "stack");
  private final MyApplicationsAbstraction appAbstraction = new MyApplicationsAbstraction(stack, "resource");
  private final String synthesized = Testing.synth(stack);

  @Test
  void shouldContainContainer() {
    assertTrue(Testing.toHaveResource(synthesized, Container.TF_RESOURCE_TYPE) );
  }

  @Test
  void shouldUseUbuntuImage() {
    assertTrue(Testing.toHaveResourceWithProperties(synthesized, Image.TF_RESOURCE_TYPE, new HashMap<String, Object>() {
                {
                    put("name", "ubuntu:latest");
                }
    }) );
  }
}

using Xunit;
using HashiCorp.Cdktf; // MyApplicationsAbstraction - Could be a class extending from Construct
using MyCompany.MyApp;
using System;
using System.Collections.Generic;
using docker;

namespace MyCompany.MyApp{
  public class TestApplication{

    private static TerraformStack stack = new TerraformStack(Testing.app(), "stack");
    private static MyApplicationsAbstraction appAbstraction = new MyApplicationsAbstraction(stack, "resource");
    private static string synthesized = Testing.synth(stack);

    [Fact]
    public void ShouldContainContainer(){
      Assert.True(Testing.ToHaveResource(synthesized, Container.TfResourceType) );
    }

    [Fact]
    public void shouldUseUbuntuImage(){
      Assert.True(Testing.ToHaveResourceWithProperties(synthesized, Image.TfResourceType, new Dictionary<String, Object>() {
              {"name", "ubuntu:latest"}
      }) );
    }
  }
}

using Xunit;
using HashiCorp.Cdktf; // MyApplicationsAbstraction - Could be a class extending from Construct
using MyCompany.MyApp;
using System;
using System.Collections.Generic;
using docker;

namespace MyCompany.MyApp{
  public class TestApplication{

    private static TerraformStack stack = new TerraformStack(Testing.app(), "stack");
    private static MyApplicationsAbstraction appAbstraction = new MyApplicationsAbstraction(stack, "resource");
    private static string synthesized = Testing.synth(stack);

    [Fact]
    public void ShouldContainContainer(){
      Assert.True(Testing.ToHaveResource(synthesized, Container.TfResourceType) );
    }

    [Fact]
    public void shouldUseUbuntuImage(){
      Assert.True(Testing.ToHaveResourceWithProperties(synthesized, Image.TfResourceType, new Dictionary<String, Object>() {
              {"name", "ubuntu:latest"}
      }) );
    }
  }
}

package main

import (
    "testing"
    "cdk.tf/go/stack/generated/kreuzwerker/docker"
    "github.com/hashicorp/terraform-cdk-go/cdktf"
    "github.com/aws/jsii-runtime-go"
)

var stack = NewMyApplicationsAbstraction(cdktf.Assertions_App(nil), "stack")
var synth = cdktf.Assertions_Synth(stack)

func TestShouldContainContainer(t *testing.T){
    assertion := cdktf.Assertions_ToHaveResource(synth, docker.Container_TfResourceType())

    if !*assertion  {
        t.Error(assertion.Message())
    }
}

func TestShouldUseUbuntuImage(t *testing.T){
    properties := map[string]interface{}{
        "name": "ubuntu:latest",
    }
    assertion := cdktf.Assertions_ToHaveResourceWithProperties(synth, docker.Image_TfResourceType(), &properties)

    if !*assertion  {
        t.Error(assertion.Message())
    }
}

package main

import (
    "testing"
    "cdk.tf/go/stack/generated/kreuzwerker/docker"
    "github.com/hashicorp/terraform-cdk-go/cdktf"
    "github.com/aws/jsii-runtime-go"
)

var stack = NewMyApplicationsAbstraction(cdktf.Assertions_App(nil), "stack")
var synth = cdktf.Assertions_Synth(stack)

func TestShouldContainContainer(t *testing.T){
    assertion := cdktf.Assertions_ToHaveResource(synth, docker.Container_TfResourceType())

    if !*assertion  {
        t.Error(assertion.Message())
    }
}

func TestShouldUseUbuntuImage(t *testing.T){
    properties := map[string]interface{}{
        "name": "ubuntu:latest",
    }
    assertion := cdktf.Assertions_ToHaveResourceWithProperties(synth, docker.Image_TfResourceType(), &properties)

    if !*assertion  {
        t.Error(assertion.Message())
    }
}

»Snapshot Testing

Snapshot tests are useful when you want to make sure your infrastructure does not change unexpectedly. Snapshot Testing is only supported in Typescript with Jest. Refer to the Jest docs for details.

import { Testing } from "cdktf";
import { Image, Container } from "../.gen/providers/docker";
import MyApplicationsAbstraction from "../app"; // Could be a class extending from Construct

describe("Unit testing using snapshots", () => {
  it("Tests a custom abstraction", () => {
    expect(
      Testing.synthScope((stack) => {
        const app = new MyApplicationsAbstraction(scope, "my-app", {});
        app.addEndpoint("127.0.0.1"); // This could be a method your class exposes
      })
    ).toMatchInlineSnapshot(); // There is also .toMatchSnapshot() to write the snapshot to a file
  });
});

import { Testing } from "cdktf";
import { Image, Container } from "../.gen/providers/docker";
import MyApplicationsAbstraction from "../app"; // Could be a class extending from Construct

describe("Unit testing using snapshots", () => {
  it("Tests a custom abstraction", () => {
    expect(
      Testing.synthScope((stack) => {
        const app = new MyApplicationsAbstraction(scope, "my-app", {});
        app.addEndpoint("127.0.0.1"); // This could be a method your class exposes
      })
    ).toMatchInlineSnapshot(); // There is also .toMatchSnapshot() to write the snapshot to a file
  });
});

»Integration with Terraform

You can produce invalid Terraform configuration if you are using escape hatches in your CDK for Terraform application. You may use an escape hatch when setting up a remote backend or when overriding resource attributes

To test this, you can assert that terraform validate or terraform plan run successfully on all or part of your application before running cdktf plan or cdktf deploy.

Currently only Typescript is capable of testing for successful plans, while all languages are capable of testing for validity of the Terraform produced.

import { Testing } from "cdktf";

describe("Checking validity", () => {
  it("check if the produced terraform configuration is valid", () => {
    const app = Testing.app();
    const stack = new TerraformStack(app, "test");

    const myAbstraction = new MyApplicationsAbstraction(stack, "my-app", {});
    myAbstraction.addEndpoint("127.0.0.1"); // This could be a method your class exposes

    // We need to do a full synth to validate the terraform configuration
    expect(Testing.fullSynth(stack)).toBeValidTerraform();
  });

  it("check if this can be planned", () => {
    const app = Testing.app();
    const stack = new TerraformStack(app, "test");

    const myAbstraction = new MyApplicationsAbstraction(stack, "my-app", {});
    myAbstraction.addEndpoint("127.0.0.1"); // This could be a method your class exposes

    // We need to do a full synth to plan the terraform configuration
    expect(Testing.fullSynth(stack)).toPlanSuccessfully();
  });
});

import { Testing } from "cdktf";

describe("Checking validity", () => {
  it("check if the produced terraform configuration is valid", () => {
    const app = Testing.app();
    const stack = new TerraformStack(app, "test");

    const myAbstraction = new MyApplicationsAbstraction(stack, "my-app", {});
    myAbstraction.addEndpoint("127.0.0.1"); // This could be a method your class exposes

    // We need to do a full synth to validate the terraform configuration
    expect(Testing.fullSynth(stack)).toBeValidTerraform();
  });

  it("check if this can be planned", () => {
    const app = Testing.app();
    const stack = new TerraformStack(app, "test");

    const myAbstraction = new MyApplicationsAbstraction(stack, "my-app", {});
    myAbstraction.addEndpoint("127.0.0.1"); // This could be a method your class exposes

    // We need to do a full synth to plan the terraform configuration
    expect(Testing.fullSynth(stack)).toPlanSuccessfully();
  });
});

import pytest
from cdktf import Testing
from app import MyApplicationsAbstraction # Could be a class extending from Construct

class TestApplication:

  stack = TerraformStack(Testing.app(), "stack")
  app_abstraction = MyApplicationsAbstraction(stack, "app-abstraction")

  def test_check_validity(self):
    # We need to do a full synth to validate the terraform configuration
    assert Testing.to_be_valid_terraform(Testing.full_synth(stack))

import pytest
from cdktf import Testing
from app import MyApplicationsAbstraction # Could be a class extending from Construct

class TestApplication:

  stack = TerraformStack(Testing.app(), "stack")
  app_abstraction = MyApplicationsAbstraction(stack, "app-abstraction")

  def test_check_validity(self):
    # We need to do a full synth to validate the terraform configuration
    assert Testing.to_be_valid_terraform(Testing.full_synth(stack))

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
import com.hashicorp.cdktf.MyApplicationsAbstraction; // Could be a class extending from Construct

public class TestApplication {

  private final TerraformStack stack = new TerraformStack(Testing.app(), "stack");
  private final MyApplicationsAbstraction appAbstraction = new MyApplicationsAbstraction(stack, "resource");

  @Test
  void checkValidity() {
    // We need to do a full synth to validate the terraform configuration
    assertTrue(Testing.toBeValidTerraform(Testing.fullSynth(stack)) );
  }
}

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
import com.hashicorp.cdktf.MyApplicationsAbstraction; // Could be a class extending from Construct

public class TestApplication {

  private final TerraformStack stack = new TerraformStack(Testing.app(), "stack");
  private final MyApplicationsAbstraction appAbstraction = new MyApplicationsAbstraction(stack, "resource");

  @Test
  void checkValidity() {
    // We need to do a full synth to validate the terraform configuration
    assertTrue(Testing.toBeValidTerraform(Testing.fullSynth(stack)) );
  }
}

using Xunit;
using HashiCorp.Cdktf; // MyApplicationsAbstraction - Could be a class extending from Construct
using MyCompany.MyApp;
using HashiCorp.Cdktf;
using System;

namespace MyCompany.MyApp{
  public class TestApplication{

    private static TerraformStack stack = new TerraformStack(Testing.app(), "stack");
    private static MyApplicationsAbstraction appAbstraction = new MyApplicationsAbstraction(stack, "construct");

    [Fact]
    public void CheckValidity(){
      // We need to do a full synth to validate the terraform configuration
      Assert.True(Testing.ToBeValidTerraform(Testing.FullSynth(stack)) );
    }
  }
}

using Xunit;
using HashiCorp.Cdktf; // MyApplicationsAbstraction - Could be a class extending from Construct
using MyCompany.MyApp;
using HashiCorp.Cdktf;
using System;

namespace MyCompany.MyApp{
  public class TestApplication{

    private static TerraformStack stack = new TerraformStack(Testing.app(), "stack");
    private static MyApplicationsAbstraction appAbstraction = new MyApplicationsAbstraction(stack, "construct");

    [Fact]
    public void CheckValidity(){
      // We need to do a full synth to validate the terraform configuration
      Assert.True(Testing.ToBeValidTerraform(Testing.FullSynth(stack)) );
    }
  }
}

package main

import (
    "testing"
    "github.com/hashicorp/terraform-cdk-go/cdktf"
    "github.com/aws/jsii-runtime-go"
)

var stack = cdktf.NewTerraformStack(cdktf.Testing_App(nil), "stack")

func TestCheckValidity(t *testing.T){
  // We need to do a full synth to validate the terraform configuration
    assertion := cdktf.Testing_ToBeValidTerraform(cdktf.Testing_FullSynth(stack))

    if !*assertion  {
        t.Error(assertion.Message())
    }
}

package main

import (
    "testing"
    "github.com/hashicorp/terraform-cdk-go/cdktf"
    "github.com/aws/jsii-runtime-go"
)

var stack = cdktf.NewTerraformStack(cdktf.Testing_App(nil), "stack")

func TestCheckValidity(t *testing.T){
  // We need to do a full synth to validate the terraform configuration
    assertion := cdktf.Testing_ToBeValidTerraform(cdktf.Testing_FullSynth(stack))

    if !*assertion  {
        t.Error(assertion.Message())
    }
}

»Integration Testing

CDK for Terraform does not currently offer many helpers for integration testing, but you can create them for your use cases. Here is a recent example: CDK Day 2021.