feat: testing fixes as well as refactoring test organization and to use npm & tsx (#3)

* test: add unit tests for validation, update, errors, and zod-util

- src/cli/commands/add/validate.test.ts
- src/cli/commands/update/update.test.ts
- src/cli/errors.test.ts
- src/schema/schemas/zod-util.test.ts

🤖 Assisted by Amazon Q Developer

* refactor: move CLI integration tests from __tests__ to integ-tests

- Move help.test.ts and json-output.test.ts to integ-tests/
- Fix import paths for test-utils
- Remove empty src/cli/__tests__/ directory

These tests run the CLI as a black box and belong with other
integration tests, not colocated with source files.

* refactor: migrate from bun to esbuild/tsx/vitest\n\nBuild system:\n- Replace bun bundler with esbuild (esbuild.config.mjs)\n- Delete bun.build.ts\n\nRuntime:\n- Replace bun with tsx for TypeScript execution\n- Update dev server to use npx tsx watch\n- Update test runner to use node with built bundle\n\nTesting:\n- Replace bun:test with vitest\n- Migrate all assertions from node:assert to vitest expect\n- Move 29 test files to __tests__/ directories\n- Add vitest.config.ts with text-loader plugin\n\nDependencies:\n- Add: esbuild, tsx, vitest\n- Remove: @types/bun\n\nDocumentation:\n- Update CONTRIBUTING.md (remove bun prereq, add Testing section)\n- Update integ-tests/README.md (vitest commands/imports)\n- Add docs/TESTING.md\n\nConfig:\n- Update tsconfig.build.json to exclude test files\n- Add test and test:watch npm scripts

* fix: prefix Lambda template tool names to allow multiple behind-gateway tools\n\nWhen adding multiple behind-gateway Lambda tools, the hardcoded tool names\n(lookup_ip, get_random_user, fetch_post) would conflict in mcp-defs.json.\n\nNow tool names are prefixed with the MCP tool name (e.g., MyTool_lookup_ip)\nto avoid conflicts and allow multiple Lambda tools per project.

* fix: improve invoke command CLI mode detection and validation\n\n- Detect CLI mode when --json, --target, or --stream flags are provided\n  (follows the same pattern as deploy command)\n- Add validation for streaming mode requiring a prompt\n- Prevents unexpected TUI mode when user intends CLI usage

* fix: add optional sessionId field to AgentCoreDeployedStateSchema

* fix: resolve ESLint and TypeScript errors\n\n- Prefix unused parameters with underscore\n- Add null checks for optional values\n- Use String() for template expressions with unknown types\n- Add type assertions for exhaustive switch cases\n- Fix type imports

* chore: remove tests for unimplemented --policy flag\n\nThese tests were for a --policy flag on remove commands that was never\nimplemented. The tests used --policy cascade and --policy restrict\nwhich are not valid CLI options.

* test: fix remove command tests\n\n- Use alphanumeric names (schema requires no hyphens)\n- Update tests to expect cascade behavior (default removal policy)\n- Add result checks for add commands before testing remove\n- Fix field name (agentCoreGateways not gateways)

* test: fix various test issues\n\n- Remove target requirement test (target defaults to 'default')\n- Skip plan test requiring CDK dependencies (integration test)\n- Remove incorrect synth.lock cleanup test (intentionally not cleaned)\n- Fix import paths and add non-null assertions\n- Add cwd argument to runCLI calls

* style: apply prettier formatting to test files and imports

* fix: improve integration test infrastructure\n\n- Add LOCAL_L3_PATH env var support for local L3 constructs development\n- Separate integration tests into vitest.integ.config.ts with 120s timeout\n- Fix dev-server test: use built bundle, clear INIT_CWD env var\n- Add test:integ npm script for running integration tests

* fix: restore TypeScript (coming soon) disabled state

* fix: pass disabled property to SelectList for language options

* chore: remove test-output.txt

Author: aidandaly24

CONTRIBUTING.md

@@ -63,7 +63,6 @@ public github issue.
 ### Prerequisites
 
 - Node.js 20+
-- Bun (for CLI bundling)
 - npm
 
 ### Building
@@ -73,6 +72,15 @@ npm install
 npm run build
 ```
 
+### Testing
+
+```bash
+npm test           # Run all tests
+npm run test:watch # Run tests in watch mode
+```
+
+See [docs/TESTING.md](docs/TESTING.md) for detailed testing guidelines.
+
 ### Local Development with CDK Package
 
 If you're also developing the CDK package (`@aws/agentcore-l3-cdk-constructs`):

docs/TESTING.md

@@ -0,0 +1,116 @@
+# Testing Guide
+
+## Quick Start
+
+```bash
+npm test           # Run all tests
+npm run test:watch # Run tests in watch mode
+```
+
+## Test Organization
+
+### Unit Tests
+
+Unit tests are co-located with source files in `__tests__/` directories:
+
+```
+src/cli/commands/add/
+├── action.ts
+├── command.ts
+└── __tests__/
+    └── add.test.ts
+```
+
+### Integration Tests
+
+Integration tests live in `integ-tests/`:
+
+```
+integ-tests/
+├── create-no-agent.test.ts
+├── create-with-agent.test.ts
+├── deploy.test.ts
+└── ...
+```
+
+See [integ-tests/README.md](../integ-tests/README.md) for integration test details.
+
+## Writing Tests
+
+### Imports
+
+Use vitest for all test utilities:
+
+```typescript
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+```
+
+### Assertions
+
+Use `expect` assertions:
+
+```typescript
+// Equality
+expect(result).toBe('expected');
+expect(obj).toEqual({ key: 'value' });
+
+// Truthiness
+expect(value).toBeTruthy();
+expect(value).toBeFalsy();
+
+// Errors
+expect(() => fn()).toThrow();
+expect(() => fn()).toThrow('message');
+```
+
+### Mocking
+
+Use `vi` for mocks:
+
+```typescript
+// Mock functions
+const mockFn = vi.fn();
+mockFn.mockReturnValue('value');
+mockFn.mockResolvedValue('async value');
+
+// Spies
+vi.spyOn(module, 'method');
+
+// Module mocks
+vi.mock('./module');
+```
+
+## Test Utilities
+
+### CLI Runner
+
+`src/test-utils/cli-runner.ts` runs CLI commands in tests:
+
+```typescript
+import { runCLI } from '../src/test-utils/cli-runner';
+
+const result = await runCLI(['create', '--name', 'test'], tempDir);
+expect(result.exitCode).toBe(0);
+```
+
+## Configuration
+
+Test configuration is in `vitest.config.ts`:
+
+- Test timeout: 15 seconds
+- Hook timeout: 60 seconds
+- Test patterns: `src/**/*.test.ts`, `integ-tests/**/*.test.ts`
+
+## Integration Tests
+
+Integration tests require:
+
+- AWS credentials configured
+- IAM permissions for CloudFormation operations
+- Dedicated test AWS account (recommended)
+
+Run integration tests:
+
+```bash
+npm run test:integ
+```

bun.build.ts esbuild.config.mjsbun.build.ts renamed to esbuild.config.mjs

@@ -1,9 +1,11 @@
+import * as esbuild from 'esbuild';
 import * as fs from 'fs';
+import { createRequire } from 'module';
 
 // Stub plugin for optional dev dependencies
 const optionalDepsPlugin = {
   name: 'optional-deps',
-  setup(build: Parameters<Parameters<typeof Bun.build>[0]['plugins'][number]['setup']>[0]) {
+  setup(build) {
     // Stub react-devtools-core (only used when DEV=true)
     build.onResolve({ filter: /^react-devtools-core$/ }, () => ({
       path: 'react-devtools-core',
@@ -19,17 +21,18 @@ const optionalDepsPlugin = {
 // Text loader plugin for embedding files
 const textLoaderPlugin = {
   name: 'text-loader',
-  setup(build: Parameters<Parameters<typeof Bun.build>[0]['plugins'][number]['setup']>[0]) {
+  setup(build) {
+    // Handle .md and .txt files as text
     build.onLoad({ filter: /\.(md|txt)$/ }, async args => {
-      const text = await Bun.file(args.path).text();
+      const text = await fs.promises.readFile(args.path, 'utf8');
       return {
         contents: `export default ${JSON.stringify(text)};`,
         loader: 'js',
       };
     });
-    // Handle .ts files in llm-compacted as text (use platform-agnostic pattern)
+    // Handle .ts files in llm-compacted as text
     build.onLoad({ filter: /llm-compacted[/\\].*\.ts$/ }, async args => {
-      const text = await Bun.file(args.path).text();
+      const text = await fs.promises.readFile(args.path, 'utf8');
       return {
         contents: `export default ${JSON.stringify(text)};`,
         loader: 'js',
@@ -38,13 +41,17 @@ const textLoaderPlugin = {
   },
 };
 
-await Bun.build({
-  entrypoints: ['./src/cli/index.ts'],
-  outdir: './dist/cli',
-  target: 'node',
+await esbuild.build({
+  entryPoints: ['./src/cli/index.ts'],
+  outfile: './dist/cli/index.mjs',
+  bundle: true,
+  platform: 'node',
   format: 'esm',
   minify: true,
-  naming: '[dir]/[name].mjs',
+  // Inject require shim for ESM compatibility with CommonJS dependencies
+  banner: {
+    js: `import { createRequire } from 'module'; const require = createRequire(import.meta.url);`,
+  },
   external: ['fsevents', '@aws-cdk/toolkit-lib'],
   plugins: [optionalDepsPlugin, textLoaderPlugin],
 });

integ-tests/README.md

@@ -15,7 +15,7 @@ This directory contains real AWS integration tests that actually deploy resource
 npm run test:integ
 
 # Run a specific test
-bun test --timeout 300000 integ-tests/integ.deploy.ts
+npx vitest run integ-tests/deploy.test.ts --testTimeout=300000
 ```
 
 ## Test Naming Convention
@@ -38,14 +38,14 @@ Integration tests are NOT run automatically on every PR. They can be triggered:
 ## Writing Integration Tests
 
 ```typescript
-import { runCLI } from '../src/test-utils';
-import { after, before, describe, it } from 'node:test';
+import { runCLI } from '../src/test-utils/cli-runner';
+import { afterAll, describe, expect, it } from 'vitest';
 
 describe('integ: deploy', () => {
   // Use unique stack names to avoid conflicts
   const stackName = `test-${Date.now()}`;
 
-  after(async () => {
+  afterAll(async () => {
     // ALWAYS clean up - destroy the stack
     await runCLI(['destroy', '--target', stackName, '--force'], projectDir);
   });

integ-tests/create-no-agent.test.ts

@@ -1,11 +1,10 @@
 import { exists, runCLI } from '../src/test-utils/index.js';
-import { afterAll, beforeAll, describe, it } from 'bun:test';
-import assert from 'node:assert';
 import { execSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { mkdir, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 function hasCommand(cmd: string): boolean {
   try {
@@ -35,22 +34,22 @@ describe('integration: create without agent', () => {
     const name = `IntegNoAgent${Date.now()}`;
     const result = await runCLI(['create', '--name', name, '--no-agent', '--json'], testDir, false);
 
-    assert.strictEqual(result.exitCode, 0, `stderr: ${result.stderr}`);
+    expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
 
     const json = JSON.parse(result.stdout);
-    assert.strictEqual(json.success, true);
+    expect(json.success).toBe(true);
 
     // Verify npm install ran (in CDK project directory)
-    assert.ok(
+    expect(
       await exists(join(json.projectPath, 'agentcore', 'cdk', 'node_modules')),
       'agentcore/cdk/node_modules/ should exist'
-    );
+    ).toBeTruthy();
 
     // Verify git init ran
-    assert.ok(await exists(join(json.projectPath, '.git')), '.git/ should exist');
+    expect(await exists(join(json.projectPath, '.git')), '.git/ should exist').toBeTruthy();
 
     // Verify at least one commit
     const gitLog = execSync('git log --oneline', { cwd: json.projectPath, encoding: 'utf-8' });
-    assert.ok(gitLog.trim().length > 0, 'Should have at least one commit');
+    expect(gitLog.trim().length > 0, 'Should have at least one commit').toBeTruthy();
   });
 });

integ-tests/create-with-agent.test.ts

@@ -1,11 +1,10 @@
 import { exists, runCLI } from '../src/test-utils/index.js';
-import { afterAll, beforeAll, describe, it } from 'bun:test';
-import assert from 'node:assert';
 import { execSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { mkdir, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 function hasCommand(cmd: string): boolean {
   try {
@@ -53,19 +52,22 @@ describe('integration: create with Python agent', () => {
       false
     );
 
-    assert.strictEqual(result.exitCode, 0, `stderr: ${result.stderr}`);
+    expect(result.exitCode, `stderr: ${result.stderr}`).toBe(0);
 
     const json = JSON.parse(result.stdout);
-    assert.strictEqual(json.success, true);
+    expect(json.success).toBe(true);
 
     // Verify npm install ran
-    assert.ok(await exists(join(json.projectPath, 'agentcore', 'cdk', 'node_modules')), 'node_modules/ should exist');
+    expect(
+      await exists(join(json.projectPath, 'agentcore', 'cdk', 'node_modules')),
+      'node_modules/ should exist'
+    ).toBeTruthy();
 
     // Verify git init ran
-    assert.ok(await exists(join(json.projectPath, '.git')), '.git/ should exist');
+    expect(await exists(join(json.projectPath, '.git')), '.git/ should exist').toBeTruthy();
 
     // Verify uv venv ran - .venv in app/{agentName} directory
     const agentDir = join(json.projectPath, 'app', json.agentName || name);
-    assert.ok(await exists(join(agentDir, '.venv')), '.venv/ should exist in agent directory');
+    expect(await exists(join(agentDir, '.venv')), '.venv/ should exist in agent directory').toBeTruthy();
   });
 });

integ-tests/deploy.test.ts

@@ -1,11 +1,10 @@
 import { runCLI } from '../src/test-utils/index.js';
-import { afterAll, beforeAll, describe, it } from 'bun:test';
-import assert from 'node:assert';
 import { execSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { mkdir, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 function hasCommand(cmd: string): boolean {
   try {
@@ -89,17 +88,17 @@ describe('integration: deploy', () => {
       const result = await runCLI(['destroy', '--target', targetName, '--yes', '--json'], projectPath, false);
 
       // Assert destroy succeeded
-      assert.strictEqual(result.exitCode, 0, `Destroy failed: ${result.stderr}`);
+      expect(result.exitCode, `Destroy failed: ${result.stderr}`).toBe(0);
       const json = JSON.parse(result.stdout);
-      assert.strictEqual(json.success, true, 'Destroy should report success');
+      expect(json.success, 'Destroy should report success').toBe(true);
     }
     await rm(testDir, { recursive: true, force: true });
   }, 120000);
 
   it.skipIf(!hasNpm || !hasGit || !hasUv || !hasAws)(
     'deploys to AWS successfully',
     async () => {
-      assert.ok(projectPath, 'Project should have been created');
+      expect(projectPath, 'Project should have been created').toBeTruthy();
 
       const result = await runCLI(['deploy', '--target', targetName, '--yes', '--json'], projectPath, false);
 
@@ -108,10 +107,10 @@ describe('integration: deploy', () => {
         console.log('Deploy stderr:', result.stderr);
       }
 
-      assert.strictEqual(result.exitCode, 0, `Deploy failed: ${result.stderr}`);
+      expect(result.exitCode, `Deploy failed: ${result.stderr}`).toBe(0);
 
       const json = JSON.parse(result.stdout);
-      assert.strictEqual(json.success, true, 'Deploy should report success');
+      expect(json.success, 'Deploy should report success').toBe(true);
     },
     180000
   );