aws-amplify · iliapolo · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
@@ -39,15 +39,14 @@ with a specific combination of Amplify categories and configurations. See
 
 ### Fix a Bug
 
-The snapshot inputs (`_snapshot.pre.*`) don't change — only the code and possibly the
-expected outputs (`_snapshot.post.*`) change.
-
 1. Read the relevant Context above for the area you're touching.
 
-2. Analyze the bug by reading the affected app's snapshot files. Read the
-   `_snapshot.pre.generate/` and/or `_snapshot.pre.refactor/` files to understand the
-   input configuration, and the `_snapshot.post.*` files to identify what's wrong in the
-   current output.
+2. Determine whether an existing test app covers the bug's scenario. Read the affected
+   app's `_snapshot.pre.generate/` and/or `_snapshot.pre.refactor/` files to understand
+   the input configuration, and the `_snapshot.post.*` files to identify what's wrong in
+   the current output. If no existing app exercises the affected code path, follow the
+   "Adding an App" or "Modifying an App" instructions from `amplify-migration-apps/README.md`
+   to add or update the `_snapshot.pre.*` inputs before proceeding.
 
 3. Reproduce the bug by running the appropriate E2E test:
 
@@ -56,8 +55,11 @@ expected outputs (`_snapshot.post.*`) change.
    npm run test:e2e
    ```
 
-   After the E2E run, inspect the live Gen1 and Gen2 resources and CloudFormation stack
-   events using the AWS CLI to confirm the root cause.
+   The E2E tool logs the directory where on-the-fly snapshots are captured for this run
+   (look for the `Snapshot directory:` line in the output). You can inspect the files in
+   that directory to see the state of the app at each step. In addition, inspect the live
+   Gen1 and Gen2 resources and CloudFormation stack events using the AWS CLI to confirm
+   the root cause.
 
 4. Present the root cause analysis to the user.
 
@@ -111,6 +113,12 @@ expected outputs (`_snapshot.post.*`) change.
    UPDATE_SNAPSHOTS=1 npm run test:e2e
    ```
 
+   The E2E tool logs the directory where on-the-fly snapshots are captured for this run
+   (look for the `Snapshot directory:` line in the output). You can inspect the files in
+   that directory to see the state of the app at each step. In addition, inspect the live
+   Gen1 and Gen2 resources and CloudFormation stack events using the AWS CLI to confirm
+   correctness.
+
 8. Run `yarn build && yarn test` in `packages/amplify-cli/` to verify nothing else broke.
    If tests fail at this point, only test code changes should be needed — the production
    code was already validated by the E2E run.
@@ -293,27 +293,36 @@ Make sure to follow the existing patterns and add tests as well.
 2. Run `amplify init`.
 3. Configure the backend using Gen1 CLI.
 4. Run `amplify push`.
-5. Use the [Snapshot Capture Tool](#snapshot-capture-tool) to capture the `pre.generate` snapshot.
+5. Add validation tests under `<app-name>/tests/` that exercise the new app's capabilities
+   (API queries, auth flows, storage operations, etc.). Follow the patterns in existing apps
+   like `project-boards/tests/` or `fitness-tracker/tests/`.
+6. Use the [Snapshot Capture Tool](#snapshot-capture-tool) to capture the `pre.generate` snapshot.
 
     ```console
     npx tsx snapshot.ts pre.generate <app-name>
 
-6. Run `UPDATE_SNAPSHOTS=1 npm run test:e2e` to execute the full migration flow and capture
-   the remaining snapshots (`post.generate`, `pre.refactor`, `post.refactor`).
+7. Run `UPDATE_SNAPSHOTS=1 npm run test:e2e` to execute the full migration flow and capture
+   the remaining snapshots (`post.generate`, `pre.refactor`, `post.refactor`). The E2E may
+   fail if the new app exercises a bug in the migration tooling. In that case the snapshots
+   will not be updated — fix the bug first, then re-run.
 
 ## Modifying an App
 
 1. `cd` into a specific app and run `npm run deploy`.
 2. Locate the deployed app directory in output logs and `cd` into it.
 3. Update the backend using Gen1 CLI.
 4. Run `amplify push`.
-5. Use the [Snapshot Capture Tool](#snapshot-capture-tool) to capture the `pre.generate` snapshot.
+5. Add or update validation tests under `<app-name>/tests/` to cover the modified
+   capabilities. Follow the patterns in existing apps like `project-boards/tests/`.
+6. Use the [Snapshot Capture Tool](#snapshot-capture-tool) to capture the `pre.generate` snapshot.
 
     ```console
     npx tsx snapshot.ts pre.generate <app-name>
 
-6. Run `UPDATE_SNAPSHOTS=1 npm run test:e2e` to execute the full migration flow and capture
-   the remaining snapshots (`post.generate`, `pre.refactor`, `post.refactor`).
+7. Run `UPDATE_SNAPSHOTS=1 npm run test:e2e` to execute the full migration flow and capture
+   the remaining snapshots (`post.generate`, `pre.refactor`, `post.refactor`). The E2E may
+   fail if the app change exercises a bug in the migration tooling. In that case the
+   snapshots will not be updated — fix the bug first, then re-run.
 
 ## Snapshot Testing
 

@@ -12,6 +12,7 @@
     "typecheck": "cd _snapshot.post.generate/amplify && npx tsc --noEmit",
     "test:gen1": "true",
     "test:gen2": "true",
+    "test:shared-data": "true",
     "test:e2e": "cd ../../packages/amplify-gen2-migration-e2e-system && npx tsx src/cli.ts --app backend-only --profile ${AWS_PROFILE:-default}",
     "deploy": "cd ../../packages/amplify-gen2-migration-e2e-system && npx tsx src/cli.ts --app backend-only --step deploy --profile ${AWS_PROFILE:-default}",
     "pre-push": "true",

@@ -3,34 +3,61 @@
  * Post-refactor script for discussions app.
  *
  * Applies manual edits required after `amplify gen2-migration refactor`:
- * 1. Add tableName to the DynamoDB table definition in backend.ts
- *    This ensures the refactored table keeps its original name.
+ * 1. Add tableName to the activity DynamoDB table definition in backend.ts
+ * 2. Add tableName to the bookmarks DynamoDB table definition in backend.ts
+ * 3. Uncomment s3Bucket.bucketName to preserve the original bucket name
  */
 
 import fs from 'fs/promises';
 import path from 'path';
 
-async function addTableNameToActivityTable(appPath: string, envName: string): Promise<void> {
+async function addTableNameToTable(
+  appPath: string,
+  stackVar: string,
+  tableId: string,
+  envName: string,
+): Promise<void> {
   const backendPath = path.join(appPath, 'amplify', 'backend.ts');
   const content = await fs.readFile(backendPath, 'utf-8');
 
-  const tableName = `activity-${envName}`;
+  const tableName = `${tableId}-${envName}`;
 
+  // Insert tableName as its own property line after the opening brace,
+  // matching the indentation of the existing partitionKey property.
   const updated = content.replace(
-    /new Table\(storageStack,\s*["']activity["'],\s*\{\s*partitionKey:/g,
-    `new Table(storageStack, "activity", { tableName: "${tableName}", partitionKey:`,
+    new RegExp(
+      `(new Table\\(${stackVar},\\s*["']${tableId}["'],\\s*\\{\\n)(\\s*)(partitionKey:)`,
+    ),
+    `$1$2tableName: '${tableName}',\n$2$3`,
   );
 
   await fs.writeFile(backendPath, updated, 'utf-8');
 }
 
-export async function postRefactor(appPath: string, envName = 'main'): Promise<void> {
-  await addTableNameToActivityTable(appPath, envName);
+async function uncommentS3BucketName(appPath: string): Promise<void> {
+  const backendPath = path.join(appPath, 'amplify', 'backend.ts');
+  const content = await fs.readFile(backendPath, 'utf-8');
+
+  const updated = content.replace(
+    /\/\/\s*(s3Bucket\.bucketName\s*=\s*['"][^'"]+['"];?)/g,
+    '$1',
+  );
+
+  await fs.writeFile(backendPath, updated, 'utf-8');
+}
+
+export async function postRefactor(appPath: string, envName: string): Promise<void> {
+  await addTableNameToTable(appPath, 'storageActivityStack', 'activity', envName);
+  await addTableNameToTable(appPath, 'storageBookmarksStack', 'bookmarks', envName);
+  await uncommentS3BucketName(appPath);
 }
 
 async function main(): Promise<void> {
-  const [appPath = process.cwd(), envName] = process.argv.slice(2);
-  await postRefactor(appPath, envName);
+  const [appPath = process.cwd()] = process.argv.slice(2);
+  if (!process.env.ENV_NAME) {
+    throw new Error(`Missing ENV_NAME env variable`);
+  }
+  await postRefactor(appPath, process.env.ENV_NAME);
 }
 
 main().catch((error) => {

@@ -14,8 +14,9 @@
     "configure-schema": "./backend/configure-schema.sh",
     "sanitize": "tsx ../sanitize.ts",
     "typecheck": "cd _snapshot.post.generate/amplify && npx tsc --noEmit",
-    "test:gen1": "APP_CONFIG_PATH=${APP_CONFIG_PATH:-src/amplifyconfiguration.json} NODE_OPTIONS='--experimental-vm-modules' jest --verbose",
-    "test:gen2": "APP_CONFIG_PATH=${APP_CONFIG_PATH:-amplify_outputs.json} NODE_OPTIONS='--experimental-vm-modules' jest --verbose",
+    "test:gen1": "APP_CONFIG_PATH=${APP_CONFIG_PATH:-src/amplifyconfiguration.json} NODE_OPTIONS='--experimental-vm-modules' jest --verbose --testPathIgnorePatterns='shared-data'",
+    "test:gen2": "APP_CONFIG_PATH=${APP_CONFIG_PATH:-amplify_outputs.json} NODE_OPTIONS='--experimental-vm-modules' jest --verbose --testPathIgnorePatterns='shared-data'",
+    "test:shared-data": "NODE_OPTIONS='--experimental-vm-modules' jest --verbose tests/shared-data.test.ts",
     "test:e2e": "cd ../../packages/amplify-gen2-migration-e2e-system && npx tsx src/cli.ts --app discussions --profile ${AWS_PROFILE:-default}",
     "deploy": "cd ../../packages/amplify-gen2-migration-e2e-system && npx tsx src/cli.ts --app discussions --step deploy --profile ${AWS_PROFILE:-default}",
     "pre-push": "true",

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { generateClient } from 'aws-amplify/api';
 import { getCurrentUser, signIn, signOut } from 'aws-amplify/auth';
-import { signUp, config } from './signup';
+import { signUp, configureAmplify } from './signup';
 import {
   getTopic, listTopics,
   getPost, listPosts,
@@ -20,6 +20,7 @@ let username: string;
 let password: string;
 
 beforeAll(async () => {
+  const config = configureAmplify();
   const creds = await signUp(config);
   username = creds.username;
   password = creds.password;