@cakemail-org/cakemail-cli 1.5.0 → 2.0.0

package/tests/README.md

@@ -0,0 +1,244 @@
+# Cakemail CLI Test Suite
+
+## Overview
+
+This is a **hybrid test suite** combining fast mocked tests with real API integration tests, providing comprehensive coverage of all 136 commands.
+
+## Test Strategy: Hybrid Approach ⭐
+
+We use **two complementary testing strategies**:
+
+### 1. **Mocked E2E Tests** (Fast - 90% of tests)
+- ✅ Execute real CLI binary
+- ✅ Mock API responses with nock
+- ✅ Test command logic, output formatting, error handling
+- ✅ Run in ~seconds (no network calls)
+- 🎯 Use for: Unit-style testing of all commands
+
+### 2. **Real API Integration Tests** (Slow - 10% of tests)
+- ✅ Make actual HTTP requests to Cakemail API
+- ✅ Test real authentication flow
+- ✅ Test actual data creation/modification
+- ✅ Test full command lifecycle
+- 🎯 Use for: Critical paths and end-to-end validation
+
+## Current Status
+
+✅ **Phase 1 Complete: Hybrid Test Infrastructure**
+- Test framework setup (Vitest)
+- Mocked E2E tests with nock
+- Real API integration tests
+- Helper utilities (CLI runner, API mocking)
+- Environment configuration (.env.test)
+- First 26 tests (20 mocked + 6 integration)
+
+### Test Results
+- **Mocked E2E Tests**: 20 tests created
+- **Integration Tests**: 6 tests created (skipped without credentials)
+- **Total Coverage**: Campaigns command group (both mocked and real API)
+
+## Setup
+
+### For Mocked Tests (Fast)
+No setup required! Just run:
+```bash
+npm test
+```
+
+### For Integration Tests (Real API)
+1. Copy environment template:
+   ```bash
+   cp .env.test.example .env.test
+   ```
+
+2. Edit `.env.test` and add your test credentials:
+   ```bash
+   CAKEMAIL_TEST_EMAIL=your-test@example.com
+   CAKEMAIL_TEST_PASSWORD=your-test-password
+   ```
+
+3. Run integration tests:
+   ```bash
+   npm run test:integration
+   ```
+
+⚠️ **Important**: Use a TEST account, not production! Integration tests create/modify/delete data.
+
+## Test Architecture
+
+```
+tests/
+├── e2e/                    # End-to-end CLI tests (20/136 commands)
+│   └── campaigns.test.ts   # ✅ Created (20 tests)
+├── integration/            # API integration tests
+├── unit/                   # Unit tests for utilities
+├── helpers/
+│   ├── cli-runner.ts       # ✅ CLI execution helper
+│   └── mock-api.ts         # ✅ API mocking utilities
+└── fixtures/               # ✅ Test data
+```
+
+## Running Tests
+
+### Mocked Tests (Fast)
+```bash
+# Run all mocked E2E tests
+npm run test:e2e
+
+# Run specific test file
+npx vitest run tests/e2e/campaigns.test.ts
+
+# Watch mode (during development)
+npm run test:watch
+```
+
+### Integration Tests (Real API)
+```bash
+# Run all integration tests
+npm run test:integration
+
+# Run specific integration test
+npx vitest run tests/integration/campaigns-real-api.test.ts
+```
+
+### Combined
+```bash
+# Run ALL tests (mocked + integration)
+npm test
+
+# Run with coverage report
+npm run test:coverage
+
+# CI/CD mode (with JUnit reporter)
+npm run test:ci
+```
+
+## Test Coverage Goals
+
+| Category | Commands | Tests | Status |
+|----------|----------|-------|--------|
+| Campaigns | 15 | 20 | 🟡 In Progress |
+| Lists | 10 | 0 | ⚪ Pending |
+| Contacts | 12 | 0 | ⚪ Pending |
+| Templates | 8 | 0 | ⚪ Pending |
+| Senders | 7 | 0 | ⚪ Pending |
+| Webhooks | 5 | 0 | ⚪ Pending |
+| Tags | 5 | 0 | ⚪ Pending |
+| Interests | 7 | 0 | ⚪ Pending |
+| Transactional Templates | 12 | 0 | ⚪ Pending |
+| Logs | 3 | 0 | ⚪ Pending |
+| Reports | 12 | 0 | ⚪ Pending |
+| Segments | 6 | 0 | ⚪ Pending |
+| Attributes | 4 | 0 | ⚪ Pending |
+| Suppressed | 7 | 0 | ⚪ Pending |
+| Account | 5 | 0 | ⚪ Pending |
+| Emails | 8 | 0 | ⚪ Pending |
+| Config | 6 | 0 | ⚪ Pending |
+| **Total** | **136** | **20** | **15%** |
+
+## Next Steps
+
+### Immediate (Fix Failing Tests)
+1. ✅ Install test dependencies
+2. ✅ Create test infrastructure
+3. ✅ Write first 20 E2E tests
+4. 🔄 Fix nock/SDK integration issue
+5. ⚪ Get all 20 campaigns tests passing
+
+### Phase 2: Core Commands (Weeks 3-6)
+- Lists commands (10 tests)
+- Contacts commands (12 tests)
+- Templates commands (8 tests)
+- Senders commands (7 tests)
+- Webhooks commands (5 tests)
+
+### Phase 3: New Features (Weeks 7-8)
+- Tags commands (5 tests)
+- Interests commands (7 tests)
+- Transactional templates (12 tests)
+- Logs commands (3 tests)
+
+### Phase 4: Advanced (Weeks 9-10)
+- Reports & analytics (12 tests)
+- Segments (6 tests)
+- Attributes (4 tests)
+- Profile system (15 tests)
+- Interactive features (20 tests)
+
+## Writing Tests
+
+### Example Test
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { runCLISuccess, parseJSONOutput } from '../helpers/cli-runner';
+import { mockCampaignsList } from '../helpers/mock-api';
+
+describe('campaigns list', () => {
+  it('should list campaigns in JSON format', async () => {
+    mockCampaignsList([
+      { id: 1, name: 'Test Campaign', status: 'draft' }
+    ]);
+
+    const result = await runCLISuccess(['campaigns', 'list']);
+
+    expect(result.exitCode).toBe(0);
+    const output = parseJSONOutput(result.stdout);
+    expect(output.data).toHaveLength(1);
+  });
+});
+```
+
+### Testing Patterns
+
+1. **Command Execution**: Test that command runs without error
+2. **Output Formats**: Test JSON, table, and compact formats
+3. **Options**: Test all flags and parameters
+4. **Error Handling**: Test API errors (401, 404, 500, etc.)
+5. **Profile Support**: Test with developer/marketer/balanced profiles
+6. **Interactive Features**: Test prompts and confirmations
+
+## Troubleshooting
+
+### "Cannot find module" errors
+```bash
+npm run build
+```
+
+### "HTTP request not mocked" errors
+Check that mock API is properly set up in test setup.
+
+### Tests timing out
+Increase timeout in vitest.config.ts:
+```typescript
+testTimeout: 60000 // 60 seconds
+```
+
+## Contributing
+
+When adding new commands:
+1. Create corresponding test file in `tests/e2e/`
+2. Add at least 5 tests per command:
+   - Basic execution
+   - Output formats (3 tests)
+   - Error handling
+3. Update coverage table in this README
+4. Ensure all tests pass before committing
+
+## CI/CD Integration
+
+Tests run automatically on:
+- Every pull request
+- Every commit to main
+- Scheduled nightly runs
+
+Coverage reports are published to:
+- Pull request comments
+- GitHub Actions artifacts
+- Coverage dashboard (TBD)
+
+## Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [Testing Best Practices](https://testingjavascript.com/)
+- [CLI Testing Guide](https://github.com/testing-library/cli-testing-library)

package/tests/fixtures/api-responses/campaigns.json

@@ -0,0 +1,34 @@
+{
+  "singleCampaign": {
+    "id": 123,
+    "name": "Test Campaign",
+    "status": "draft",
+    "list_id": 1,
+    "sender_id": 1,
+    "subject": "Test Subject",
+    "html": "<h1>Test</h1>",
+    "created_on": "2025-01-01T00:00:00Z",
+    "updated_on": "2025-01-01T00:00:00Z"
+  },
+  "campaignsList": {
+    "data": [
+      {
+        "id": 1,
+        "name": "Campaign 1",
+        "status": "delivered",
+        "list_id": 1,
+        "sender_id": 1,
+        "created_on": "2025-01-01T00:00:00Z"
+      },
+      {
+        "id": 2,
+        "name": "Campaign 2",
+        "status": "draft",
+        "list_id": 1,
+        "sender_id": 1,
+        "created_on": "2025-01-02T00:00:00Z"
+      }
+    ],
+    "count": 2
+  }
+}

package/tests/fixtures/test-config.json

@@ -0,0 +1,13 @@
+{
+  "testCredentials": {
+    "accessToken": "test-access-token",
+    "email": "test@example.com",
+    "password": "test-password"
+  },
+  "testAccount": {
+    "id": 1,
+    "email": "test@example.com",
+    "name": "Test Account"
+  },
+  "apiBase": "https://api.cakemail.dev"
+}

package/tests/helpers/cli-runner.ts

@@ -0,0 +1,128 @@
+import { execa, type ExecaReturnValue } from 'execa';
+import stripAnsi from 'strip-ansi';
+import { join } from 'path';
+
+export interface CLIResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  rawStdout: string;
+  rawStderr: string;
+}
+
+export interface CLIOptions {
+  stdin?: string;
+  env?: Record<string, string>;
+  cwd?: string;
+  timeout?: number;
+}
+
+/**
+ * Execute the CLI with given arguments
+ */
+export async function runCLI(
+  args: string[],
+  options: CLIOptions = {}
+): Promise<CLIResult> {
+  const cliPath = join(process.cwd(), 'dist', 'cli.js');
+
+  const env = {
+    // Inherit process environment (for credentials)
+    ...process.env,
+    // Default test environment
+    CAKEMAIL_BATCH_MODE: 'true',
+    FORCE_COLOR: '0', // Disable colors for easier testing
+    // Override with custom env
+    ...options.env
+  };
+
+  try {
+    const result: ExecaReturnValue = await execa('node', [cliPath, ...args], {
+      env,
+      input: options.stdin,
+      cwd: options.cwd || process.cwd(),
+      timeout: options.timeout || 30000,
+      reject: false, // Don't throw on non-zero exit
+      all: true
+    });
+
+    return {
+      exitCode: result.exitCode,
+      stdout: stripAnsi(result.stdout),
+      stderr: stripAnsi(result.stderr),
+      rawStdout: result.stdout,
+      rawStderr: result.stderr
+    };
+  } catch (error: any) {
+    // Handle execution errors (timeout, etc.)
+    return {
+      exitCode: error.exitCode || 1,
+      stdout: error.stdout ? stripAnsi(error.stdout) : '',
+      stderr: error.stderr ? stripAnsi(error.stderr) : error.message,
+      rawStdout: error.stdout || '',
+      rawStderr: error.stderr || error.message
+    };
+  }
+}
+
+/**
+ * Run CLI and expect success
+ */
+export async function runCLISuccess(
+  args: string[],
+  options: CLIOptions = {}
+): Promise<CLIResult> {
+  const result = await runCLI(args, options);
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `CLI command failed with exit code ${result.exitCode}\n` +
+      `Command: cakemail ${args.join(' ')}\n` +
+      `Stderr: ${result.stderr}`
+    );
+  }
+  return result;
+}
+
+/**
+ * Run CLI and expect failure
+ */
+export async function runCLIFailure(
+  args: string[],
+  options: CLIOptions = {}
+): Promise<CLIResult> {
+  const result = await runCLI(args, options);
+  if (result.exitCode === 0) {
+    throw new Error(
+      `CLI command succeeded when failure was expected\n` +
+      `Command: cakemail ${args.join(' ')}\n` +
+      `Stdout: ${result.stdout}`
+    );
+  }
+  return result;
+}
+
+/**
+ * Parse JSON output from CLI
+ */
+export function parseJSONOutput(stdout: string): any {
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(`Failed to parse CLI output as JSON:\n${stdout}`);
+  }
+}
+
+/**
+ * Setup test environment
+ */
+export function setupTestEnv(): void {
+  // Build the CLI before running tests
+  // This should be done once before all tests
+}
+
+/**
+ * Cleanup test environment
+ */
+export function cleanupTestEnv(): void {
+  // Clean up any test artifacts
+}

package/tests/helpers/mock-server.ts

@@ -0,0 +1,301 @@
+import express, { Express } from 'express';
+import { Server } from 'http';
+import { AddressInfo } from 'net';
+
+/**
+ * Create a mock Cakemail API server for testing
+ *
+ * This is a REAL HTTP server that runs on localhost.
+ * The CLI subprocess can make real HTTP requests to it.
+ */
+export function createMockAPI(): Express {
+  const app = express();
+  app.use(express.json());
+
+  // OAuth2 Authentication
+  app.post('/token', (req, res) => {
+    const { username, password } = req.body;
+
+    if (username && password) {
+      res.json({
+        access_token: 'mock-access-token',
+        token_type: 'Bearer',
+        expires_in: 3600,
+        refresh_token: 'mock-refresh-token',
+        scope: 'read write'
+      });
+    } else {
+      res.status(401).json({
+        error: 'invalid_grant',
+        error_description: 'Invalid credentials'
+      });
+    }
+  });
+
+  // Account endpoints (for OAuth flow)
+  app.get('/accounts', (req, res) => {
+    res.json({
+      data: [
+        { id: 1, name: 'Test Account', email: 'test@example.com', is_master: true }
+      ],
+      count: 1
+    });
+  });
+
+  app.get('/account', (req, res) => {
+    res.json({
+      id: 1,
+      name: 'Test Account',
+      email: 'test@example.com',
+      is_master: true
+    });
+  });
+
+  // Campaigns
+  app.get('/campaigns', (req, res) => {
+    res.json({
+      data: [
+        { id: 1, name: 'Test Campaign 1', status: 'draft', created_on: '2025-01-01' },
+        { id: 2, name: 'Test Campaign 2', status: 'sent', created_on: '2025-01-02' }
+      ],
+      count: 2,
+      _links: {}
+    });
+  });
+
+  app.get('/campaigns/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    if (id === 999) {
+      return res.status(404).json({ error: 'Campaign not found' });
+    }
+    res.json({
+      id,
+      name: `Campaign ${id}`,
+      status: 'draft',
+      list_id: 1,
+      sender_id: 1,
+      created_on: '2025-01-01T00:00:00Z'
+    });
+  });
+
+  app.post('/campaigns', (req, res) => {
+    const { name, list_id, sender_id } = req.body;
+    if (!name) {
+      return res.status(422).json({ error: 'Name is required' });
+    }
+    res.status(201).json({
+      id: 123,
+      name,
+      list_id,
+      sender_id,
+      status: 'draft',
+      created_on: new Date().toISOString()
+    });
+  });
+
+  app.patch('/campaigns/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({
+      id,
+      ...req.body,
+      updated_on: new Date().toISOString()
+    });
+  });
+
+  app.delete('/campaigns/:id', (req, res) => {
+    res.status(204).send();
+  });
+
+  // Lists
+  app.get('/lists', (req, res) => {
+    res.json({
+      data: [
+        { id: 1, name: 'Main List', status: 'active', active_contacts: 100 },
+        { id: 2, name: 'VIP List', status: 'active', active_contacts: 25 }
+      ],
+      count: 2
+    });
+  });
+
+  app.get('/lists/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({
+      id,
+      name: `List ${id}`,
+      status: 'active',
+      active_contacts: 100,
+      created_on: '2025-01-01T00:00:00Z'
+    });
+  });
+
+  app.post('/lists', (req, res) => {
+    const { name } = req.body;
+    res.status(201).json({
+      id: 456,
+      name,
+      status: 'active',
+      created_on: new Date().toISOString()
+    });
+  });
+
+  app.patch('/lists/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({ id, ...req.body });
+  });
+
+  app.delete('/lists/:id', (req, res) => {
+    res.status(204).send();
+  });
+
+  // Contacts
+  app.get('/contacts', (req, res) => {
+    res.json({
+      data: [
+        { id: 1, email: 'user1@example.com', status: 'active' },
+        { id: 2, email: 'user2@example.com', status: 'active' }
+      ],
+      count: 2
+    });
+  });
+
+  app.get('/contacts/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({
+      id,
+      email: `user${id}@example.com`,
+      first_name: 'Test',
+      last_name: 'User',
+      status: 'active'
+    });
+  });
+
+  app.post('/contacts', (req, res) => {
+    const { email, list_ids } = req.body;
+    res.status(201).json({
+      id: 789,
+      email,
+      list_ids,
+      status: 'active',
+      created_on: new Date().toISOString()
+    });
+  });
+
+  app.patch('/contacts/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({ id, ...req.body });
+  });
+
+  app.delete('/contacts/:id', (req, res) => {
+    res.status(204).send();
+  });
+
+  // Senders
+  app.get('/senders', (req, res) => {
+    res.json({
+      data: [
+        { id: 1, name: 'Support', email: 'support@example.com', confirmed: true },
+        { id: 2, name: 'Marketing', email: 'marketing@example.com', confirmed: false }
+      ],
+      count: 2
+    });
+  });
+
+  app.get('/senders/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({
+      id,
+      name: `Sender ${id}`,
+      email: `sender${id}@example.com`,
+      confirmed: true
+    });
+  });
+
+  app.post('/senders', (req, res) => {
+    const { name, email } = req.body;
+    res.status(201).json({
+      id: 999,
+      name,
+      email,
+      confirmed: false,
+      created_on: new Date().toISOString()
+    });
+  });
+
+  app.patch('/senders/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({ id, ...req.body });
+  });
+
+  app.delete('/senders/:id', (req, res) => {
+    res.status(204).send();
+  });
+
+  // Templates
+  app.get('/templates', (req, res) => {
+    res.json({
+      data: [
+        { id: 1, name: 'Welcome Email', tags: ['onboarding'] },
+        { id: 2, name: 'Newsletter', tags: ['marketing'] }
+      ],
+      count: 2
+    });
+  });
+
+  app.get('/templates/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({
+      id,
+      name: `Template ${id}`,
+      html: '<h1>Hello</h1>',
+      text: 'Hello',
+      subject: 'Test Subject'
+    });
+  });
+
+  app.post('/templates', (req, res) => {
+    const { name } = req.body;
+    res.status(201).json({
+      id: 888,
+      name,
+      created_on: new Date().toISOString()
+    });
+  });
+
+  app.patch('/templates/:id', (req, res) => {
+    const id = parseInt(req.params.id);
+    res.json({ id, ...req.body });
+  });
+
+  app.delete('/templates/:id', (req, res) => {
+    res.status(204).send();
+  });
+
+  return app;
+}
+
+/**
+ * Start mock server on random available port
+ */
+export async function startMockServer(): Promise<{ server: Server; port: number; url: string }> {
+  const app = createMockAPI();
+
+  return new Promise((resolve) => {
+    const server = app.listen(0, () => {
+      const port = (server.address() as AddressInfo).port;
+      const url = `http://localhost:${port}`;
+      resolve({ server, port, url });
+    });
+  });
+}
+
+/**
+ * Stop mock server
+ */
+export async function stopMockServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}