test: add comprehensive E2E test suite for CLI wrapper

.github/workflows/e2e.yml

@@ -0,0 +1,40 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  e2e-tests:
+    name: E2E Tests (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ['18', '20', '22']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build project
+        run: pnpm build
+
+      - name: Run E2E tests
+        run: pnpm test:e2e

package.json

@@ -38,14 +38,17 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest --watch",
-    "test:coverage": "vitest run --coverage",
+    "test": "vitest run --config vitest.config.ts --dir tests/unit",
+    "test:unit": "vitest run --config vitest.config.ts --dir tests/unit",
+    "test:e2e": "vitest run --config vitest.config.e2e.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts --dir tests/unit",
+    "test:coverage": "vitest run --coverage --config vitest.config.ts --dir tests/unit",
+    "test:all": "npm run test:unit && npm run test:e2e",
     "lint": "eslint src --ext .ts",
     "lint:fix": "eslint src --ext .ts --fix",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build && npm test",
+    "prepublishOnly": "npm run clean && npm run build && npm run test:unit",
     "start": "node bin/capiscio.js"
   },
   "dependencies": {

tests/README.md

@@ -0,0 +1,116 @@
+# Tests for capiscio-node CLI
+
+This directory contains unit and E2E tests for the `capiscio` CLI wrapper.
+
+## Directory Structure
+
+```
+tests/
+├── unit/              # Unit tests with mocks (no server required)
+│   └── cli.test.ts
+└── e2e/               # E2E tests (offline mode, no server required)
+    ├── fixtures/      # Test data files
+    │   ├── valid-agent-card.json
+    │   ├── invalid-agent-card.json
+    │   └── malformed.json
+    ├── validate.e2e.test.ts  # Validation command tests
+    └── badge.e2e.test.ts     # Badge issuance/verification tests
+```
+
+## Running Tests
+
+### Run All Tests
+
+```bash
+pnpm test              # Unit tests only (default)
+pnpm test:all          # Both unit and E2E tests
+```
+
+### Run Only Unit Tests
+
+```bash
+pnpm test:unit
+```
+
+### Run Only E2E Tests
+
+```bash
+pnpm test:e2e
+```
+
+### Run with Watch Mode
+
+```bash
+pnpm test:watch
+```
+
+### Run with Coverage
+
+```bash
+pnpm test:coverage
+```
+
+## E2E Test Design
+
+The E2E tests are designed to run **offline** without requiring a server:
+
+- **Validate tests**: Use `--schema-only` flag for local schema validation
+- **Badge tests**: Use `--self-sign` for issuance and `--accept-self-signed --offline` for verification
+
+This approach allows E2E tests to run in CI without complex server infrastructure.
+
+## Test Coverage
+
+### Validate Command (`validate.e2e.test.ts`)
+
+- ✅ Valid local agent card file (schema-only mode)
+- ✅ Invalid local agent card file
+- ✅ Malformed JSON file
+- ✅ Nonexistent file
+- ✅ JSON output format
+- ✅ Help command
+
+### Badge Commands (`badge.e2e.test.ts`)
+
+- ✅ Issue self-signed badge
+- ✅ Issue badge with custom expiration
+- ✅ Issue badge with audience restriction
+- ✅ Verify self-signed badge (offline)
+- ✅ Verify invalid token (error handling)
+- ✅ Help commands (badge, issue, verify)
+
+## CI/CD Integration
+
+The E2E tests run in GitHub Actions without server dependencies:
+
+```yaml
+# See .github/workflows/e2e.yml
+- name: Run E2E tests
+  run: pnpm test:e2e
+```
+
+## Notes
+
+- **Offline Mode**: All E2E tests run offline without server dependencies
+- **Timeouts**: Tests have 15-second timeouts to prevent hanging
+- **Download Messages**: On first run, the CLI may download the capiscio-core binary; tests handle this gracefully
+
+## Troubleshooting
+
+### TypeScript Build Errors
+
+Ensure the project is built before running E2E tests:
+
+```bash
+pnpm build
+pnpm test:e2e
+```
+
+### Path Issues
+
+Ensure you're running tests from the project root:
+
+```bash
+cd /path/to/capiscio-node
+pnpm test:e2e
+```

tests/e2e/badge.e2e.test.ts

@@ -0,0 +1,114 @@
+/**
+ * E2E tests for capiscio badge commands.
+ * 
+ * Tests badge issuance and verification commands against the CLI.
+ * These tests focus on the CLI interface itself, not the server.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { runCapiscio, extractToken } from './helpers';
+
+describe('badge commands', () => {
+  describe('badge issue', () => {
+    it('should issue a self-signed badge', async () => {
+      const result = await runCapiscio([
+        'badge', 'issue', '--self-sign', '--domain', 'test.example.com'
+      ]);
+
+      // Self-signed badge issuance should succeed
+      expect(result.exitCode).toBe(0);
+
+      // Output should contain a JWT token (has dots for header.payload.signature)
+      // Get last line in case there are download messages
+      const token = extractToken(result.stdout);
+      expect(token.split('.').length).toBe(3); // JWT format
+    }, 15000);
+
+    it('should issue badge with custom expiration', async () => {
+      const result = await runCapiscio([
+        'badge', 'issue', '--self-sign', '--exp', '10m'
+      ]);
+
+      expect(result.exitCode).toBe(0);
+      const token = extractToken(result.stdout);
+      expect(token.split('.').length).toBe(3);
+    }, 15000);
+
+    it('should issue badge with audience restriction', async () => {
+      const result = await runCapiscio([
+        'badge', 'issue', '--self-sign', '--aud', 'https://api.example.com'
+      ]);
+
+      expect(result.exitCode).toBe(0);
+      const token = extractToken(result.stdout);
+      expect(token.split('.').length).toBe(3);
+    }, 15000);
+
+    it('should display help for badge issue', async () => {
+      const result = await runCapiscio(['badge', 'issue', '--help']);
+
+      expect(result.exitCode).toBe(0);
+      const helpText = result.stdout.toLowerCase();
+      expect(helpText.includes('issue')).toBe(true);
+      expect(helpText.includes('self-sign') || helpText.includes('level')).toBe(true);
+    }, 15000);
+  });
+
+  describe('badge verify', () => {
+    it('should verify a self-signed badge', async () => {
+      // First issue a badge
+      const issueResult = await runCapiscio([
+        'badge', 'issue', '--self-sign', '--domain', 'test.example.com'
+      ]);
+      expect(issueResult.exitCode).toBe(0);
+      const token = extractToken(issueResult.stdout);
+
+      // Then verify it with --accept-self-signed
+      const verifyResult = await runCapiscio([
+        'badge', 'verify', token, '--accept-self-signed', '--offline'
+      ]);
+
+      expect(verifyResult.exitCode).toBe(0);
+      const output = verifyResult.stdout.toLowerCase();
+      expect(
+        output.includes('valid') || output.includes('verified') || output.includes('ok')
+      ).toBe(true);
+    }, 15000);
+
+    it('should fail for invalid token', async () => {
+      const invalidToken = 'invalid.jwt.token';
+      const result = await runCapiscio(['badge', 'verify', invalidToken, '--accept-self-signed']);
+
+      expect(result.exitCode).not.toBe(0);
+      const errorOutput = (result.stderr + result.stdout).toLowerCase();
+      expect(
+        errorOutput.includes('invalid') ||
+        errorOutput.includes('verify') ||
+        errorOutput.includes('failed') ||
+        errorOutput.includes('malformed') ||
+        errorOutput.includes('error')
+      ).toBe(true);
+    }, 15000);
+
+    it('should display help for badge verify', async () => {
+      const result = await runCapiscio(['badge', 'verify', '--help']);
+
+      expect(result.exitCode).toBe(0);
+      const helpText = result.stdout.toLowerCase();
+      expect(helpText.includes('verify') || helpText.includes('token')).toBe(true);
+    }, 15000);
+  });
+
+  describe('badge help', () => {
+    it('should display help for badge command', async () => {
+      const result = await runCapiscio(['badge', '--help']);
+
+      expect(result.exitCode).toBe(0);
+      const helpText = result.stdout.toLowerCase();
+      expect(helpText.includes('badge')).toBe(true);
+      expect(
+        helpText.includes('issue') || helpText.includes('verify') || helpText.includes('usage')
+      ).toBe(true);
+    }, 15000);
+  });
+});

tests/e2e/fixtures/invalid-agent-card.json

@@ -0,0 +1,9 @@
+{
+  "version": "1.0",
+  "did": "invalid-did-format",
+  "name": "Invalid Agent",
+  "publicKey": {
+    "kty": "WRONG",
+    "x": "invalid-key-data"
+  }
+}

tests/e2e/fixtures/malformed.txt

@@ -0,0 +1,5 @@
+{
+  "version": "1.0",
+  "did": "did:web:example.com",
+  "trailing": "comma",
+}

tests/e2e/fixtures/valid-agent-card.json

@@ -0,0 +1,26 @@
+{
+  "protocolVersion": "1.3.0",
+  "version": "1.0.0",
+  "name": "Test Agent",
+  "description": "A test agent for E2E validation tests",
+  "url": "https://example.com/.well-known/agent.json",
+  "capabilities": {
+    "streaming": false,
+    "pushNotifications": false
+  },
+  "skills": [
+    {
+      "id": "test-skill",
+      "name": "Test Skill",
+      "description": "A skill for testing",
+      "tags": ["test", "validation"]
+    }
+  ],
+  "provider": {
+    "organization": "Test Organization",
+    "url": "https://example.com"
+  },
+  "authentication": {
+    "schemes": ["none"]
+  }
+}

tests/e2e/helpers.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared test helpers for E2E tests.
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+
+const execAsync = promisify(exec);
+
+export const CLI_PATH = path.join(__dirname, '../../bin/capiscio.js');
+export const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+
+/**
+ * Run the capiscio CLI with the given arguments.
+ */
+export async function runCapiscio(
+  args: string[],
+  env?: Record<string, string>
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  try {
+    const { stdout, stderr } = await execAsync(`node "${CLI_PATH}" ${args.join(' ')}`, {
+      env: { ...process.env, ...env },
+    });
+    return { stdout, stderr, exitCode: 0 };
+  } catch (error: unknown) {
+    const err = error as { stdout?: string; stderr?: string; code?: number };
+    return {
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      exitCode: err.code || 1,
+    };
+  }
+}
+
+/**
+ * Extract token from CLI output - handles potential download messages on first run.
+ * The CLI may print download progress before the actual output.
+ */
+export function extractToken(stdout: string): string {
+  const lines = stdout.trim().split('\n');
+  return lines[lines.length - 1].trim();
+}