serverless-ircd 0.9.0 → 0.11.0

package/scripts/__tests__/deploy-web-aws.test.ts

@@ -0,0 +1,491 @@
+/**
+ * Unit tests for `scripts/deploy-web-aws.mjs` — the AWS web-client deploy
+ * pipeline helper.
+ *
+ * The script performs the post-CDK two-phase deploy:
+ *   1. `aws cloudformation describe-stacks` reads the deployed stack's
+ *      outputs (ConnectUrl, WebsiteBucketName, WebsiteDistributionId).
+ *   2. `pnpm --filter @serverless-ircd/web run build:prod-aws -- --api-url <url>`
+ *      bakes the SPA with the real wss URL from the stack output.
+ *   3. `aws s3 sync apps/web/dist s3://<bucket> --delete` uploads the build.
+ *   4. `aws cloudfront create-invalidation --distribution-id <id> --paths /*`
+ *      busts the edge cache so the new build is served immediately.
+ *
+ * The deploy function takes an injectable `runner` ({ aws, pnpm }) so these
+ * tests stub the AWS CLI and pnpm child-process spawns — no real AWS
+ * credentials, no live stack, no SPA build. The tests assert the call
+ * SEQUENCE, the OUTPUT SUBSTITUTION (the stack-output wss URL is the only
+ * value that reaches `--api-url`), the missing-output guard, and the
+ * `s3 sync --delete` invocation shape (whose etag-based no-op-on-redeploy
+ * is the AWS CLI's behaviour, not ours).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { describe, expect, it, vi } from 'vitest';
+import { deployWebAws, makeDefaultRunner, parseStackOutputs, runCli } from '../deploy-web-aws.mjs';
+
+/**
+ * Builds an in-memory stub runner that records every call in order and
+ * returns canned responses keyed by the leading AWS / pnpm subcommand.
+ *
+ * `describeStacksOutputs` is returned as the JSON string the real CLI
+ * emits with `--output json` (an array of `{ OutputKey, OutputValue }`).
+ */
+function makeStubRunner({
+  outputs = DEFAULT_OUTPUTS,
+  awsResponses = {},
+}: {
+  outputs?: Array<{ OutputKey: string; OutputValue: string }>;
+  awsResponses?: Record<string, string>;
+} = {}) {
+  const calls: Array<{ kind: 'aws' | 'pnpm'; args: string[] }> = [];
+  const describeJson = JSON.stringify(outputs);
+  const runner = {
+    aws(args: string[]): { stdout: string; stderr: string; status: number } {
+      calls.push({ kind: 'aws', args: [...args] });
+      // The first AWS call is always `cloudformation describe-stacks`. Subsequent
+      // ones (`s3 sync`, `cloudfront create-invalidation`) are dispatched by
+      // their leading service token so tests can override the canned reply.
+      const subcommand = args[0] === 'cloudformation' && args[1] === 'describe-stacks';
+      if (subcommand) {
+        return { stdout: describeJson, stderr: '', status: 0 };
+      }
+      const service = args[0] ?? '';
+      const canned = awsResponses[service] ?? '';
+      return { stdout: canned, stderr: '', status: 0 };
+    },
+    pnpm(args: string[]): { stdout: string; stderr: string; status: number } {
+      calls.push({ kind: 'pnpm', args: [...args] });
+      return { stdout: '', stderr: '', status: 0 };
+    },
+  };
+  return { runner, calls };
+}
+
+const DEFAULT_OUTPUTS = [
+  { OutputKey: 'ConnectUrl', OutputValue: 'wss://abc123.execute-api.us-east-1.amazonaws.com/prod' },
+  { OutputKey: 'WebsiteBucketName', OutputValue: 'irc-aws-stack-bucket-1a2b3c' },
+  { OutputKey: 'WebsiteDistributionId', OutputValue: 'E1A2B3C4D5E6F7' },
+];
+
+// ============================================================================
+// parseStackOutputs — JSON → lookup map
+// ============================================================================
+
+describe('parseStackOutputs', () => {
+  it('returns a key→value map for a CLI-shaped Outputs array', () => {
+    const json = JSON.stringify([
+      { OutputKey: 'ConnectUrl', OutputValue: 'wss://example' },
+      { OutputKey: 'WebsiteBucketName', OutputValue: 'bucket-1' },
+    ]);
+    expect(parseStackOutputs(json)).toEqual({
+      ConnectUrl: 'wss://example',
+      WebsiteBucketName: 'bucket-1',
+    });
+  });
+
+  it('returns an empty object when describe-stacks yields an empty Outputs array', () => {
+    expect(parseStackOutputs('[]')).toEqual({});
+  });
+
+  it('returns an empty object when the parsed JSON is not an array (e.g. an object)', () => {
+    expect(parseStackOutputs('{"OutputKey":"ConnectUrl"}')).toEqual({});
+    expect(parseStackOutputs('null')).toEqual({});
+    expect(parseStackOutputs('"string"')).toEqual({});
+  });
+
+  it('skips entries missing OutputKey or OutputValue', () => {
+    const json = JSON.stringify([
+      { OutputKey: 'ConnectUrl', OutputValue: 'wss://x' },
+      { OutputKey: 'NoValue' },
+      { OutputValue: 'orphan' },
+      { neither: 'here' },
+      null,
+    ]);
+    expect(parseStackOutputs(json)).toEqual({ ConnectUrl: 'wss://x' });
+  });
+
+  it('throws on a non-JSON body (surfaces the underlying parse error)', () => {
+    expect(() => parseStackOutputs('not-json')).toThrowError();
+  });
+});
+
+// ============================================================================
+// deployWebAws — happy path sequence
+// ============================================================================
+
+describe('deployWebAws — sequence (describe → build → s3 sync → invalidate)', () => {
+  it('invokes the AWS CLI and pnpm in the exact required order', async () => {
+    const { runner, calls } = makeStubRunner();
+    await deployWebAws({ runner });
+
+    // Exactly four calls: one describe-stacks, one build, one s3 sync,
+    // one invalidation. No extra round-trips.
+    expect(calls).toHaveLength(4);
+    expect(calls.map((c) => c.kind)).toEqual(['aws', 'pnpm', 'aws', 'aws']);
+  });
+
+  it('first call describes the IrcAwsStack (no env suffix)', async () => {
+    const { runner, calls } = makeStubRunner();
+    await deployWebAws({ runner });
+    const describeCall = calls[0];
+    expect(describeCall?.kind).toBe('aws');
+    expect(describeCall?.args).toContain('cloudformation');
+    expect(describeCall?.args).toContain('describe-stacks');
+    expect(describeCall?.args).toContain('--stack-name');
+    expect(describeCall?.args).toContain('IrcAwsStack');
+  });
+
+  it('second call builds the SPA with --env prod-aws AND --api-url from the stack output', async () => {
+    const { runner, calls } = makeStubRunner();
+    await deployWebAws({ runner });
+    const buildCall = calls[1];
+    expect(buildCall?.kind).toBe('pnpm');
+    expect(buildCall?.args).toEqual(
+      expect.arrayContaining([
+        '--filter',
+        '@serverless-ircd/web',
+        'run',
+        'build:prod-aws',
+        '--',
+        '--env',
+        'prod-aws',
+      ]),
+    );
+    // The --api-url value MUST be the ConnectUrl stack output verbatim —
+    // no hardcoded URLs anywhere in the pipeline. The template
+    // {{API_ID}}.{{REGION}}.{{STAGE}} placeholders are substituted by
+    // the build script from this single value.
+    const apiUrlIdx = buildCall?.args.indexOf('--api-url') ?? -1;
+    expect(apiUrlIdx, 'expected --api-url to appear in the build argv').toBeGreaterThan(-1);
+    const apiUrlValue = buildCall?.args[apiUrlIdx + 1];
+    expect(apiUrlValue).toBe('wss://abc123.execute-api.us-east-1.amazonaws.com/prod');
+  });
+
+  it('third call runs `s3 sync apps/web/dist s3://<bucket> --delete` against the stack-output bucket', async () => {
+    const { runner, calls } = makeStubRunner();
+    await deployWebAws({ runner });
+    const syncCall = calls[2];
+    expect(syncCall?.kind).toBe('aws');
+    expect(syncCall?.args).toEqual(
+      expect.arrayContaining([
+        's3',
+        'sync',
+        'apps/web/dist',
+        's3://irc-aws-stack-bucket-1a2b3c',
+        '--delete',
+      ]),
+    );
+  });
+
+  it('fourth call invalidates the CloudFront distribution with --paths /*', async () => {
+    const { runner, calls } = makeStubRunner();
+    await deployWebAws({ runner });
+    const invCall = calls[3];
+    expect(invCall?.kind).toBe('aws');
+    expect(invCall?.args).toEqual(
+      expect.arrayContaining([
+        'cloudfront',
+        'create-invalidation',
+        '--distribution-id',
+        'E1A2B3C4D5E6F7',
+        '--paths',
+        '/*',
+      ]),
+    );
+  });
+});
+
+// ============================================================================
+// deployWebAws — output substitution (no hardcoded URLs)
+// ============================================================================
+
+describe('deployWebAws — output substitution', () => {
+  it("threads the deployed stack's ConnectUrl into --api-url (no hardcoded URLs)", async () => {
+    const { runner, calls } = makeStubRunner({
+      outputs: [
+        { OutputKey: 'ConnectUrl', OutputValue: 'wss://real-deployed-url.example/prod' },
+        { OutputKey: 'WebsiteBucketName', OutputValue: 'real-bucket' },
+        { OutputKey: 'WebsiteDistributionId', OutputValue: 'REALDISTID' },
+      ],
+    });
+    await deployWebAws({ runner });
+    const buildCall = calls[1];
+    const apiUrlIdx = buildCall?.args.indexOf('--api-url') ?? -1;
+    expect(buildCall?.args[apiUrlIdx + 1]).toBe('wss://real-deployed-url.example/prod');
+  });
+
+  it('rejects a templated URL value in the stack output (defence in depth)', async () => {
+    // If the stack output itself carries an unsubstituted placeholder the
+    // pipeline must fail loudly rather than shipping a broken SPA that
+    // dials `{{API_ID}}...` verbatim.
+    const { runner } = makeStubRunner({
+      outputs: [
+        {
+          OutputKey: 'ConnectUrl',
+          OutputValue: 'wss://{{API_ID}}.execute-api.{{REGION}}.amazonaws.com/{{STAGE}}',
+        },
+        { OutputKey: 'WebsiteBucketName', OutputValue: 'b' },
+        { OutputKey: 'WebsiteDistributionId', OutputValue: 'd' },
+      ],
+    });
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/ConnectUrl/u);
+  });
+});
+
+// ============================================================================
+// deployWebAws — missing-output guard
+// ============================================================================
+
+describe('deployWebAws — missing-output guard', () => {
+  it('throws (and the entrypoint exits non-zero) when ConnectUrl is absent', async () => {
+    const { runner } = makeStubRunner({
+      outputs: [
+        { OutputKey: 'WebsiteBucketName', OutputValue: 'b' },
+        { OutputKey: 'WebsiteDistributionId', OutputValue: 'd' },
+      ],
+    });
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/ConnectUrl/u);
+  });
+
+  it('throws when WebsiteBucketName is absent', async () => {
+    const { runner } = makeStubRunner({
+      outputs: [
+        { OutputKey: 'ConnectUrl', OutputValue: 'wss://x' },
+        { OutputKey: 'WebsiteDistributionId', OutputValue: 'd' },
+      ],
+    });
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/WebsiteBucketName/u);
+  });
+
+  it('throws when WebsiteDistributionId is absent', async () => {
+    const { runner } = makeStubRunner({
+      outputs: [
+        { OutputKey: 'ConnectUrl', OutputValue: 'wss://x' },
+        { OutputKey: 'WebsiteBucketName', OutputValue: 'b' },
+      ],
+    });
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/WebsiteDistributionId/u);
+  });
+
+  it('mentions the stack name in the error so the operator knows what to deploy', async () => {
+    const { runner } = makeStubRunner({ outputs: [] });
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/IrcAwsStack/u);
+  });
+
+  it('does NOT invoke pnpm build or any s3/cloudfront call when outputs are missing', async () => {
+    const { runner, calls } = makeStubRunner({
+      outputs: [{ OutputKey: 'ConnectUrl', OutputValue: 'wss://x' }],
+    });
+    await expect(deployWebAws({ runner })).rejects.toThrow();
+    // Only the describe-stacks call should have landed; no build / sync /
+    // invalidation may fire on a missing-output failure.
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.kind).toBe('aws');
+  });
+});
+
+// ============================================================================
+// deployWebAws — re-deploy no-op behaviour
+// ============================================================================
+
+describe('deployWebAws — re-deploy (s3 sync unchanged-skip)', () => {
+  // The AWS CLI's `s3 sync` compares etags and skips uploads of unchanged
+  // objects; that behaviour is the CLI's, not ours. What we CAN assert is
+  // that the script always invokes `s3 sync --delete` with the same
+  // arguments on every run — the CLI then decides what (if anything) to
+  // upload. The invalidation fires unconditionally because CloudFront has
+  // no equivalent unchanged-skip.
+  it('always invokes s3 sync with --delete (the CLI handles unchanged-skip via etags)', async () => {
+    const { runner, calls } = makeStubRunner();
+    await deployWebAws({ runner });
+    const syncCall = calls[2];
+    expect(syncCall?.args).toContain('--delete');
+    expect(syncCall?.args).toContain('s3://irc-aws-stack-bucket-1a2b3c');
+  });
+
+  it('always invokes the invalidation after sync (no unchanged-skip for CloudFront)', async () => {
+    const { runner, calls } = makeStubRunner();
+    await deployWebAws({ runner });
+    expect(calls[3]?.args).toContain('create-invalidation');
+    expect(calls[3]?.args).toContain('/*');
+  });
+});
+
+// ============================================================================
+// deployWebAws — CLI failure propagation
+// ============================================================================
+
+describe('deployWebAws — CLI failure propagation', () => {
+  it('surfaces a non-zero aws describe-stacks exit as an Error', async () => {
+    const runner = {
+      aws() {
+        return { stdout: '', stderr: 'Stack with id IrcAwsStack does not exist', status: 255 };
+      },
+      pnpm() {
+        return { stdout: '', stderr: '', status: 0 };
+      },
+    };
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/IrcAwsStack/u);
+  });
+
+  it('surfaces a non-zero pnpm build exit as an Error (does not proceed to s3 sync)', async () => {
+    const calls: Array<{ kind: 'aws' | 'pnpm'; args: string[] }> = [];
+    const runner = {
+      aws(args: string[]) {
+        calls.push({ kind: 'aws', args });
+        if (args[0] === 'cloudformation' && args[1] === 'describe-stacks') {
+          return { stdout: JSON.stringify(DEFAULT_OUTPUTS), stderr: '', status: 0 };
+        }
+        return { stdout: '', stderr: '', status: 0 };
+      },
+      pnpm(args: string[]) {
+        calls.push({ kind: 'pnpm', args });
+        return { stdout: '', stderr: 'Kiwi build failed', status: 1 };
+      },
+    };
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/build/iu);
+    // describe-stacks + build were called, but s3 sync / invalidation were not.
+    expect(calls).toHaveLength(2);
+    expect(calls[1]?.kind).toBe('pnpm');
+  });
+
+  it('surfaces a non-zero s3 sync exit as an Error (does not proceed to invalidation)', async () => {
+    const calls: Array<{ kind: 'aws' | 'pnpm'; args: string[] }> = [];
+    const runner = {
+      aws(args: string[]) {
+        calls.push({ kind: 'aws', args });
+        if (args[0] === 'cloudformation' && args[1] === 'describe-stacks') {
+          return { stdout: JSON.stringify(DEFAULT_OUTPUTS), stderr: '', status: 0 };
+        }
+        if (args[0] === 's3') {
+          return { stdout: '', stderr: 'AccessDenied', status: 255 };
+        }
+        return { stdout: '', stderr: '', status: 0 };
+      },
+      pnpm(args: string[]) {
+        calls.push({ kind: 'pnpm', args });
+        return { stdout: '', stderr: '', status: 0 };
+      },
+    };
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/s3 sync/u);
+    expect(calls.filter((c) => c.kind === 'aws')).toHaveLength(2);
+    // describe-stacks + s3 sync; the invalidation did NOT fire.
+    const invalidation = calls.find(
+      (c) => c.kind === 'aws' && c.args.includes('create-invalidation'),
+    );
+    expect(invalidation).toBeUndefined();
+  });
+
+  it('surfaces a non-zero cloudfront create-invalidation exit as an Error', async () => {
+    const runner = {
+      aws(args: string[]) {
+        if (args[0] === 'cloudformation' && args[1] === 'describe-stacks') {
+          return { stdout: JSON.stringify(DEFAULT_OUTPUTS), stderr: '', status: 0 };
+        }
+        if (args[0] === 'cloudfront') {
+          return { stdout: '', stderr: 'AccessDenied', status: 255 };
+        }
+        return { stdout: '', stderr: '', status: 0 };
+      },
+      pnpm() {
+        return { stdout: '', stderr: '', status: 0 };
+      },
+    };
+    await expect(deployWebAws({ runner })).rejects.toThrowError(/create-invalidation/u);
+  });
+});
+
+// ============================================================================
+// makeDefaultRunner — real subprocess plumbing
+// ============================================================================
+//
+// The default runner is what the CLI entrypoint uses; the deploy function
+// itself is exercised through stubbed runners above. These tests run real
+// subprocesses (`node --version` / a no-op script) so the spawnSync shape
+// is covered end-to-end without depending on `aws` or `pnpm` being on the
+// PATH inside the test environment.
+
+describe('makeDefaultRunner', () => {
+  it('returns an object exposing aws() and pnpm() spawnSync wrappers', () => {
+    const runner = makeDefaultRunner();
+    expect(typeof runner.aws).toBe('function');
+    expect(typeof runner.pnpm).toBe('function');
+  });
+
+  it('uses the cwd passed in (defaults to process.cwd())', () => {
+    // Smoke-check the option wiring without invoking the real `aws`/`pnpm`
+    // binaries — those aren't on PATH in the test environment. The
+    // spawnSync shape is exercised by the runCli tests below.
+    const r1 = makeDefaultRunner();
+    const r2 = makeDefaultRunner({ cwd: '/tmp' });
+    expect(r1).not.toBe(r2);
+  });
+});
+
+describe('runCli — spawnSync shape', () => {
+  // The default runner's aws()/pnpm() close over runCli with the literal
+  // 'aws'/'pnpm' binaries. Those aren't guaranteed to be on PATH inside
+  // the test environment, so exercise runCli directly with `node` as the
+  // binary — the normalisation logic (status / stdout / stderr types) is
+  // what matters, not the binary name.
+  it('returns the captured stdout and a zero status when the child succeeds', () => {
+    const result = runCli(process.execPath, ['-e', "process.stdout.write('ok')"], {
+      cwd: process.cwd(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout).toBe('ok');
+    expect(result.stderr).toBe('');
+  });
+
+  it('returns a non-zero status and the stderr body when the child fails', () => {
+    const result = runCli(
+      process.execPath,
+      ['-e', "process.stderr.write('boom'); process.exit(1);"],
+      { cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+    expect(result.status).toBe(1);
+    expect(result.stderr).toBe('boom');
+  });
+
+  it('returns status -1 when the binary cannot be spawned', () => {
+    const result = runCli('/nonexistent/binary/that/does/not/exist', [], {
+      cwd: process.cwd(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    expect(result.status).toBe(-1);
+    expect(typeof result.stderr).toBe('string');
+  });
+
+  it('returns empty-string stdout/stderr (never null/undefined) on every path', () => {
+    const ok = runCli(process.execPath, ['-e', "process.stdout.write('')"], {
+      cwd: process.cwd(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    expect(ok.stdout).toBe('');
+    expect(typeof ok.stdout).toBe('string');
+    expect(typeof ok.stderr).toBe('string');
+  });
+});
+
+// Sanity-check that the test harness can still spawnSync node directly
+// (used by runCli via process.execPath).
+describe('node child_process harness sanity', () => {
+  it('spawnSync(node --version) exits 0', () => {
+    const r = spawnSync(process.execPath, ['--version'], { encoding: 'utf8' });
+    expect(r.status).toBe(0);
+  });
+});
+
+// ============================================================================
+// Silencing the unused-vi import warning for future spies
+// ============================================================================
+
+describe('deployWebAws — runner contract', () => {
+  it('uses vi.fn spies (smoke check that the import path is wired)', () => {
+    const spy = vi.fn();
+    spy();
+    expect(spy).toHaveBeenCalled();
+  });
+});