perf(test): speed up CLI unit tests, silence stdout noise, fix flakey MCP tests (#260)

* perf(test): speed up CLI unit tests from ~8s to ~1.7s

Two key changes:

1. Fix sandbox reset test poll-interval (5s → 0s): The test used
   poll-interval: 5 which caused a real 5-second sleep in waitForSandbox.
   Other sandbox tests already use poll-interval: 0 to avoid this.

2. Replace runCommand with shared Config in cip/report and scapi/schemas
   tests: runCommand from @oclif/test calls Config.load() on every
   invocation (~1s cold, ~40ms warm). Instead, load Config once in a
   before() hook and use config.runCommand() / Help.showHelp() directly.
   Added getSharedFullConfig() helper to test-setup.ts for reuse.

* perf(test): silence stdout noise from AM command tests

stubCommandConfigAndLogger now automatically stubs command.log,
command.logToStderr, and ux.stdout so non-JSON command output
(tables, formatted details) doesn't leak to the console during tests.

* perf(test): speed up SDK unit tests from ~8.5s to ~2.7s

Several changes to eliminate unnecessary real delays in tests:

1. Telemetry tests: Use fake timers to skip the 300ms real sleep in
   telemetry.stop(). Added stopTelemetryFast() helper that installs
   sinon fake timers, advances clock, then restores. (9 calls × 300ms)

2. Logs integration tests: Reduce pollInterval (1000→100ms) and delays
   (1500→200ms, 10000→5000ms timeout) since the test just verifies
   stop/discover behavior, not sustained polling.

3. MRT env tests: Use fake timers with shouldAdvanceTime for timeout
   and polling tests. Reduce pollInterval from 100→10ms.

4. Logs tail tests: Reduce pollInterval (100→10ms) and stop/wait
   delays (200→50ms) since these use MSW mocks, not real network.

5. Code watch tests: Reduce filesystem watcher ready delays from
   200-300ms to 50ms.

6. Job command test: Stub mockInstance.webdav.get to reject immediately
   instead of timing out on a real network request.

7. CLI integration tests: Replace runCommand (which calls Config.load
   per invocation) with a shared Config instance loaded once in
   before() hook.

* fix(test): fix type errors in base-command integration test

Cast extraParams to Record<string, unknown> before accessing .query/.body
to satisfy tsc -p test stricter type checking used in CI.

* fix(test): revert mrt/env fake timers to avoid OOM in CI

The sinon.useFakeTimers({shouldAdvanceTime: true}) with pollInterval: 10
caused rapid-fire MSW HTTP requests (50+ polls in a tickAsync burst),
accumulating memory that led to OOM on CI runners with limited heap.

Reverted to real timers with pollInterval: 100 and this.timeout(5000),
which is still faster than the original tests and doesn't risk OOM.

* fix(test): restore runCommand for cip/report and scapi/schemas tests

Revert the shared Config + config.runCommand() optimization for these
tests. The change to showHelp() and config.runCommand() skipped the
oclif init hook and full run() pipeline, which reduced function coverage
below the 70% threshold.

The runCommand approach calls Config.load() per invocation but oclif
caches internally, so subsequent calls are ~40ms. The sandbox reset
poll-interval fix (5s→0s) remains the primary speed win.

Retains: sandbox reset poll-interval fix, stdout silencing in
stubCommandConfigAndLogger.

* fix(test): fix flaky MCP signal handler tests that hang on CI

The signal handler tests called command.run() which is async and sets up
stdinClosePromise, then used setTimeout-based polling to wait for
handlers to register. This was non-deterministic:

- run() is synchronous after the stubbed connect() resolves, so handlers
  are registered immediately — no polling needed
- stdinClosePromise was left dangling with only runPromise.catch(() => {})
  as cleanup, which doesn't await the flush() promise chain
- On CI (slower timing), the polling races and unresolved promises caused
  mocha to hang until the 60s timeout, then exit with code 1 or 2

Fixed by:
- Awaiting command.run() directly (handlers register synchronously)
- Triggering signal handlers immediately after run()
- Awaiting stdinClosePromise to ensure flush() completes
- Removing all setTimeout-based polling and manual cleanup

* perf: cache ts-morph Project in page-designer-decorator analyzer

Reuse a single ts-morph Project instance across analyzeComponent calls
instead of creating a new one each time. The Project uses an in-memory
file system and is stateless — source files are added with overwrite:true
and removed in a finally block after analysis.

This eliminates repeated TypeScript compiler initialization (~40ms local,
~700ms CI per call × 57 test invocations). MCP test suite drops from
~2s to ~440ms locally, expected ~52s to ~10-15s on CI.

* ci: move docs build to separate workflow triggered only on docs/ changes

The docs build (vitepress + typedoc) was running on every CI run
regardless of what changed. Move it to a dedicated workflow with a
paths filter on docs/ so it only runs when documentation files change.

This removes a blocking step from the main CI pipeline for the vast
majority of PRs that don't touch docs.

Author: clavery

.claude/skills/testing/SKILL.md

@@ -324,11 +324,29 @@ const customAuth = new MockAuthStrategy('custom-token');
 
 ## Silencing Test Output
 
-Commands may produce console output (tables, formatted displays) even in tests. Use these helpers to keep test output clean.
+Commands produce console output (tables, formatted displays) during tests. **All test helpers are designed to keep test output clean by default** — no extra work needed in most cases.
 
-### Using runSilent for Output Capture
+### stubCommandConfigAndLogger Silences Output Automatically
 
-The `runSilent` helper uses oclif's `captureOutput` to suppress stdout/stderr:
+The `stubCommandConfigAndLogger` helper (used by AM and sandbox command tests) automatically stubs `command.log`, `command.logToStderr`, and `ux.stdout` so no output leaks to the console:
+
+```typescript
+import { stubCommandConfigAndLogger } from '../../../helpers/test-setup.js';
+
+it('displays client details in non-JSON mode', async () => {
+  const command = new ClientGet([], {} as any);
+  stubCommandConfigAndLogger(command); // stdout is silenced automatically
+  stubJsonEnabled(command, false);
+  // ... setup ...
+
+  const result = await command.run(); // No console noise
+  expect(result.id).to.equal('client-123');
+});
+```
+
+### Using runSilent for Other Cases
+
+For commands that don't use `stubCommandConfigAndLogger`, use `runSilent` to capture stdout/stderr:
 
 ```typescript
 import { runSilent } from '../../helpers/test-setup.js';
@@ -344,24 +362,22 @@ it('returns data in non-JSON mode', async () => {
 });
 ```
 
-Use `runSilent` when:
-- Testing non-JSON output modes (tables, formatted displays)
-- The test doesn't need to verify console output content
-- You want clean test output with only pass/fail summary
-
 ### When Output Verification is Needed
 
-If you need to verify console output, stub `ux.stdout` directly:
+If you need to verify console output content, stub `ux.stdout` directly **before** calling `stubCommandConfigAndLogger` (which checks if the stub already exists):
 
 ```typescript
 import { ux } from '@oclif/core';
 
 it('prints table in non-JSON mode', async () => {
   const stdoutStub = sinon.stub(ux, 'stdout');
+  stubCommandConfigAndLogger(command); // won't double-stub ux.stdout
 
   await command.run();
 
   expect(stdoutStub.called).to.be.true;
+  const text = stdoutStub.firstCall.args[0];
+  expect(text).to.include('expected content');
 });
 ```
 

.github/workflows/ci.yml

@@ -60,9 +60,6 @@ jobs:
       - name: Build packages
         run: pnpm -r run build
 
-      - name: Build documentation
-        run: pnpm run docs:build
-
       - name: Run SDK tests
         id: sdk-test
         working-directory: packages/b2c-tooling-sdk

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs Build
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+
+permissions:
+  contents: read
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.17.1
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm -r run build
+
+      - name: Build documentation
+        run: pnpm run docs:build

AGENTS.md

@@ -161,6 +161,8 @@ This catches prettier formatting, import ordering, class member ordering (`perfe
 
 See [testing skill](./.claude/skills/testing/SKILL.md) for patterns on writing tests with Mocha, Chai, and MSW.
 
+**Stdout in tests**: Command tests must not leak output to the console. `stubCommandConfigAndLogger()` silences `command.log`, `command.logToStderr`, and `ux.stdout` automatically. For other cases, use `runSilent()` from `test/helpers/test-setup.ts`.
+
 ## Changesets
 
 This project uses [Changesets](https://github.com/changesets/changesets) for version management with **independent per-package versioning**. Each package versions independently based on its own changesets.

packages/b2c-cli/test/commands/sandbox/reset.test.ts

@@ -92,7 +92,7 @@ describe('sandbox reset', () => {
 
   it('waits for sandbox to reach started state when --wait is set', async () => {
     const command = await setupCommand(
-      {force: true, wait: true, 'poll-interval': 5, timeout: 60, json: true},
+      {force: true, wait: true, 'poll-interval': 0, timeout: 60, json: true},
       {
         sandboxId: 'zzzz-001',
       },

packages/b2c-cli/test/helpers/test-setup.ts

@@ -5,6 +5,7 @@
  */
 
 import type {Config} from '@oclif/core';
+import {ux} from '@oclif/core';
 import {captureOutput} from '@oclif/test';
 import sinon from 'sinon';
 import {isolateConfig, restoreConfig} from '@salesforce/b2c-tooling-sdk/test-utils';
@@ -116,6 +117,14 @@ export function stubCommandConfigAndLogger(command: any, accountManagerHost = 'a
     },
     configurable: true,
   });
+
+  // Silence stdout: stub command.log/logToStderr and ux.stdout to prevent
+  // test noise from non-JSON command output (tables, formatted details, etc.)
+  command.log = () => {};
+  command.logToStderr = () => {};
+  if (!Object.hasOwn(ux.stdout, 'isSinonProxy')) {
+    sinon.stub(ux, 'stdout');
+  }
 }
 
 /**

packages/b2c-dx-mcp/src/tools/storefrontnext/page-designer-decorator/analyzer.ts

@@ -9,6 +9,23 @@ import path from 'node:path';
 import {globSync} from 'glob';
 import {Project, InterfaceDeclaration, PropertySignature} from 'ts-morph';
 
+/**
+ * Lazily-initialized, reusable ts-morph Project for component analysis.
+ * Creating a new Project (~40ms) on every analyzeComponent call is expensive;
+ * reusing one with an in-memory file system avoids repeated TypeScript compiler init.
+ */
+let cachedProject: Project | undefined;
+
+function getProject(): Project {
+  if (!cachedProject) {
+    cachedProject = new Project({
+      useInMemoryFileSystem: true,
+      skipAddingFilesFromTsConfig: true,
+    });
+  }
+  return cachedProject;
+}
+
 // ============================================================================
 // TYPE DEFINITIONS
 // ============================================================================
@@ -352,48 +369,49 @@ function parseComponentFile(filePath: string): ComponentInfo {
     };
   }
 
-  const project = new Project({
-    useInMemoryFileSystem: true,
-    skipAddingFilesFromTsConfig: true,
-  });
+  const project = getProject();
+  const sourceFile = project.createSourceFile(filePath, content, {overwrite: true});
+
+  try {
+    const interfaces = sourceFile.getInterfaces();
+    const propsInterface = interfaces.find((i: InterfaceDeclaration) => i.getName().includes('Props'));
+
+    if (!propsInterface) {
+      return {
+        componentName: extractComponentName(content),
+        interfaceName: null,
+        hasDecorators: false,
+        props: [],
+        exportType: detectExportType(content),
+        filePath,
+      };
+    }
 
-  const sourceFile = project.createSourceFile(filePath, content);
-  const interfaces = sourceFile.getInterfaces();
-  const propsInterface = interfaces.find((i: InterfaceDeclaration) => i.getName().includes('Props'));
+    const props: PropInfo[] = propsInterface.getProperties().map((prop: PropertySignature) => {
+      const name = prop.getName();
+      const type = prop.getType().getText();
+      const optional = prop.hasQuestionToken();
+
+      return {
+        name,
+        type,
+        optional,
+        isComplex: isComplexType(type),
+        isUIOnly: isUIOnlyProp(name),
+      };
+    });
 
-  if (!propsInterface) {
     return {
       componentName: extractComponentName(content),
-      interfaceName: null,
+      interfaceName: propsInterface.getName(),
       hasDecorators: false,
-      props: [],
+      props,
       exportType: detectExportType(content),
       filePath,
     };
+  } finally {
+    project.removeSourceFile(sourceFile);
   }
-
-  const props: PropInfo[] = propsInterface.getProperties().map((prop: PropertySignature) => {
-    const name = prop.getName();
-    const type = prop.getType().getText();
-    const optional = prop.hasQuestionToken();
-
-    return {
-      name,
-      type,
-      optional,
-      isComplex: isComplexType(type),
-      isUIOnly: isUIOnlyProp(name),
-    };
-  });
-
-  return {
-    componentName: extractComponentName(content),
-    interfaceName: propsInterface.getName(),
-    hasDecorators: false,
-    props,
-    exportType: detectExportType(content),
-    filePath,
-  };
 }
 
 // ============================================================================