Restructure integration testing documentation

content/docs/iac/guides/testing/integration/_index.md

@@ -0,0 +1,87 @@
+---
+title_tag: "Integration Testing for Pulumi Programs"
+meta_desc: "Guide to integration testing of Pulumi programs with various testing frameworks and approaches."
+title: Integration testing
+h1: Integration Testing for Pulumi Programs
+meta_image: /images/docs/meta-images/docs-meta.png
+weight: 3
+menu:
+    iac:
+        name: Integration testing
+        parent: iac-guides-testing
+        weight: 3
+        identifier: iac-guides-testing-integration
+    usingpulumi:
+        parent: testing
+        identifier: testing-integration
+aliases:
+    - /docs/guides/testing/integration/
+    - /docs/using-pulumi/testing/integration/
+    - /docs/iac/concepts/testing/integration/
+---
+
+Integration testing validates your Pulumi programs by running your program and testing the results without examining internal implementation details. For example, you might test that an HTTP endpoint is available and gives the expected response to an incoming request. An integration test runs the program in combination with the Pulumi CLI or Automation API to deploy infrastructure to an ephemeral environment. Once your tests are run and the correctness of your infrastructure is verified (or refuted), you will typically destroy the infrastructure you created for the test. This approach is known as "black-box testing" because it tests the program from the outside.
+
+## Why integration testing?
+
+Integration testing allows you to validate that your infrastructure code works correctly in a real cloud environment. Unlike unit tests that mock cloud resources, or Policy as Code that verifies expectations for specific resources in your stack, integration tests deploy actual infrastructure to verify your code's behavior end-to-end.
+
+By running a program through integration tests, you can ensure:
+
+- Your project's code is syntactically well-formed and runs without errors.
+- Your stack's configuration and secrets work and are interpreted correctly.
+- Your project can be successfully deployed to your cloud provider of choice.
+- Resources of the desired shape are successfully created.
+- The infrastructure behaves as expected: for example, a health-check endpoint returns a valid HTML document, or a suite of application-level tests succeeds against the public API.
+- Your project can be successfully updated from its starting state to other states.
+- Your project can be successfully destroyed and removed from your cloud provider.
+
+## Integration testing options
+
+Pulumi supports several approaches to integration testing, each with different trade-offs:
+
+### Integration testing framework
+
+Pulumi provides a [dedicated integration testing framework](/docs/iac/guides/testing/integration/framework/) written in Go. This framework is designed to drive lifecycle operations against a Pulumi program: deploying a new stack from scratch, optionally updating it with variations, and tearing it down afterwards.
+
+Benefits:
+
+- Purpose-built for testing Pulumi programs
+- Comprehensive lifecycle testing capabilities, including the ability to test update/upgrade paths
+- Robust validation options for resources and runtime behavior
+- Can test Pulumi programs written in any supported language
+
+Constraints:
+
+- Tests must be written in Go
+
+### Automation API
+
+You can use [Automation API for integration testing](/docs/iac/guides/testing/integration/automation-api/) to programmatically run CLI actions and write tests using your preferred testing framework. This approach gives you full control over the testing process using the programming language of your choice.
+
+Benefits:
+
+- Write tests in your preferred language and testing framework
+- Full programmatic control over stack lifecycle
+- Easy integration with existing language-specific tooling for testing
+- Available in Node.js, Python, .NET, Go, and Java
+
+Constraints:
+
+- Not available in YAML
+
+### DIY Options
+
+You can also write integration tests by executing Pulumi CLI commands via shell (either by executing a shell script or by executing shell commands in your preferred language) and making assertions in any language. While Automation API makes this easier by providing language-native APIs, you can accomplish similar results with shell scripts if needed.
+
+Benefits:
+
+- Works with any programming language
+- Simple to understand and implement
+- No additional dependencies beyond the Pulumi CLI
+
+Trade-offs:
+
+- More manual error handling
+- Less type-safe than Automation API
+- More difficult to extract and validate resource properties

content/docs/iac/guides/testing/integration/automation-api.md

@@ -0,0 +1,71 @@
+---
+title_tag: "Integration Testing with Automation API"
+meta_desc: "Learn how to use Pulumi's Automation API to write integration tests in your preferred programming language."
+title: Automation API testing
+h1: Integration Testing with Automation API
+meta_image: /images/docs/meta-images/docs-meta.png
+weight: 2
+menu:
+    iac:
+        name: Automation API testing
+        parent: iac-guides-testing-integration
+        weight: 2
+---
+
+Pulumi's [Automation API](/docs/iac/automation-api/) provides a programmatic interface for integration testing. While not a purpose-built integration testing framework, you can use Automation API in your integration tests to accomplish the same objectives of basic correctness testing, resource validation, and runtime testing. Automation API is available in all Pulumi languages except YAML and is a part of the Pulumi SDK.
+
+## Testing workflow
+
+To write integration tests with Automation API, follow these steps:
+
+1. Create a stack using Automation API.
+1. Set up stack configuration and secrets.
+1. Deploy the stack using `up()`.
+1. Perform resource validation by examining the deployment state.
+1. Perform runtime checks by interacting with deployed infrastructure.
+1. Tear down the stack using `destroy()` and clean up resources.
+
+## Validating resource and stack properties
+
+To validate that the correct resources were created with the expected properties, you can export the stack and examine the resulting resources.
+
+For example, in TypeScript:
+
+```typescript
+export async function getDeployment(): Promise<Deployment> {
+  const stack = await LocalWorkspace.createOrSelectStack(args);
+
+  return stack.exportStack();
+}
+```
+
+You can then iterate through the `Deployment` object to check that the expected resources and property values are present.
+
+## Validating infrastructure correctness
+
+Runtime validation involves interacting with your deployed infrastructure to verify it works correctly. For example, you might:
+
+- Make HTTP requests to validate an API endpoint
+- Query a database to verify data was created correctly
+- Check that files exist in object storage
+- Verify that VMs are responding to network requests
+
+The Automation API gives you full access to stack outputs, which typically include endpoints, URLs, and other information needed to interact with your infrastructure.
+
+## Example
+
+The [`localProgram-tsnode-mochatests` example](https://github.com/pulumi/automation-api-examples/tree/main/nodejs/localProgram-tsnode-mochatests) demonstrates how to:
+
+- Set up a stack using Automation API
+- Perform runtime validation checks
+- Tear down the stack as part of a test
+
+## Additional resources
+
+Integration tests written with Automation API in the Pulumi SDK repositories:
+
+- [Node.js tests](https://github.com/pulumi/pulumi/blob/master/sdk/nodejs/tests/automation/localWorkspace.spec.ts)
+- [Go tests](https://github.com/pulumi/pulumi/blob/master/sdk/go/auto/local_workspace_test.go)
+- [Python tests](https://github.com/pulumi/pulumi/blob/master/sdk/python/lib/test/automation/test_local_workspace.py)
+- [C# tests](https://github.com/pulumi/pulumi-dotnet/blob/main/sdk/Pulumi.Automation.Tests/LocalWorkspaceTests.cs)
+- [Java example](https://github.com/pulumi/automation-api-examples/blob/main/java/localProgram/)