Added documentation around testing, and updated test library (#662)

* Updated the test framework

* Added documentation for testing

* Removed details from source file

* Added screenshot

README.md

@@ -114,6 +114,70 @@ TF_REATTACH_PROVIDERS='{"octopus.com/com/octopusdeploy":{"Protocol":"grpc","Prot
 ```
 5. In the same terminal session where you exported the environment variable, execute the Terraform commands you want to debug.
 
+## Testing
+
+The tests under `integration_test.go` verify the Terraform modules under the `terraform` directory run as expected. At a high level, the tests work like this:
+
+* Create a new Octopus Deploy instance and MSSQL in Docker using Test Containers.
+* Create a new blank space using the module in `1-singlespace`.
+* Populate the new space using one of the other modules under the `terraform` directory.
+* Inspect the new space with the Octopus Go client to verify the newly created resources exist and have the expected settings.
+
+These tests are split by [go-test-split-action](https://github.com/hashicorp-forge/go-test-split-action) to run in parallel across multiple GitHub Action workers as part of the build.
+
+To run the tests locally, you must have the following environment variables:
+
+* `LICENSE`: base 64 encoded octopus license XML file
+* `ECR_ACCESS_KEY`: aws access key (optional, and only used for ECR feed tests)
+* `ECR_SECRET_KEY`: aws secret key (optional, and only used for ECR feed tests)
+* `GIT_CREDENTIAL`: github token (optional, and only used for CaC tests)
+* `GIT_USERNAME`: github username (optional, and only used for CaC tests)
+
+By default, the tests spin up an Octopus instance based on the locally pulled `octopusdeploy/octopusdeploy:latest` image. You can override the image and tag with the following environment variables:
+
+* `OCTOTESTIMAGEURL`: The image to use to create the Octopus instance. Defaults to `octopusdeploy/octopusdeploy`. Can be set to `octopusdeploy/linuxoctopus` to test the Octopus cloud builds. Note you must be logged into DockerHub with the correct credentials to pull this private image.
+* `OCTOTESTVERSION`: The version of the image to use. Defaults to `latest`.
+
+The tests can be run in parallel to speed up the test run time. Set the `GOMAXPROCS` environment variable to the number of parallel tests you want to run. For example, to run 4 tests in parallel, set `GOMAXPROCS=4`. Note though that each test creates it own Octopus and MSSQL docker images, so you will need to have enough resources to run the tests in parallel.
+
+The tests work by executing the `terraform` executable against the test modules. By default, the version of the terraform provider that is used for these tests is defined in the file `config.tf`. The version defined in this file is almost always going to be a few revisions old.
+
+To test the latest build of the Terraform provider, you must build the provider executable locally and define an override to configure Terraform to ignore the version of the provider defined in the module and instead use your local build.
+
+Build the terraform provider with the command:
+
+```bash
+go build -o terraform-provider-octopusdeploy main.go
+```
+
+Then save the following configuration to a file called `~/.terraformrc`, making sure to replace the string `/var/home/yourname/Code/` with the path to the directory containing the Terraform provider executable:
+
+```hcl
+provider_installation {
+  dev_overrides {
+    "octopusdeploylabs/octopusdeploy" = "/var/home/yourname/Code/terraform-provider-octopusdeploy"
+  }
+
+  direct {}
+}
+```
+
+When the overrides are in effect, `terraform` will print a warning message to the console:
+
+```bash
+Warning: Provider development overrides are in effect
+
+The following provider development overrides are set in the CLI
+configuration:
+ - octopusdeploylabs/octopusdeploy in /var/home/yourname/Code/terraform-provider-octopusdeploy
+```
+
+If you wish to view the Octopus instance created by the test framework, add a breakpoint after the call to `testFramework.Act()` and get the IP address and port from the `container` argument:
+
+![](test-debugging.png)
+
+You can then log into the Octopus instance with the credentials `admin` and `Password01!`.
+
 ## Documentation Generation
 
 Documentation is auto-generated by the [tfplugindocs CLI](https://github.com/hashicorp/terraform-plugin-docs). To generate the documentation, run the following command:

go.mod

@@ -4,7 +4,7 @@ go 1.21
 
 require (
 	github.com/OctopusDeploy/go-octopusdeploy/v2 v2.43.0
-	github.com/OctopusSolutionsEngineering/OctopusTerraformTestFramework v0.0.0-20240502041300-f71244db277d
+	github.com/OctopusSolutionsEngineering/OctopusTerraformTestFramework v0.0.0-20240622231527-24df7b6eaa48
 	github.com/google/uuid v1.6.0
 	github.com/gruntwork-io/terratest v0.41.11
 	github.com/hashicorp/go-cty v1.4.1-0.20200723130312-85980079f637
@@ -43,7 +43,7 @@ require (
 	github.com/buger/jsonparser v1.1.1 // indirect
 	github.com/cenkalti/backoff/v4 v4.2.1 // indirect
 	github.com/cloudflare/circl v1.3.7 // indirect
-	github.com/containerd/containerd v1.7.12 // indirect
+	github.com/containerd/containerd v1.7.15 // indirect
 	github.com/containerd/log v0.1.0 // indirect
 	github.com/cpuguy83/dockercfg v0.3.1 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
@@ -125,7 +125,7 @@ require (
 	github.com/shopspring/decimal v1.3.1 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/spf13/cast v1.5.0 // indirect
-	github.com/testcontainers/testcontainers-go v0.30.0 // indirect
+	github.com/testcontainers/testcontainers-go v0.31.0 // indirect
 	github.com/tklauser/go-sysconf v0.3.12 // indirect
 	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/tmccombs/hcl2json v0.3.6 // indirect

go.sum

@@ -42,6 +42,8 @@ github.com/OctopusDeploy/go-octopusdeploy/v2 v2.43.0 h1:fYwGBqG88xy3qHp5j1ySCztd
 github.com/OctopusDeploy/go-octopusdeploy/v2 v2.43.0/go.mod h1:GZmFu6LmN8Yg0tEoZx3ytk9FnaH+84cWm7u5TdWZC6E=
 github.com/OctopusSolutionsEngineering/OctopusTerraformTestFramework v0.0.0-20240502041300-f71244db277d h1:E0Rm52/XBlVzdkHET/+Js1FVVgf5/0oRk1tNkI4jcyk=
 github.com/OctopusSolutionsEngineering/OctopusTerraformTestFramework v0.0.0-20240502041300-f71244db277d/go.mod h1:Nyg+7cyTrSQ/lMIy5YY1UdJekRuoMWf4uHIPfaGmgTM=
+github.com/OctopusSolutionsEngineering/OctopusTerraformTestFramework v0.0.0-20240622231527-24df7b6eaa48 h1:lxcmT+JUYCe2pA7owBK47/z0jY3va03yl1sQA3n0/Xo=
+github.com/OctopusSolutionsEngineering/OctopusTerraformTestFramework v0.0.0-20240622231527-24df7b6eaa48/go.mod h1:/QwYrEWP690YoKAR9lUVEv2y1Ta0HY08OaWb4LMZCAw=
 github.com/ProtonMail/go-crypto v1.1.0-alpha.2 h1:bkyFVUP+ROOARdgCiJzNQo2V2kiB97LyUpzH9P6Hrlg=
 github.com/ProtonMail/go-crypto v1.1.0-alpha.2/go.mod h1:rA3QumHc/FZ8pAHreoekgiAbzpNsfQAosU5td4SnOrE=
 github.com/agext/levenshtein v1.2.1/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558=
@@ -83,6 +85,8 @@ github.com/cncf/xds/go v0.0.0-20231128003011-0fa0005c9caa h1:jQCWAUqqlij9Pgj2i/P
 github.com/cncf/xds/go v0.0.0-20231128003011-0fa0005c9caa/go.mod h1:x/1Gn8zydmfq8dk6e9PdstVsDgu9RuyIIJqAaF//0IM=
 github.com/containerd/containerd v1.7.12 h1:+KQsnv4VnzyxWcfO9mlxxELaoztsDEjOuCMPAuPqgU0=
 github.com/containerd/containerd v1.7.12/go.mod h1:/5OMpE1p0ylxtEUGY8kuCYkDRzJm9NO1TFMWjUpdevk=
+github.com/containerd/containerd v1.7.15 h1:afEHXdil9iAm03BmhjzKyXnnEBtjaLJefdU7DV0IFes=
+github.com/containerd/containerd v1.7.15/go.mod h1:ISzRRTMF8EXNpJlTzyr2XMhN+j9K302C21/+cr3kUnY=
 github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
 github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
 github.com/cpuguy83/dockercfg v0.3.1 h1:/FpZ+JaygUR/lZP2NlFI2DVfrOEMAIKP5wWEJdoYe9E=
@@ -419,6 +423,8 @@ github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsT
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/testcontainers/testcontainers-go v0.30.0 h1:jmn/XS22q4YRrcMwWg0pAwlClzs/abopbsBzrepyc4E=
 github.com/testcontainers/testcontainers-go v0.30.0/go.mod h1:K+kHNGiM5zjklKjgTtcrEetF3uhWbMUyqAQoyoh8Pf0=
+github.com/testcontainers/testcontainers-go v0.31.0 h1:W0VwIhcEVhRflwL9as3dhY6jXjVCA27AkmbnZ+UTh3U=
+github.com/testcontainers/testcontainers-go v0.31.0/go.mod h1:D2lAoA0zUFiSY+eAflqK5mcUx/A5hrrORaEQrd0SefI=
 github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFAEVmqU=
 github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
 github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk=

integration_test.go

@@ -1,39 +1,5 @@
 package main
 
-/*
-	To test the Octopus Terraform provider locally, save the following into a failed called ~/.terraformrc, replacing
-	/var/home/yourname/Code/terraform-provider-octopusdeploy with the directory containing your clone
-	of the git repo:
-
-		provider_installation {
-		  dev_overrides {
-			"octopusdeploylabs/octopusdeploy" = "/var/home/yourname/Code/terraform-provider-octopusdeploy"
-		  }
-
-		  direct {}
-		}
-
-	Checkout the provider with
-
-		git clone https://github.com/OctopusDeployLabs/terraform-provider-octopusdeploy.git
-
-	Then build the provider executable with the command:
-
-		go build -o terraform-provider-octopusdeploy main.go
-
-	Terraform will then use the local executable rather than download the provider from the registry.
-
-	To build the and run the tests, run:
-
-		export LICENSE=base 64 octopus license
-		export ECR_ACCESS_KEY=aws access key
-		export ECR_SECRET_KEY=aws secret key
-		export GIT_CREDENTIAL=github token
-		export GIT_USERNAME=github username
-		go test -c -o integration_test
-		./integration_test
-*/
-
 import (
 	"fmt"
 	"net/url"
@@ -96,8 +62,8 @@ func TestSpaceResource(t *testing.T) {
 			return err
 		}
 
-		if space.Description != "My test space" {
-			t.Fatalf("New space must have the name \"My test space\"")
+		if space.Description != "TestSpaceResource" {
+			t.Fatalf("New space must have the name \"TestSpaceResource\"")
 		}
 
 		if space.IsDefault {

terraform/1-singlespace/space.tf

@@ -1,8 +1,8 @@
 resource "octopusdeploy_space" "octopus_space_test" {
-  name                  = "${var.octopus_space_name}"
+  name                  = var.octopus_space_name
   is_default            = false
   is_task_queue_stopped = false
-  description           = "My test space"
+  description           = var.octopus_space_description
   space_managers_teams  = ["teams-administrators"]
 }
 
@@ -17,3 +17,11 @@ variable "octopus_space_name" {
   description = "The name of the new space"
   default     = "Test"
 }
+
+variable "octopus_space_description" {
+  type        = string
+  nullable    = false
+  sensitive   = false
+  description = "The description of the new space"
+  default     = "My test space"
+}