env-secrets 0.1.10 → 0.3.0

package/__e2e__/README.md

@@ -0,0 +1,160 @@
+# End-to-End Tests
+
+This directory contains comprehensive end-to-end tests for the env-secrets CLI tool.
+
+## Prerequisites
+
+### LocalStack Setup
+
+The e2e tests use LocalStack to emulate AWS Secrets Manager. You need to have LocalStack running before executing the tests.
+
+#### Using Docker Compose (Recommended)
+
+```bash
+# Start LocalStack
+docker-compose up -d localstack
+
+# Wait for LocalStack to be ready
+docker-compose logs -f localstack
+```
+
+#### Manual LocalStack Setup
+
+```bash
+# Install LocalStack
+pip install localstack
+
+# Start LocalStack
+localstack start
+```
+
+### awslocal Setup
+
+The tests require `awslocal` to be installed, which is a wrapper around AWS CLI that automatically points to LocalStack:
+
+```bash
+# Install awslocal using pip (recommended)
+pip install awscli-local
+
+# Or using npm
+npm install -g awscli-local
+
+# Verify installation
+awslocal --version
+
+# Test connectivity to LocalStack
+awslocal sts get-caller-identity
+```
+
+**Note**: The tests will automatically check if `awslocal` is installed and provide helpful error messages if it's missing.
+
+## Environment Variables
+
+The following environment variables are used by the e2e tests:
+
+- `LOCALSTACK_URL`: LocalStack endpoint (default: `http://localhost:4566`)
+- `AWS_ACCESS_KEY_ID`: AWS access key (default: `test`)
+- `AWS_SECRET_ACCESS_KEY`: AWS secret key (default: `test`)
+- `AWS_DEFAULT_REGION`: AWS region (default: `us-east-1`)
+- `DEBUG`: Enable debug output (optional)
+
+**Note**: The tests automatically clean up AWS environment variables (like `AWS_PROFILE`, `AWS_SESSION_TOKEN`, etc.) to ensure a clean test environment.
+
+## Running Tests
+
+### Run All E2E Tests
+
+```bash
+npm run test:e2e
+```
+
+### Run E2E Tests with Coverage
+
+```bash
+npm run test:e2e:coverage
+```
+
+### Run Specific Test File
+
+```bash
+npm run build
+npx jest --config jest.e2e.config.js __e2e__/index.test.ts
+```
+
+### Run Tests with Debug Output
+
+```bash
+DEBUG=1 npm run test:e2e
+```
+
+## Test Structure
+
+### Test Categories
+
+1. **CLI Help Commands**: Tests for help, version, and general CLI functionality
+2. **AWS Secrets Manager Integration**: Tests for secret retrieval using different credential methods
+3. **Output to File**: Tests for writing secrets to files
+4. **Program Execution**: Tests for executing programs with injected environment variables
+5. **Error Handling**: Tests for various error scenarios
+
+### Test Utilities
+
+The `utils/test-utils.ts` file provides helper functions:
+
+- `LocalStackHelper`: Manages LocalStack operations (create/delete secrets, wait for readiness)
+- `cli()`: Execute CLI commands
+- `cliWithEnv()`: Execute CLI commands with custom environment variables
+- `createTempFile()` / `cleanupTempFile()`: Manage temporary files
+- `createTestProfile()` / `restoreTestProfile()`: Manage AWS profiles
+
+### Test Secrets
+
+The tests create and use several test secrets:
+
+- `test-secret-basic`: Basic JSON secret with API key and database URL
+- `test-secret-simple`: Simple string secret
+- `test-secret-complex`: Complex JSON with nested objects and arrays
+- `test-secret-special-chars`: Secret with special characters
+
+## Troubleshooting
+
+### LocalStack Not Starting
+
+If LocalStack fails to start:
+
+1. Check if port 4566 is available
+2. Ensure Docker is running
+3. Check LocalStack logs: `docker-compose logs localstack`
+
+### awslocal Issues
+
+If awslocal commands fail:
+
+1. Verify awslocal is installed: `awslocal --version`
+2. Test LocalStack connectivity: `awslocal sts get-caller-identity`
+3. Check if LocalStack is running: `docker-compose ps`
+
+### Test Failures
+
+Common issues and solutions:
+
+1. **Timeout errors**: Increase timeout in `jest.e2e.config.js`
+2. **Permission errors**: Ensure proper file permissions for AWS credentials
+3. **Network errors**: Check LocalStack endpoint URL and connectivity
+
+## Continuous Integration
+
+The e2e tests are designed to run in CI environments. Make sure to:
+
+1. Start LocalStack before running tests
+2. Set appropriate environment variables
+3. Install AWS CLI in the CI environment
+4. Allow sufficient time for LocalStack to start
+
+## Coverage Reports
+
+Coverage reports are generated in the `coverage-e2e/` directory:
+
+- `coverage-e2e/lcov-report/index.html`: HTML coverage report
+- `coverage-e2e/lcov.info`: LCOV format for CI integration
+- `coverage-e2e/coverage-final.json`: JSON coverage data

package/__e2e__/index.test.ts

@@ -0,0 +1,339 @@
+import {
+  LocalStackHelper,
+  cli,
+  cliWithEnv,
+  createTempFile,
+  cleanupTempFile,
+  createTestProfile,
+  restoreTestProfile,
+  TestSecret,
+  CreatedSecret
+} from './utils/test-utils';
+import { debugLog } from './utils/debug-logger';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+describe('End-to-End Tests', () => {
+  let localStack: LocalStackHelper;
+  let awsDir: string | undefined;
+
+  beforeAll(async () => {
+    localStack = new LocalStackHelper();
+    await localStack.waitForLocalStack();
+
+    // Create test AWS profile
+    awsDir = createTestProfile();
+  });
+
+  afterAll(async () => {
+    // Clean up all secrets created during this test run
+    await localStack.cleanupRunSecrets();
+
+    // Restore AWS profile
+    restoreTestProfile(awsDir);
+  });
+
+  // Helper function to create a secret for a test
+  const createTestSecret = async (
+    secret: TestSecret,
+    region?: string
+  ): Promise<CreatedSecret> => {
+    return await localStack.createSecret(secret, region);
+  };
+
+  // Helper function to create LocalStack environment variables
+  const getLocalStackEnv = (overrides: Record<string, string> = {}) => ({
+    AWS_ENDPOINT_URL: process.env.LOCALSTACK_URL || 'http://localhost:4566',
+    AWS_ACCESS_KEY_ID: 'test',
+    AWS_SECRET_ACCESS_KEY: 'test',
+    AWS_DEFAULT_REGION: 'us-east-1',
+    ...overrides
+  });
+
+  describe('CLI Help Commands', () => {
+    test('should show general help', async () => {
+      const result = await cli(['-h']);
+      expect(result.code).toBe(0);
+      expect(result.stdout).toContain('env-secrets');
+      expect(result.stdout).toContain('pull secrets from vaults');
+    });
+
+    test('should show AWS command help', async () => {
+      const result = await cli(['aws', '-h']);
+      expect(result.code).toBe(0);
+      expect(result.stdout).toContain('get secrets from AWS secrets manager');
+      expect(result.stdout).toContain('--secret');
+    });
+
+    test('should show version', async () => {
+      const result = await cli(['--version']);
+      expect(result.code).toBe(0);
+      expect(result.stdout).toMatch(/^\d+\.\d+\.\d+/);
+    });
+  });
+
+  describe('AWS Secrets Manager Integration', () => {
+    describe('Using Default AWS Credentials', () => {
+      test('should retrieve basic JSON secret', async () => {
+        const secret = await createTestSecret({
+          name: 'test-secret-basic',
+          value:
+            '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+          description: 'Basic test secret with API key and database URL'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+        expect(result.stderr).toBe('');
+      });
+
+      test('should retrieve simple string secret', async () => {
+        const secret = await createTestSecret({
+          name: 'test-secret-simple',
+          value: 'simple-string-value',
+          description: 'Simple string secret'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+        expect(result.stderr).toBe('');
+      });
+
+      test('should retrieve complex JSON secret', async () => {
+        const secret = await createTestSecret({
+          name: 'test-secret-complex',
+          value:
+            '{"NESTED": {"KEY": "value"}, "ARRAY": [1, 2, 3], "BOOLEAN": true, "NUMBER": 42}',
+          description: 'Complex JSON secret'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+        expect(result.stderr).toBe('');
+      });
+
+      test('should retrieve secret with special characters', async () => {
+        const secret = await createTestSecret({
+          name: 'test-secret-special-chars',
+          value:
+            '{"PASSWORD": "p@ssw0rd!#$%", "URL": "https://api.example.com/v1?key=value&other=test"}',
+          description: 'Secret with special characters'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+        expect(result.stderr).toBe('');
+      });
+
+      test('should handle non-existent secret', async () => {
+        const result = await cliWithEnv(
+          ['aws', '-s', 'non-existent-secret'],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+        expect(result.stderr).toContain('non-existent-secret not found');
+      });
+
+      test('should work with custom region', async () => {
+        const secret = await createTestSecret(
+          {
+            name: `test-secret-region-${Date.now()}`,
+            value:
+              '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+            description: 'Basic test secret for us-west-2'
+          },
+          'us-west-2'
+        );
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName, '-r', 'us-west-2'],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+        expect(result.stderr).toBe('');
+      });
+    });
+
+    describe('Using AWS Profile', () => {
+      test('should retrieve secret using default profile', async () => {
+        const secret = await createTestSecret({
+          name: 'test-secret-profile',
+          value:
+            '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+          description: 'Secret for profile test'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+        expect(result.stderr).toBe('');
+      });
+
+      test('should retrieve secret using custom profile', async () => {
+        const secret = await createTestSecret({
+          name: 'test-secret-profile-custom',
+          value:
+            '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+          description: 'Secret for custom profile test'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName, '-p', 'env-secrets-test'],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+        expect(result.stderr).toBe('');
+      });
+    });
+
+    describe('Output to File', () => {
+      test('should write secrets to file', async () => {
+        debugLog('Starting test...');
+
+        const secret = await createTestSecret({
+          name: `test-secret-file-${Date.now()}`,
+          value:
+            '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+          description: 'Secret for file output test'
+        });
+        debugLog('Secret created successfully');
+
+        const tempFile = path.join(
+          os.tmpdir(),
+          `env-secrets-test-${Date.now()}.env`
+        );
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName, '-o', tempFile],
+          getLocalStackEnv()
+        );
+
+        debugLog('CLI result:', {
+          code: result.code,
+          stdout: result.stdout,
+          stderr: result.stderr
+        });
+        expect(result.code).toBe(0);
+        expect(result.stdout).toContain(`Secrets written to ${tempFile}`);
+
+        // Verify file contents
+        const fileContent = fs.readFileSync(tempFile, 'utf8');
+        expect(fileContent).toContain('API_KEY=secret123');
+        expect(fileContent).toContain(
+          'DATABASE_URL=postgres://localhost:5432/test'
+        );
+
+        cleanupTempFile(tempFile);
+      });
+
+      test('should not overwrite existing file', async () => {
+        const tempFile = createTempFile('existing content');
+
+        try {
+          const result = await cliWithEnv(
+            ['aws', '-s', 'test-secret-basic', '-o', tempFile],
+            getLocalStackEnv()
+          );
+
+          expect(result.code).toBe(1);
+          expect(result.stderr).toContain(
+            'already exists and will not be overwritten'
+          );
+
+          // Verify file was not modified
+          const fileContent = fs.readFileSync(tempFile, 'utf8');
+          expect(fileContent).toBe('existing content');
+        } finally {
+          cleanupTempFile(tempFile);
+        }
+      });
+    });
+
+    describe('Program Execution', () => {
+      test('should execute program with injected environment variables', async () => {
+        const secret = await createTestSecret({
+          name: `test-secret-exec-${Date.now()}`,
+          value:
+            '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+          description: 'Secret for program execution test'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName, 'echo', '$API_KEY'],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+
+        // In test mode, the CLI outputs the environment variables as JSON
+        const envVars = JSON.parse(result.stdout.trim());
+        expect(envVars.API_KEY).toBe('secret123');
+        expect(envVars.DATABASE_URL).toBe('postgres://localhost:5432/test');
+      });
+
+      test('should handle program execution errors gracefully', async () => {
+        const secret = await createTestSecret({
+          name: `test-secret-error-${Date.now()}`,
+          value: '{"API_KEY": "secret123"}',
+          description: 'Secret for error handling test'
+        });
+
+        const result = await cliWithEnv(
+          ['aws', '-s', secret.prefixedName, 'nonexistent-command'],
+          getLocalStackEnv()
+        );
+
+        expect(result.code).toBe(0);
+
+        // In test mode, the CLI outputs the environment variables as JSON
+        const envVars = JSON.parse(result.stdout.trim());
+        expect(envVars.API_KEY).toBe('secret123');
+      });
+    });
+
+    describe('Error Handling', () => {
+      test('should handle invalid AWS credentials', async () => {
+        const result = await cliWithEnv(
+          ['aws', '-s', 'test-secret-basic'],
+          getLocalStackEnv({
+            AWS_ACCESS_KEY_ID: 'invalid',
+            AWS_SECRET_ACCESS_KEY: 'invalid'
+          })
+        );
+
+        // LocalStack accepts any credentials, so this should succeed
+        expect(result.code).toBe(0);
+      });
+
+      test('should handle missing secret parameter', async () => {
+        const result = await cliWithEnv(['aws'], getLocalStackEnv());
+
+        expect(result.code).toBe(1);
+        expect(result.stderr).toContain('required option');
+      });
+    });
+  });
+});

package/__e2e__/setup.ts

@@ -0,0 +1,58 @@
+// E2E Test Setup
+// This file runs before all e2e tests
+
+import { LocalStackHelper, checkAwslocalInstalled } from './utils/test-utils';
+import { debugLog, debugError } from './utils/debug-logger';
+
+// Increase timeout for e2e tests
+jest.setTimeout(30000);
+
+// Global setup for e2e tests
+beforeAll(async () => {
+  debugLog('Setting up E2E test environment...');
+
+  // Check if awslocal is installed
+  await checkAwslocalInstalled();
+
+  // Check if LocalStack is available
+  const localStack = new LocalStackHelper();
+  try {
+    await localStack.waitForLocalStack();
+    debugLog('LocalStack is ready for E2E tests');
+  } catch (error) {
+    debugError(
+      'LocalStack is not available, some tests may fail:',
+      error.message
+    );
+    process.exit(1);
+  }
+});
+
+// Global cleanup
+afterAll(async () => {
+  debugLog('Cleaning up E2E test environment...');
+});
+
+// Suppress console.log during tests unless DEBUG is set
+// But always show console.error and console.warn for debugging
+const originalConsoleLog = console.log;
+const originalConsoleInfo = console.info;
+const originalConsoleDebug = console.debug;
+
+beforeEach(() => {
+  if (!process.env.DEBUG) {
+    console.log = jest.fn();
+    console.info = jest.fn();
+    console.debug = jest.fn();
+    // Keep console.error and console.warn enabled for debugging
+  }
+});
+
+afterEach(() => {
+  if (!process.env.DEBUG) {
+    console.log = originalConsoleLog;
+    console.info = originalConsoleInfo;
+    console.debug = originalConsoleDebug;
+    // console.error and console.warn are already enabled
+  }
+});

package/__e2e__/utils/debug-logger.ts

@@ -0,0 +1,45 @@
+/**
+ * Debug logging utility for e2e tests
+ * Only outputs logs when DEBUG environment variable is set
+ */
+
+export class DebugLogger {
+  private static isDebugEnabled(): boolean {
+    return process.env.DEBUG === 'true' || process.env.DEBUG === '1';
+  }
+
+  static log(message: string, ...args: any[]): void {
+    if (DebugLogger.isDebugEnabled()) {
+      console.log(message, ...args);
+    }
+  }
+
+  static error(message: string, ...args: any[]): void {
+    // Always show errors for debugging
+    console.error(message, ...args);
+  }
+
+  static warn(message: string, ...args: any[]): void {
+    // Always show warnings for debugging
+    console.warn(message, ...args);
+  }
+
+  static info(message: string, ...args: any[]): void {
+    if (DebugLogger.isDebugEnabled()) {
+      console.info(message, ...args);
+    }
+  }
+
+  static debug(message: string, ...args: any[]): void {
+    if (DebugLogger.isDebugEnabled()) {
+      console.debug(message, ...args);
+    }
+  }
+}
+
+// Export convenience functions
+export const debugLog = DebugLogger.log;
+export const debugError = DebugLogger.error;
+export const debugWarn = DebugLogger.warn;
+export const debugInfo = DebugLogger.info;
+export const debugDebug = DebugLogger.debug;