chore: add e2e convenience tooling (cloud-e2e, e2e-monitor)

AGENTS.md

@@ -0,0 +1,102 @@
+# Agent Guidelines for amplify-codegen
+
+## E2E Testing
+
+### Overview
+
+E2E tests run via AWS CodeBuild. The project uses a batch build that fans out into
+multiple test suites. All tests must pass (100%) before a PR can be merged.
+
+### Prerequisites
+
+1. Copy `scripts/sample.env` to `scripts/.env` and fill in the account IDs (get these from your team lead):
+   ```bash
+   cp scripts/sample.env scripts/.env
+   # Edit scripts/.env with your account values
+   ```
+
+2. Ensure you have valid credentials (`mwinit` or equivalent).
+
+### Triggering E2E Tests
+
+**For a PR:**
+```bash
+yarn cloud-pr
+# Interactive: prompts for PR number
+```
+
+**For the current branch:**
+```bash
+yarn cloud-e2e
+# Or directly:
+./scripts/cloud-e2e.sh
+```
+
+**For a specific PR (non-interactive):**
+```bash
+./scripts/cloud-e2e.sh pr/1035
+```
+
+### Monitoring E2E Tests
+
+After triggering, you'll get a batch ID like `amplify-codegen-e2e-workflow:abc123-...`.
+
+**Check status:**
+```bash
+yarn e2e-status <batchId>
+```
+
+**Monitor with auto-retry (polls every 5 min, retries transient failures):**
+```bash
+yarn e2e-monitor <batchId>
+# With custom max retries:
+yarn e2e-monitor <batchId> 5
+```
+
+**List recent batches:**
+```bash
+yarn e2e-list
+```
+
+**View failed builds:**
+```bash
+yarn e2e-failed <batchId>
+```
+
+**View build logs:**
+```bash
+yarn e2e-logs <buildId>
+```
+
+**Retry failed builds manually:**
+```bash
+yarn e2e-retry <batchId>
+```
+
+### Process
+
+1. **Trigger**: Run `yarn cloud-e2e` or `./scripts/cloud-e2e.sh pr/<number>`
+2. **Monitor**: Run `yarn e2e-monitor <batchId>` — this polls every 5 minutes and auto-retries transient failures
+3. **Verify**: 100% pass rate required. If failures persist after retries, investigate the logs with `yarn e2e-failed` and `yarn e2e-logs`
+4. **Retry**: For persistent transient failures, use `yarn e2e-retry <batchId>`
+
+### Important Notes
+
+- Account IDs and credentials go in `scripts/.env` (gitignored), **never** in committed code
+- The e2e profile is `AmplifyAPIE2EProd` with role `CodebuildDeveloper`
+- Tests run in `us-east-1`
+- Batch builds typically take 30-90 minutes depending on test count
+- The monitor command exits with code 0 on success, 1 on failure
+
+### Available CodeBuild Projects
+
+- `amplify-codegen-e2e-workflow` — Full e2e test suite (used by `cloud-e2e`)
+- `amplify-codegen-pr-workflow` — PR validation (used by `cloud-pr`)
+- `amplify-codegen-cleanup-workflow` — Stale resource cleanup
+
+### Debugging Failures
+
+1. Get failed builds: `yarn e2e-failed <batchId>`
+2. View logs: `yarn e2e-logs <buildId>`
+3. Re-run with debug session: `yarn cloud-e2e-debug <batchId>`
+4. Authenticate for manual AWS CLI use: `yarn authenticate-e2e-profile`

package.json

@@ -49,7 +49,13 @@
     "authenticate-e2e-profile": "source scripts/cloud-utils.sh && authenticateWithE2EProfile",
     "extract-dependency-licenses": "./scripts/extract-dependency-licenses.sh",
     "verify-dependency-licenses-extract": "yarn extract-dependency-licenses && ./scripts/verify-dependency-licenses.sh",
-    "deprecate": "ts-node scripts/deprecate_release.ts"
+    "deprecate": "ts-node scripts/deprecate_release.ts",
+    "e2e-status": "yarn ts-node scripts/e2e-test-manager.ts status",
+    "e2e-monitor": "yarn ts-node scripts/e2e-test-manager.ts monitor",
+    "e2e-retry": "yarn ts-node scripts/e2e-test-manager.ts retry",
+    "e2e-list": "yarn ts-node scripts/e2e-test-manager.ts list",
+    "e2e-failed": "yarn ts-node scripts/e2e-test-manager.ts failed",
+    "e2e-logs": "yarn ts-node scripts/e2e-test-manager.ts logs"
   },
   "bugs": {
     "url": "https://github.com/aws-amplify/amplify-codegen/issues"
@@ -126,7 +132,8 @@
     "rimraf": "^3.0.0",
     "ts-jest": "^27.0.0",
     "ts-node": "^8.10.1",
-    "typescript": "4.7.4"
+    "typescript": "4.7.4",
+    "@aws-sdk/client-cloudwatch-logs": "^3.1080.0"
   },
   "resolutions": {
     "**/@aws-amplify/amplify-codegen-e2e-tests/**/cookie": "^0.7.0",

scripts/cloud-e2e.sh

@@ -0,0 +1,60 @@
+#!/bin/bash -e
+
+# Triggers the amplify-codegen e2e test suite on the current branch.
+#
+# Usage:
+#   ./scripts/cloud-e2e.sh              # Run e2e on current branch
+#   ./scripts/cloud-e2e.sh pr/1035      # Run e2e on a specific PR
+#
+# Prerequisites:
+#   - scripts/.env must exist with E2E_ACCOUNT_PROD set (see scripts/sample.env)
+#   - mwinit credentials must be active
+
+scriptDir=$(dirname -- "$(readlink -f -- "$BASH_SOURCE")")
+source "$scriptDir/.env"
+
+if [ -z "$E2E_ACCOUNT_PROD" ]; then
+  echo "❌ E2E_ACCOUNT_PROD is not set. Please configure scripts/.env (see scripts/sample.env)"
+  exit 1
+fi
+
+REGION=us-east-1
+E2E_ROLE_NAME=CodebuildDeveloper
+E2E_PROFILE_NAME=AmplifyAPIE2EProd
+E2E_PROJECT_NAME=amplify-codegen-e2e-workflow
+
+# Determine source version
+if [ -n "$1" ]; then
+  SOURCE_VERSION="$1"
+else
+  SOURCE_VERSION=$(git branch --show-current)
+fi
+
+echo "🚀 Triggering E2E tests"
+echo "   Project: $E2E_PROJECT_NAME"
+echo "   Source:  $SOURCE_VERSION"
+echo ""
+
+# Authenticate
+echo "🔐 Authenticating..."
+ada cred update --profile="$E2E_PROFILE_NAME" --account="$E2E_ACCOUNT_PROD" --role="$E2E_ROLE_NAME" --provider=isengard --once
+aws configure set region $REGION --profile "$E2E_PROFILE_NAME"
+
+# Trigger the batch build
+RESULT=$(aws codebuild start-build-batch \
+  --profile="$E2E_PROFILE_NAME" \
+  --region "$REGION" \
+  --project-name "$E2E_PROJECT_NAME" \
+  --source-version="$SOURCE_VERSION" \
+  --environment-variables-override name=BRANCH_NAME,value="$SOURCE_VERSION",type=PLAINTEXT \
+  --query 'buildBatch.id' --output text)
+
+echo ""
+echo "✅ Build batch triggered!"
+echo "   Batch ID: $RESULT"
+echo ""
+echo "📋 Monitor with:"
+echo "   yarn e2e-monitor $RESULT"
+echo ""
+echo "🔗 Console URL:"
+echo "   https://$REGION.console.aws.amazon.com/codesuite/codebuild/$E2E_ACCOUNT_PROD/projects/$E2E_PROJECT_NAME/batch/$RESULT?region=$REGION"