Package: pitfall
Pulumi Integration Test Frameworkpitfallis a Python integration testing framework forPulumiInfrastructure as Code. It enables and encourages end to end testing to avoid errors, assumptions, and other pitfalls.Installationpitfallcan be installed via pip:$ pip install pitfallCompatibilitypitfallhas been tested against versions 1.2.0 - 1.4.0 of Pulumi and will strive to work with the latest Pulumi release.Warning: this is alpha software. There are no guarantees of backwards compatibility.Usagepitfallis intended to be used in integration tests to verify the desired state of infrastructure provisioned by Pulumi.It will do the following:create a temp directory to store Pulumi code and statecopy the contents of the current directory (and all subdirectories) to the temp directorymove into the temp directorycreate a new Pulumi project file:Pulumi.yamlcreate a new Pulumi stack file:Pulumi.<stack name>.yamlinitialize a new Pulumi state file in.pulumi/install Pulumi pluginsexecutepulumi previewexecutepulumi upexecutepulumi destroydelete the temp directorypitfallsupports acontext managerto automatically do the above.pitfalldoes not use the Pulumi Service backend.ExamplesBasic S3 Example- provision a AWS S3 bucket and verify that required tags have been set on itAdvanced S3 Example- provision a AWS S3 bucket to host a static website and verify that it's functionalAWS VPC ComponentResource Example- provision a AWS VPC using a ComponentResourceFeaturesContext Managerpitfallincludes a context manager to automatically setup a test and execute the Pulumi workflow:frompitfallimportPulumiConfigurationKey,PulumiIntegrationTestdirectory='/path/to/pulumi/code'opts=PulumiIntegrationTestOptions(cleanup=True,preview=True,up=True,destroy=True)withPulumiIntegrationTest(directory=directory,opts=opts)ast:passThe context manager will create a temporary directory for the test, copy the entire contents ofdirectoryto the temporary directory, generate the Pulumi Project and Stack files, initialize a new Pulumi local state file, install Pulumi plugins, and executepulumi preview,pulumi up, andpulumi destroy. Upon exit, the context manager will delete the temporary directory.To control automatic execution of Pulumi commands, temporary directory deletion, and verbosity, set desired options withPulumiIntegrationTestOptions.Configuration and Secretspitfallsupports PulumiConfiguration and Secrets:frompitfallimportPulumiConfigurationKey,PulumiIntegrationTestimportosdbpassword=os.urandom(32)config=[PulumiConfigurationKey(name='aws:region',value="us-east-1"),PulumiConfigurationKey(name='dbpassword',value=dbpassword,encrypted=True)]t=PulumiIntegrationTest(config=config)t.setup()Whent.setup()is called, the Pulumi stack file (Pulumi.<stack name>.yaml) will automatically be created with the supplied configuration. Configuration keys are automatically namespaced with the name of the Pulumi Project and Secrets are encryped using the password set by the environment variablePULUMI_CONFIG_PASSPHRASE:$ cat Pulumi.pitf-stack-91c13928d11648be.yaml

config:
  aws:region: us-east-1
  pitf-project-99c24db7cc324cf9:dbpassword:
    secure: v1:6UEXewJReYiPCgrg:fOFTB4ODFyZB0bvHA2lhoZJ3khCOQCkX8n5OhLXjgSECbu+WrcIQ+wl0HaZhZ/4v
encryptionsalt: v1:GEHe83S30O0=:v1:s8vb7cVFSz64pUmv:Ff5AbbcbTSim8cBwDCQCwraGHEQQ/A==Pulumi Statepitfallexposes the Pulumi state as a Python objectPulumiState. Both the current and previous state are accessible as Class properties. The resources in the current state file can be viewed and searched:t=PulumiIntegrationTest()resources=t.state.resourcesforiinresources:print(i.urn,i.id,i.type)resources.providers# {"pulumi:providers:aws": 1}resources.types# {"aws:s3/bucket:Bucket": 1, "pulumi:pulumi:Stack": 1}results=resources.lookup(key="type",value="aws:s3/bucket:Bucket")s3_bucket=results[0]print(s3_bucket.id)# pitfall-basic-example-649ce5fprint(s3_bucket.outputs["arn"])# arn:aws:s3:::pitfall-basic-example-649ce5fStack Outputspitfallcollects PulumiStack outputs, so that they can be accessed in tests:withPulumiIntegrationTest(directory=directory,opts=opts)ast:outputs=t.get_stack_outputs()s3_bucket_arn=outputs["s3_bucket"]["arn"]Resources Graphpitfallcan export the resources in the Pulumi state file as a DOT file:withPulumiIntegrationTest(directory=directory,opts=opts)ast:resources=t.state.resourcesresources.export_dotfile(filename='~/graph.dot')View the DOT file:$ cat ~/graph.dot

digraph tree {
    "pulumi:pulumi:Stack";
    "aws:s3/bucket:Bucket (pitfall-basic-example-649ce5f)";
    "pulumi:pulumi:Stack" -> "aws:s3/bucket:Bucket (pitfall-basic-example-649ce5f)";
}This DOT file can then be viewed using thedotcommand or online atwebgraphviz.com.Test Helperspitfallincludes useful helper classes and functions that can be used in integration tests. These can be found underpitfall/helpers.Environment VariablesThe following environment variables are supported:Environment VariableDefault ValueDescriptionPULUMI_HOME~/.pulumithe location of Pulumi's home directoryPULUMI_CONFIG_PASSPHRASEpulumithe password for encrypting secretsIf they are set, they will be inherited bypitfall.DocumentationTODOTestingnose2is used for unit and integration testing.pulumimust be installed for tests to pass.Unit TestsUnit tests are located in/tests.To run the unit tests:$ make testEnd to End TestsEnd to end tests are located ine2e/.testing usinglocalstacke2e tests that use localstack are located ine2e/localstack. These tests require localstack running locally in a container.To run localstack:$ make run-localstackRun the e2e tests:$ make e2e-test-localstacktesting usingAWSe2e tests that use AWS are located ine2e/aws. These tests require an AWS account and valid AWS API keys.Run the e2e tests:$ make e2e-test-awsContributingWe encourage the following contributions at this time: user feedback, documentation, bug reports, and feature requests.Acknowledgementpitfallwas built upon the Python libraries listed in itsPipfile.LicenseCopyright 2019 Ali (@bincyber)Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.