# Live AWS Testing Guide

This document is the Stage 2 handoff for live validation. Stage 1 is complete only after the code, docs, and non-live tests are in place. At that point, provide a real AWS CLI profile and region and continue with the commands below.

For day-to-day contributor workflow, use `docs/development-workflow.md`. This file is only the live AWS runbook.

## What to provide before live testing

Provide these values when you are ready:

- `login_session` profiles are supported, so a browser-authenticated AWS login cache is acceptable.
- AWS CLI profile name
- target AWS region
- whether EC2 instance creation is allowed in that account

Example setup:

```powershell
aws configure --profile awspipe-test
$env:AWS_PROFILE="awspipe-test"
$env:AWS_REGION="eu-west-1"
aws sts get-caller-identity
```

## Create disposable test resources

Create a single suffix and reuse it:

```powershell
$SUFFIX = Get-Date -Format "yyyyMMddHHmmss"
$BUCKET = "awspipe-test-$SUFFIX"
$VPC_CIDR = "10.77.0.0/16"
$SUBNET_CIDR = "10.77.1.0/24"
```

Create S3, VPC, subnet, and security group resources:

```powershell
aws s3api create-bucket --bucket $BUCKET --region $env:AWS_REGION --create-bucket-configuration LocationConstraint=$env:AWS_REGION

$VPC_ID = aws ec2 create-vpc --cidr-block $VPC_CIDR --query "Vpc.VpcId" --output text
aws ec2 create-tags --resources $VPC_ID --tags Key=Name,Value="awspipe-test-vpc-$SUFFIX"

$SUBNET_ID = aws ec2 create-subnet --vpc-id $VPC_ID --cidr-block $SUBNET_CIDR --availability-zone "$($env:AWS_REGION)a" --query "Subnet.SubnetId" --output text
aws ec2 create-tags --resources $SUBNET_ID --tags Key=Name,Value="awspipe-test-subnet-$SUFFIX"

$SG_ID = aws ec2 create-security-group --group-name "awspipe-test-sg-$SUFFIX" --description "awspipe test sg" --vpc-id $VPC_ID --query "GroupId" --output text
aws ec2 create-tags --resources $SG_ID --tags Key=Name,Value="awspipe-test-sg-$SUFFIX"
```

Optional EC2 instance for `aws_ec2_instance` validation:

```powershell
$AMI_ID = aws ssm get-parameter --name "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64" --query "Parameter.Value" --output text
$INSTANCE_ID = aws ec2 run-instances --image-id $AMI_ID --instance-type t3.micro --subnet-id $SUBNET_ID --security-group-ids $SG_ID --tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=awspipe-test-ec2-$SUFFIX}]" --query "Instances[0].InstanceId" --output text
```

## awspipe validation commands

Run these commands after syncing the project:

```powershell
$env:UV_CACHE_DIR='.uv-cache'
uv sync --extra dev
uv run awspipe doctor --profile awspipe-test --region eu-west-1
uv run awspipe tables
uv run awspipe query "select * from aws_account" --profile awspipe-test --region eu-west-1
uv run awspipe query "select name, region from aws_s3_bucket order by name" --profile awspipe-test --region eu-west-1
uv run awspipe query "select vpc_id, cidr_block from aws_vpc" --profile awspipe-test --region eu-west-1
uv run awspipe query "select subnet_id, vpc_id, cidr_block from aws_subnet" --profile awspipe-test --region eu-west-1
uv run awspipe query "select group_id, group_name, vpc_id from aws_security_group" --profile awspipe-test --region eu-west-1
uv run awspipe query "select instance_id, vpc_id, subnet_id, state from aws_ec2_instance" --profile awspipe-test --region eu-west-1
uv run awspipe query "select instance_id, state from aws_ec2_instance" --profile awspipe-test --region eu-west-1 --refresh
```

## What to verify

Check that:

- `doctor` resolves the expected account and region
- `aws_account` returns the active account ID and caller ARN
- `aws_s3_bucket` includes the disposable bucket with the expected region
- `aws_vpc`, `aws_subnet`, and `aws_security_group` include the created network resources
- `aws_ec2_instance` returns the optional instance when created
- rerunning the same query works without changing results, and `--refresh` forces a refetch cleanly

Cross-check with raw AWS CLI output when needed:

```powershell
aws s3api list-buckets
aws ec2 describe-vpcs
aws ec2 describe-subnets
aws ec2 describe-security-groups
aws ec2 describe-instances
```

## Cleanup

Destroy the test resources when validation is complete:

```powershell
if ($INSTANCE_ID) { aws ec2 terminate-instances --instance-ids $INSTANCE_ID | Out-Null }
if ($INSTANCE_ID) { aws ec2 wait instance-terminated --instance-ids $INSTANCE_ID }

aws ec2 delete-security-group --group-id $SG_ID
aws ec2 delete-subnet --subnet-id $SUBNET_ID
aws ec2 delete-vpc --vpc-id $VPC_ID

aws s3 rm "s3://$BUCKET" --recursive
aws s3api delete-bucket --bucket $BUCKET --region $env:AWS_REGION
```

## Ready-for-credentials milestone

Once Stage 1 is green locally, stop and wait for the live AWS profile and region from the operator. Do not claim full completion until the live validation above has been run successfully.
