testschematic

package
v1.45.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2025 License: Apache-2.0, Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package testschematic contains functions that can be used to assist and standardize the execution of unit tests for IBM Cloud Terraform projects by using the IBM Cloud Schematics service

Example (Default) 
package main

import (
	"testing"

	"github.com/terraform-ibm-modules/ibmcloud-terratest-wrapper/testschematic"
)

func main() {
	// (here for compile only)
	// this is the test object supplied in a unit test call
	t := &testing.T{}

	t.Run("schematic unit test", func(t *testing.T) {
		// create TestOptions using Default contructor. This will do several things for you:
		// * Prefix will have random string added to end
		// * Validate required OS Environment variables are set
		// * Dynamically choose best region for test, if region not supplied
		// * Set other option fields to their sensible defaults
		//
		// You call this constructor by passing it an existing TestOptions with minimal data and it will return
		// a new altered object.
		options := testschematic.TestSchematicOptionsDefault(&testschematic.TestSchematicOptions{
			Testing:            t,                      // the test object for unit test
			Prefix:             "my-test",              // will have 6 char random string appended, can be used as variable to prefix test resources
			BestRegionYAMLPath: "location/of/yaml.yml", // YAML file to configure dynamic region selection (see cloudinfo/RegionData type)
			// Region: "us-south", // if you set Region, dynamic selection will be skipped
			// Supply filters in order to build TAR file to upload to schematics, if not supplied will default to "*.tf" in project root
			TarIncludePatterns: []string{"*.tf", "scripts/*.sh", "examples/basic/*.tf"},
			// If test fails, determine if schematic workspace is also deleted
			DeleteWorkspaceOnFail: false,
			TemplateFolder:        "examples/basic",
		})

		// Set up the schematic workspace Variablestore, including values to use
		options.TerraformVars = []testschematic.TestSchematicTerraformVar{
			{Name: "ibmcloud_api_key", Value: options.RequiredEnvironmentVars["TF_VAR_ibmcloud_api_key"], DataType: "string", Secure: true},
			{Name: "ibm_region", Value: options.Region, DataType: "string"},
			{Name: "do_something", Value: true, DataType: "bool"},
			{Name: "tags", Value: []string{"test", "schematic"}, DataType: "list(string)"},
		}

		// If needed, Git credentials can be supplied to create netrc entries in schematics to pull terraform modules from private repos
		// NOTE: token should be retrieved from trusted source and not statically coded here
		options.AddNetrcCredential("github.com", "some-user", "some-token")
		options.AddNetrcCredential("bitbucket.com", "bit-user", "bit-token")

		// run the test
		err := options.RunSchematicTest()
		if err != nil {
			t.Fail()
		}
	})
}

Output:

Index

Examples

Constants

View Source 
const DefaultWaitJobCompleteMinutes = int16(120) // default 2 hrs wait time
View Source 
const SchematicsJobStatusCompleted = "COMPLETED"

IBM schematics job status

View Source 
const SchematicsJobStatusCreated = "CREATED"
View Source 
const SchematicsJobStatusFailed = "FAILED"
View Source 
const SchematicsJobStatusInProgress = "INPROGRESS"
View Source 
const SchematicsJobTypeApply = "APPLY"
View Source 
const SchematicsJobTypeDestroy = "DESTROY"
View Source 
const SchematicsJobTypePlan = "PLAN"
View Source 
const SchematicsJobTypeUpdate = "WORKSPACE_UPDATE"
View Source 
const SchematicsJobTypeUpload = "TAR_WORKSPACE_UPLOAD"

IBM schematics job types

Variables

This section is empty.

Functions

func CreateSchematicTar 

func CreateSchematicTar(projectPath string, includePatterns *[]string) (string, error)

CreateSchematicTar will accept a path to a Terraform project and an array of file patterns to include, and will create a TAR file in a temporary location that contains all of the project's files that match the supplied file patterns. This TAR file can then be uploaded to a Schematics Workspace template. Returns a string of the complete TAR file path and file name. Error is returned if any issues happen while creating TAR file.

Types

type IamAuthenticatorSvcI 

type IamAuthenticatorSvcI interface {
	Authenticate(*http.Request) error
	AuthenticationType() string
	RequestToken() (*core.IamTokenServerResponse, error)
	Validate() error
}

interface for external IBMCloud IAM Authenticator api. Can be mocked for tests

type NetrcCredential 

type NetrcCredential struct {
	Host     string // hostname or machine name of the entry
	Username string // user name
	Password string // password or token
}

type SchematicsApiSvcI 

type SchematicsApiSvcI interface {
	CreateWorkspace(*schematics.CreateWorkspaceOptions) (*schematics.WorkspaceResponse, *core.DetailedResponse, error)
	UpdateWorkspace(*schematics.UpdateWorkspaceOptions) (*schematics.WorkspaceResponse, *core.DetailedResponse, error)
	DeleteWorkspace(*schematics.DeleteWorkspaceOptions) (*string, *core.DetailedResponse, error)
	TemplateRepoUpload(*schematics.TemplateRepoUploadOptions) (*schematics.TemplateRepoTarUploadResponse, *core.DetailedResponse, error)
	ReplaceWorkspaceInputs(*schematics.ReplaceWorkspaceInputsOptions) (*schematics.UserValues, *core.DetailedResponse, error)
	ListWorkspaceActivities(*schematics.ListWorkspaceActivitiesOptions) (*schematics.WorkspaceActivities, *core.DetailedResponse, error)
	GetWorkspaceActivity(*schematics.GetWorkspaceActivityOptions) (*schematics.WorkspaceActivity, *core.DetailedResponse, error)
	PlanWorkspaceCommand(*schematics.PlanWorkspaceCommandOptions) (*schematics.WorkspaceActivityPlanResult, *core.DetailedResponse, error)
	ApplyWorkspaceCommand(*schematics.ApplyWorkspaceCommandOptions) (*schematics.WorkspaceActivityApplyResult, *core.DetailedResponse, error)
	DestroyWorkspaceCommand(*schematics.DestroyWorkspaceCommandOptions) (*schematics.WorkspaceActivityDestroyResult, *core.DetailedResponse, error)
	ReplaceWorkspace(*schematics.ReplaceWorkspaceOptions) (*schematics.WorkspaceResponse, *core.DetailedResponse, error)
}

interface for the external schematics service api. Can be mocked for tests

type SchematicsTestService 

type SchematicsTestService struct {
	SchematicsApiSvc          SchematicsApiSvcI           // the main schematics service interface
	ApiAuthenticator          IamAuthenticatorSvcI        // the authenticator used for schematics api calls
	WorkspaceID               string                      // workspace ID used for tests
	WorkspaceName             string                      // name of workspace that was created for test
	WorkspaceNameForLog       string                      // combination of Name and ID useful for log consistency
	WorkspaceLocation         string                      // region the workspace was created in
	TemplateID                string                      // workspace template ID used for tests
	TestOptions               *TestSchematicOptions       // additional testing options
	TerraformTestStarted      bool                        // keeps track of when actual Terraform resource testing has begin, used for proper test teardown logic
	TerraformResourcesCreated bool                        // keeps track of when we start deploying resources, used for proper test teardown logic
	CloudInfoService          cloudinfo.CloudInfoServiceI // reference to a CloudInfoService resource
	BaseTerraformRepo         string                      // the URL of the origin git repository, typically the base that the PR will merge into, used for upgrade test
	BaseTerraformRepoBranch   string                      // the branch name of the main origin branch of the project (main or master), used for upgrade test
	TestTerraformRepo         string                      // the URL of the repo for the pull request, will be either origin or a fork
	TestTerraformRepoBranch   string                      // the branch of the test, usually the current checked out branch of the test run
	BaseTerraformTempDir      string                      // if upgrade test, will contain the temp directory containing clone of base repo
}

main data struct for all schematic test methods

func (*SchematicsTestService) CreateApplyJob 

func (svc *SchematicsTestService) CreateApplyJob() (*schematics.WorkspaceActivityApplyResult, error)

CreateApplyJob will initiate a new APPLY action on an existing terraform Schematics Workspace. Will return a result object containing details about the new action.

func (*SchematicsTestService) CreateAuthenticator 

func (svc *SchematicsTestService) CreateAuthenticator(ibmcloudApiKey string)

CreateAuthenticator will accept a valid IBM cloud API key, and set a valid Authenticator object that will be used in the external provider service for schematics.

func (*SchematicsTestService) CreateDestroyJob 

func (svc *SchematicsTestService) CreateDestroyJob() (*schematics.WorkspaceActivityDestroyResult, error)

CreateDestroyJob will initiate a new DESTROY action on an existing terraform Schematics Workspace. Will return a result object containing details about the new action.

func (*SchematicsTestService) CreatePlanJob 

func (svc *SchematicsTestService) CreatePlanJob() (*schematics.WorkspaceActivityPlanResult, error)

CreatePlanJob will initiate a new PLAN action on an existing terraform Schematics Workspace. Will return a result object containing details about the new action.

func (*SchematicsTestService) CreateTestWorkspace 

func (svc *SchematicsTestService) CreateTestWorkspace(name string, resourceGroup string, region string, templateFolder string, terraformVersion string, tags []string) (*schematics.WorkspaceResponse, error)

CreateTestWorkspace will create a new IBM Schematics Workspace that will be used for testing.

func (*SchematicsTestService) CreateUploadTarFile added in v1.43.0 

func (svc *SchematicsTestService) CreateUploadTarFile(projectPath string) (string, error)

CreateUploadTarFile will create a tar file with terraform code, based on include patterns set in options. Returns the full tarball name that was created on local system (path included).

func (*SchematicsTestService) DeleteWorkspace 

func (svc *SchematicsTestService) DeleteWorkspace() (string, error)

DeleteWorkspace will delete the existing workspace created for the test service.

func (*SchematicsTestService) FindLatestWorkspaceJobByName 

func (svc *SchematicsTestService) FindLatestWorkspaceJobByName(jobName string) (*schematics.WorkspaceActivity, error)

FindLatestWorkspaceJobByName will find the latest executed job of the type supplied and return data about that job. This can be used to find a job by its type when the jobID is not known. A "NotFound" error will be thrown if there are no existing jobs of the provided type.

func (*SchematicsTestService) GetRefreshToken 

func (svc *SchematicsTestService) GetRefreshToken() (string, error)

GetRefreshToken will use a previously established Authenticator to create a new IAM Token object, if existing is not valid, and return the refresh token propery from the token object.

func (*SchematicsTestService) GetWorkspaceJobDetail 

func (svc *SchematicsTestService) GetWorkspaceJobDetail(jobID string) (*schematics.WorkspaceActivity, error)

GetWorkspaceJobDetail will return a data structure with full details about an existing Schematics Workspace activity for the given Job ID.

func (*SchematicsTestService) InitializeSchematicsService 

func (svc *SchematicsTestService) InitializeSchematicsService() error

InitializeSchematicsService will initialize the external service object for schematicsv1 and assign it to a property of the receiver for later use.

func (*SchematicsTestService) UpdateTestTemplateVars 

func (svc *SchematicsTestService) UpdateTestTemplateVars(vars []TestSchematicTerraformVar) error

UpdateTestTemplateVars will update an existing Schematics Workspace terraform template with a Variablestore, which will set terraform input variables for test runs.

func (*SchematicsTestService) UploadTarToWorkspace 

func (svc *SchematicsTestService) UploadTarToWorkspace(tarPath string) error

UploadTarToWorkspace will accept a file path for an existing TAR file, containing files for a Terraform test case, and upload it to an existing Schematics Workspace.

func (*SchematicsTestService) WaitForFinalJobStatus 

func (svc *SchematicsTestService) WaitForFinalJobStatus(jobID string) (string, error)

WaitForFinalJobStatus will look up details about the given activity and check the status value. If the status implies that the activity has not completed yet, this function will keep checking the status value until either the activity has finished, or a configured time threshold has been reached. Returns the final status value of the activity when it has finished. Returns an error if the activity does not finish before the configured time threshold.

type TestSchematicOptions 

type TestSchematicOptions struct {
	// REQUIRED: a pointer to an initialized testing object.
	// Typically you would assign the test object used in the unit test.
	Testing *testing.T `copier:"-"`

	// Assign the list of file patterns, including directories, that you want included in the TAR file that will get uploaded
	// to the schematics workspace. Wildcards are valid.
	// Only files that match these patterns will be used as source for the Schematic Workspace in this test.
	// NOTE: all file paths are relative to the root of the current Git project.
	//
	// Examples:
	// "*.tf", "scripts/*.sh", "examples/basic/*", "data/my-data.yml"
	//
	// Default if not provided:
	// "*.tf" (all terraform files in project root only)
	TarIncludePatterns []string

	// The default constructors will use this map to check that all required environment variables are set properly.
	// If any are missing, the test will fail.
	RequiredEnvironmentVars map[string]string

	// Path to YAML file contaning preferences for how dynamic regions should be chosen.
	// See examples in cloudinfo/testdata for proper format.
	BestRegionYAMLPath string

	// Used with dynamic region selection, if any errors occur this will be the region used (fail-open)
	DefaultRegion string

	// If set during creation, this region will be used for test and dynamic region selection will be skipped.
	// If left empty, this will be populated by dynamic region selection by default constructor and can be referenced later.
	Region string

	// Set this value to force a specific region for the Schematics Workspace.
	// Default will choose a random valid region for the workspace.
	WorkspaceLocation string

	// Only required if using the WithVars constructor, as this value will then populate the `resource_group` input variable.
	ResourceGroup string

	// REQUIRED: the string prefix that will be prepended to all resource names, typically sent in as terraform input variable.
	// Set this value in the default constructors and a unique 6-digit random string will be appended.
	// Can then be referenced after construction and used as unique variable.
	//
	// Example:
	// Supplied to constructor = `my-test`
	// After constructor = `my-test-xu5oby`
	Prefix string

	// This array will be used to construct a valid `Variablestore` configuration for the Schematics Workspace Template
	TerraformVars []TestSchematicTerraformVar

	// This value will set the `folder` attribute in the Schematics template, and will be used as the execution folder for terraform.
	// Defaults to root directory of source, "." if not supplied.
	//
	// Example: if you are testing a module source, and the execution is located in the subdirectory `examples/basic`, then set this
	// to that value.
	TemplateFolder string

	// Optional list of tags that will be applied to the Schematics Workspace instance
	Tags []string

	// Amount of time, in minutes, to wait for any schematics job to finish. Set to override the default.
	// Default: 120 (two hours)
	WaitJobCompleteMinutes int16

	// Base URL of the schematics REST API. Set to override default.
	// Default will be based on the appropriate endpoint for the chosen `WorkspaceRegion`
	SchematicsApiURL string

	// Set this to true if you would like to delete the test Schematic Workspace if the test fails.
	// By default this will be false, and if a failure happens the workspace and logs will be preserved for analysis.
	DeleteWorkspaceOnFail bool

	// If you want to skip test teardown (both resource destroy and workspace deletion)
	SkipTestTearDown bool

	// This value is used to set the terraform version attribute for the workspace and template.
	// If left empty, an empty value will be set in the template which will cause the Schematic jobs to use the highest available version.
	//
	// Format: "terraform_v1.x"
	TerraformVersion string

	// Use this optional list to provide .netrc credentials that will be used by schematics to access any private git repos accessed by
	// the project.
	//
	// This data will be used to construct a special `__netrc__` environment variable in the template.
	NetrcSettings []NetrcCredential

	// Use this optional list to provide any additional ENV values for the template.
	// NOTE: these values are only used to configure the template, they are not set as environment variables outside of schematics.
	WorkspaceEnvVars []WorkspaceEnvironmentVariable // array of ENV variables to set inside workspace

	CloudInfoService cloudinfo.CloudInfoServiceI // OPTIONAL: Supply if you need multiple tests to share info service and data
	SchematicsApiSvc SchematicsApiSvcI           // OPTIONAL: service pointer for interacting with external schematics api

	// For Consistency Checks: Specify terraform resource names to ignore for consistency checks.
	// You can ignore specific resources in both idempotent and upgrade consistency checks by adding their names to these
	// lists. There are separate lists for adds, updates, and destroys.
	//
	// This can be useful if you have resources like `null_resource` that are marked with a lifecycle that causes a refresh on every run.
	// Normally this would fail a consistency check but can be ignored by adding to one of these lists.
	//
	// Name format is terraform style, for example: `module.some_module.null_resource.foo`
	IgnoreAdds     testhelper.Exemptions
	IgnoreDestroys testhelper.Exemptions
	IgnoreUpdates  testhelper.Exemptions

	// Use these options to specify a base terraform repo and branch to use for upgrade tests.
	// If not supplied, the default logic will be used to determine the base repo and branch.
	// Will be overridden by environment variables BASE_TERRAFORM_REPO and BASE_TERRAFORM_BRANCH if set.
	//
	// For repositories that require authentication:
	// - For HTTPS repositories, set the GIT_TOKEN environment variable to your Personal Access Token (PAT).
	// - For SSH repositories, set the SSH_PRIVATE_KEY environment variable to your SSH private key value.
	//   If the SSH_PRIVATE_KEY environment variable is not set, the default SSH key located at ~/.ssh/id_rsa will be used.
	//   Ensure that the appropriate public key is added to the repository's list of authorized keys.
	//
	// BaseTerraformRepo:   The URL of the base Terraform repository.
	BaseTerraformRepo string
	// BaseTerraformBranch: The branch within the base Terraform repository to use for upgrade tests.
	BaseTerraformBranch string

	// These optional fields can be used to override the default retry settings for making Schematics API calls.
	// If SDK/API calls to Schematics result in errors, such as retrieving existing workspace details,
	// the test framework will retry those calls for a set number of times, with a wait time between calls.
	//
	// NOTE: these are pointers to int, so that we know they were purposly set (they are nil), as zero is a legitimate value
	//
	// Current Default: 5 retries, 5 second wait
	SchematicSvcRetryCount       *int
	SchematicSvcRetryWaitSeconds *int

	// By default the logs from schematics jobs will only be printed to the test log if there is a failure in the job.
	// Set this value to `true` to have all schematics job logs (plan/apply/destroy) printed to the test log.
	PrintAllSchematicsLogs bool

	// These properties will be set to true by the test when an upgrade test was performed.
	// You can then inspect this value after the test run, if needed, to make further code decisions.
	// NOTE: this is not an option field that is meant to be set from a unit test, it is informational only
	IsUpgradeTest      bool
	UpgradeTestSkipped bool // Informs the calling test that conditions were met to skip the upgrade test

	// Set to true if you wish for an Upgrade test to do a final `terraform apply` after the consistency check on the new (not base) branch.
	CheckApplyResultForUpgrade bool
	// contains filtered or unexported fields
}

TestSchematicOptions is the main data struct containing all options related to running a Terraform unit test wihtin IBM Schematics Workspaces

func TestSchematicOptionsDefault 

func TestSchematicOptionsDefault(originalOptions *TestSchematicOptions) *TestSchematicOptions

TestSchematicOptionsDefault is a constructor for struct TestSchematicOptions. This function will accept an existing instance of TestSchematicOptions values, and return a new instance of TestSchematicOptions with the original values set along with appropriate default values for any properties that were not set in the original options.

Summary of properties changed: * appends unique 6-char string to end of original prefix * checks that certain required environment variables are set * computes best dynamic region for test, if Region is not supplied * sets various other properties to sensible defaults if not supplied

func (*TestSchematicOptions) AddNetrcCredential 

func (options *TestSchematicOptions) AddNetrcCredential(hostname string, username string, password string)

AddNetrcCredential is a helper function for TestSchematicOptions that will append a new netrc credential struct to the appropriate array in the options struct

func (*TestSchematicOptions) AddNetrcCredentialByEnv 

func (options *TestSchematicOptions) AddNetrcCredentialByEnv(hostname string, usernameEnvKey string, passwordEnvKey string) error

AddNetrcCredential is a helper function for TestSchematicOptions that will append a new netrc credential struct to the appropriate options array, by retrieving the username and password by lookup up supplied environment variable keys. error returned if any keys are missing in local environment

func (*TestSchematicOptions) AddNetrcCredentialByEnvDefault 

func (options *TestSchematicOptions) AddNetrcCredentialByEnvDefault(hostname string) error

AddNetrcCredentialByEnvDefault is a helper function for TestSchematicOptions that will append a new netrc credential struct to the appropriate options array, by retrieving the username and password by looking up the default environment variable keys error returned if any keys are missing in local environment

func (*TestSchematicOptions) AddWorkspaceEnvVar 

func (options *TestSchematicOptions) AddWorkspaceEnvVar(key string, value string, hidden bool, secure bool)

AddWorkspaceEnvVar is a helper function for TestSchematicOptions that will append a new ENV entry to options that will be added to the workspace during the test

func (*TestSchematicOptions) AddWorkspaceEnvVarFromLocalEnv 

func (options *TestSchematicOptions) AddWorkspaceEnvVarFromLocalEnv(key string, hidden bool, secure bool) error

AddWorkspaceEnvVarFromLocalEnv is a helper function for TestSchematicOptions that will append a new ENV entry to options that will be added to the workspace during the test. The value for the environment variable will be queried from the local OS under the same env var key. error returned if the key is not set in local environment.

func (*TestSchematicOptions) Clone 

func (options *TestSchematicOptions) Clone() (*TestSchematicOptions, error)

Clone makes a deep copy of most fields on the Options object and returns it.

NOTE: options.SshAgent and options.Logger CANNOT be deep copied (e.g., the SshAgent struct contains channels and listeners that can't be meaningfully copied), so the original values are retained.

func (*TestSchematicOptions) GetCheckConsistencyOptions added in v1.42.0 

func (options *TestSchematicOptions) GetCheckConsistencyOptions() *testhelper.CheckConsistencyOptions

To support consistency check options interface

func (*TestSchematicOptions) RunSchematicTest 

func (options *TestSchematicOptions) RunSchematicTest() error

RunSchematicTest will use the supplied options to run an end-to-end Terraform test of a project in an IBM Cloud Schematics Workspace. This test will include the following steps: 1. create test workspace 2. (optional) create and upload tar file of terraform project to workspace 3. configure supplied test variables in workspace 4. run PLAN/APPLY/DESTROY steps on workspace to provision and destroy resources 5. check consistency by running additional PLAN after APPLY and checking for updated resources 6. delete the test workspace

func (*TestSchematicOptions) RunSchematicUpgradeTest added in v1.43.0 

func (options *TestSchematicOptions) RunSchematicUpgradeTest() error

RunSchematicUpgradeTest will use the supplied options to run an end-to-end Terraform test of a project in an IBM Cloud Schematics Workspace. The Upgrade test will first use the workspace to provision resources using the main branch of the repo, then switch the workspace to the current PR branch and run an additional PLAN and check for consistency.

This test will include the following steps: 1. create test workspace 2. configure for main branch and supplied test variables in workspace 4. run PLAN/APPLY steps on workspace to provision main branch resources 5. switch workspace to PR branch 5. check upgrade consistency by running PLAN and checking for updated resources 6. delete the test workspace

type TestSchematicTerraformVar 

type TestSchematicTerraformVar struct {
	Name     string      // name of variable
	Value    interface{} // value of variable
	DataType string      // the TERRAFORM DATA TYPE of the varialbe (not golang type)
	Secure   bool        // true if value should be hidden
}

type WorkspaceEnvironmentVariable 

type WorkspaceEnvironmentVariable struct {
	Key    string // key name to set in workspace
	Value  string // value of env var
	Hidden bool   // metadata to hide this env var
	Secure bool   // metadata to mark value as sensitive
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.