feat: initial testing framework (PSKD-1682)

.github/workflows/default-plan-unit-tests.yml

@@ -0,0 +1,35 @@
+# Copyright © 2025, SAS Institute Inc., Cary, NC, USA. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+name: Default Plan Unit Tests
+on:
+  push:
+    branches: ['**'] # '*' will cause the workflow to run on all commits to all branches.
+
+jobs:
+  go-tests:
+    name: Default Plan Unit Tests
+    runs-on: ubuntu-latest
+    environment: terraformSecrets
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Build Docker Image
+        run: docker build -t viya4-iac-gcp:terratest -f Dockerfile.terratest .
+      - name: Construct Credential File
+        run: |
+          go run create_credentials_file.go > /dev/null || true
+        env:
+          GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}
+          GCP_PRIVATE_KEY_ID: ${{ secrets.GCP_PRIVATE_KEY_ID }}
+          GCP_PRIVATE_KEY: ${{ secrets.GCP_PRIVATE_KEY }}
+          GCP_CLIENT_EMAIL: ${{ secrets.GCP_CLIENT_EMAIL }}
+          GCP_CLIENT_ID: ${{ secrets.GCP_CLIENT_ID }}
+          GCP_CLIENT_CERT_URL: ${{ secrets.GCP_CLIENT_CERT_URL }}
+        working-directory: test
+      - name: Run Tests
+        run: |
+          docker run \
+            -v $(pwd)/test/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json \
+            -v $(pwd):/viya4-iac-gcp \
+            viya4-iac-gcp:terratest -v

.gitignore

@@ -8,3 +8,4 @@ terraform.tfvars
 .terraform.tfstate.lock.info
 *.lock.hcl
 *.swp
+test/testoutput/*

CONTRIBUTING.md

@@ -1,10 +1,13 @@
 # How to Contribute
-We'd love to accept your patches and contributions to this project.
-We just ask that you follow our contribution guidelines when you do.
+This project is community-driven, and we'd love to accept your patches and contributions.
+We just ask that you follow our contribution guidelines when you do. Refer
+to the [Contributor Handbook](https://sassoftware.github.io/contributor-handbook.html)
+for guidance.
 
 ## Contributor License Agreement
 Contributions to this project must be accompanied by a signed [Contributor Agreement](ContributorAgreement.txt).
-You (or your employer) retain the copyright to your contribution; this simply grants us permission to use and redistribute your contributions as part of the project.
+You (or your employer) retain the copyright to your contribution; this agreement simply grants
+us permission to use and redistribute your contributions as part of the project.
 
 ## Code Reviews
 All submissions to this project—including submissions from project members—require
@@ -13,6 +16,16 @@ tests, integration tests, and security scans.
 
 ## Pull Request Requirement
 
+### Automated Tests
+All contributors are expected to include appropriate tests to ensure code quality
+and maintainability. This may include unit and/or integration tests as applicable
+to the scope of the changes.  We have a developed a Golang testing framework using
+[Terratest](https://terratest.gruntwork.io/) for unit tests and are in the process
+of developing integration tests. Please refer to our [Testing Philosopy](./docs/user/TestingPhilosophy.md)
+documentation for more information on our testing framework. If you need additional
+help and guidance, we are happy to help you navigate it by providing continuous
+collaboration within the pull request.
+
 ### Conventional Commits
 All pull requests must follow the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/)
 standard for commit messages. This helps maintain a consistent and meaningful
@@ -51,4 +64,4 @@ To ensure that all submissions meet our security and quality standards, we perfo
 security scans using internal SAS infrastructure. Contributions might be subjected
 to security scans before they can be accepted. Reporting of any Common Vulnerabilities
 and Exposures (CVEs) that are detected is not available in this project at this
-time.
+time.

Dockerfile.terratest

@@ -0,0 +1,30 @@
+ARG GCP_CLI_VERSION=513.0.0
+
+FROM google/cloud-sdk:$GCP_CLI_VERSION-alpine AS gcpcli
+FROM golang:1.24
+
+# Install terraform from apt repository, terratest_log_parser, jq
+RUN \
+    apt-get update \
+    && apt-get install -y jq lsb-release \
+    && wget -O - https://apt.releases.hashicorp.com/gpg \
+        | gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
+        | tee /etc/apt/sources.list.d/hashicorp.list \
+    && apt update \
+    && apt install terraform \
+    && ssh-keygen -f ~/.ssh/id_rsa -P "" \
+    && go install github.com/gruntwork-io/terratest/cmd/terratest_log_parser@latest
+
+WORKDIR /viya4-iac-gcp/test
+
+# Copy gcloud from the google/cloud-sdk image
+COPY --from=gcpcli /google-cloud-sdk /google-cloud-sdk
+ENV PATH="/google-cloud-sdk/bin:${PATH}"
+
+# Copy the test directory so it can install the go modules
+# during the docker build rather than the docker run
+COPY ./test ./
+RUN go mod tidy
+
+ENTRYPOINT ["/viya4-iac-gcp/test/terratest_docker_entrypoint.sh"]

docs/user/TerratestDockerUsage.md

@@ -0,0 +1,150 @@
+# Using the Terratest Docker Container
+
+Use the Terratest Docker container to run the suite of Terratest Go tests. For more information on Terratest, follow the [Documentation](https://terratest.gruntwork.io/docs/) page. The Terratest Docker image is used by the [Github Workflow](../../.github/workflows/default_plan_unit_tests.yml) as a required check before merging changes.
+
+## Prereqs
+
+- Docker [installed on your workstation](../../README.md#docker).
+
+## Preparation
+
+### Docker image
+
+Run the following command to create the `viya4-iac-gcp-terratest` Docker image using the provided [Dockerfile.terratest](../../Dockerfile.terratest)
+
+```bash
+docker build -t viya4-iac-gcp-terratest -f Dockerfile.terratest .
+```
+
+The Docker image `viya4-iac-gcp-terratest` will contain Terraform and Go executables, as well as the required Go modules. The Docker entrypoint for the image is `go test`, and it accepts several optional command-line arguments. For more information about command-line arguments, see [Command-Line Arguments](#command-line-arguments).
+
+### Service Account Keyfile for Google Cloud Authentication 
+
+Prepare a file with Google Cloud authentication information, as described in [Authenticating Terraform to access Google Cloud](./TerraformGCPAuthentication.md) and store it outside of this repository in a secure file, for example `$HOME/.viya4-tf-gcp-service-account.json`.
+
+#### Public Access Cidrs Environment File
+
+In order to run  ```terraform apply``` integration tests, you will also need to define your ```TF_VAR_public_cidrs``` as described in [Admin Access](../CONFIG-VARS.md#admin-access), and create a file with the public access cidr values to use with container invocation.  Store these values in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) outside of this repository in a secure file, such as `$HOME/.gcp_public_cidrs.env`. Protect that file with public access cidr values so that only you have Read access to it. Below is an example of what the file should look like.
+
+```bash
+TF_VAR_public_cidrs=["123.456.7.8/16", "98.76.54.32/32"]
+```
+
+Now each time you invoke the container, specify the file with the [`--env-file`](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) option to pass the Cidrs to the container.
+
+### Docker Volume Mounts
+
+To mount the current working directory, add the following argument to the docker run command:
+`--volume="$(pwd)":/viya4-iac-gcp`
+Note that the project must be mounted to the `/viya4-iac-gcp` directory.
+
+## Command-Line Arguments
+
+The `terratest_docker_entrypoint.sh` script supports several command-line arguments to customize the test execution. Here are the available options:
+
+* `-p, --package=PACKAGE`: The package to test. Default is './...'
+* `-r, --run=TEST`: The name of the test to run. Default is '.\*Plan.\*'.
+* `-v, --verbose`: Run the tests in verbose mode.
+* `-h, --help`: Display the help message.
+
+## Running Terratest Commands
+
+### Running the Plan Tests
+
+To run the suite of unit tests (only `terraform plan`), run the following Docker command:
+
+```bash
+# Run from the ./viya4-iac-gcp directory
+docker run --rm \
+  --volume $HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json \
+  --volume "$(pwd)":/viya4-iac-gcp \
+  viya4-iac-gcp-terratest
+```
+
+### Running the Apply Tests
+
+To run the suite of integration tests (only `terraform apply`), run the following Docker command:
+
+```bash
+# Run from the ./viya4-iac-gcp directory
+docker run --rm \
+  --volume $HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json \
+  --env-file=$HOME/.gcp_public_cidrs.env \
+  --volume "$(pwd)":/viya4-iac-gcp \
+  viya4-iac-gcp-terratest \
+  -r=".*Apply.*"
+```
+
+### Running a Specific Go Test
+
+To run a specific test, run the following Docker command with the `-r` option:
+
+```bash
+# Run from the ./viya4-iac-gcp directory
+docker run --rm \
+  --volume $HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json \
+  --env-file=$HOME/.gcp_public_cidrs.env \ #env file for integration tests
+  --volume "$(pwd)":/viya4-iac-gcp \
+  viya4-iac-gcp-terratest \
+  -r="YourTest"
+```
+To run multiple tests, pass in a regex to the `-r` option - "TestName1|TestName2|TestName3"
+
+####  Running a Specific Integration Go Test
+
+To run a specific integration test, modify the main test runner function (e.g. YourIntegrationTestMainFunction) to define the test name you desire and run the following Docker command with the `-r` option:
+
+```bash
+# Run from the ./viya4-iac-gcp directory
+docker run --rm \
+  --volume $HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json \
+  --env-file=$HOME/.gcp_public_cidrs.env \
+  --volume "$(pwd)":/viya4-iac-gcp \
+  viya4-iac-gcp-terratest \
+  -r="YourIntegrationTestMainFunction"
+```
+
+### Running a Specific Go Package and Test
+
+If you want to specify the Go package and test name, run the following Docker command with the following options:
+
+```bash
+# Run from the ./viya4-iac-gcp directory
+docker run --rm \
+  --volume $HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json \
+  --volume "$(pwd)":/viya4-iac-gcp \
+  viya4-iac-gcp-terratest \
+  -r="YourTest" \
+  -p="YourPackage"
+```
+
+####  Running a Specific Integration Go Package and Test
+
+To run a specific integration Go package and test name, modify the main test runner function in the desired packaged to define the test name you want and run the following Docker command with the following options:
+
+```bash
+# Run from the ./viya4-iac-gcp directory
+docker run --rm \
+  --volume $HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json \
+  --env-file=$HOME/.gcp_public_cidrs.env \
+  --volume "$(pwd)":/viya4-iac-gcp \
+  viya4-iac-gcp-terratest \
+  -r="YourIntegrationTestMainFunction" \
+  -p="YourPackage"
+```
+
+### Running the Go Tests with verbose mode
+
+If you want to run the tests in verbose mode, run the Docker command with the `-v` option:
+
+```bash
+# Run from the ./viya4-iac-gcp directory
+docker run --rm \
+  --volume $HOME/.viya4-tf-gcp-service-account.json:/.viya4-tf-gcp-service-account.json \
+  --volume "$(pwd)":/viya4-iac-gcp \
+  viya4-iac-gcp-terratest -v
+```
+
+### Accessing test run logs
+
+After you have started the Docker container, log files are created in the `./viya4-iac-gcp/test/test_output` directory. These files enable you to view the test results in XML format, as well as test logs that are generated by the terrratest_log_parser.