feat(test): add "test open <test-id>" to jump from the terminal to the dashboard

Author: Andy00L

src/commands/test.test.ts

@@ -33,6 +33,7 @@ import {
   runGet,
   runLint,
   runList,
+  runOpen,
   runPlanPut,
   runResult,
   runSteps,
@@ -129,6 +130,7 @@ describe('createTestCommand — surface', () => {
       'get',
       'lint',
       'list',
+      'open',
       'plan',
       'rerun',
       'result',
@@ -2324,6 +2326,94 @@ describe('runCodePut', () => {
   });
 });
 
+describe('runOpen', () => {
+  // The mock endpoint host has no portal mapping; the operator override is the
+  // supported escape hatch and gives the tests a deterministic base.
+  beforeEach(() => {
+    process.env.TESTSPRITE_PORTAL_URL = 'https://portal.example.com';
+  });
+  afterEach(() => {
+    delete process.env.TESTSPRITE_PORTAL_URL;
+  });
+
+  const TEST_ROW = {
+    id: 'test_open_me',
+    projectId: 'project_alice',
+    projectName: 'Alice',
+    name: 'Checkout',
+    type: 'frontend',
+    createdFrom: 'cli',
+    status: 'ready',
+    createdAt: '2026-06-01T10:00:00.000Z',
+    updatedAt: '2026-06-01T10:00:00.000Z',
+  };
+
+  it('prints the dashboard URL and spawns the opener with it', async () => {
+    const { credentialsPath } = makeCreds();
+    const fetchImpl = makeFetch(() => ({ body: TEST_ROW }));
+    const out: string[] = [];
+    const opened: string[] = [];
+    const result = await runOpen(
+      {
+        profile: 'default',
+        output: 'text',
+        debug: false,
+        testId: 'test_open_me',
+        noBrowser: false,
+      },
+      { credentialsPath, fetchImpl, stdout: line => out.push(line) },
+      url => opened.push(url),
+    );
+    expect(result.dashboardUrl).toContain('/dashboard/tests/project_alice/test/test_open_me');
+    expect(out.join('\n')).toContain(result.dashboardUrl);
+    expect(opened).toEqual([result.dashboardUrl]);
+  });
+
+  it('--no-browser prints the URL but never spawns', async () => {
+    const { credentialsPath } = makeCreds();
+    const fetchImpl = makeFetch(() => ({ body: TEST_ROW }));
+    const out: string[] = [];
+    const opened: string[] = [];
+    await runOpen(
+      {
+        profile: 'default',
+        output: 'json',
+        debug: false,
+        testId: 'test_open_me',
+        noBrowser: true,
+      },
+      { credentialsPath, fetchImpl, stdout: line => out.push(line) },
+      url => opened.push(url),
+    );
+    expect(opened).toEqual([]);
+    expect((JSON.parse(out.join('')) as { dashboardUrl: string }).dashboardUrl).toContain(
+      'test_open_me',
+    );
+  });
+
+  it('a broken opener downgrades to a stderr hint, never a failure', async () => {
+    const { credentialsPath } = makeCreds();
+    const fetchImpl = makeFetch(() => ({ body: TEST_ROW }));
+    const errs: string[] = [];
+    await expect(
+      runOpen(
+        {
+          profile: 'default',
+          output: 'text',
+          debug: false,
+          testId: 'test_open_me',
+          noBrowser: false,
+        },
+        { credentialsPath, fetchImpl, stdout: () => undefined, stderr: line => errs.push(line) },
+        () => {
+          throw new Error('no display');
+        },
+      ),
+    ).resolves.toBeDefined();
+    expect(errs.join('\n')).toContain('could not launch a browser');
+  });
+});
+
 describe('runSteps', () => {
   it('JSON mode returns the §6.4 wire shape and forwards pageSize/cursor', async () => {
     const { credentialsPath } = makeCreds();

src/commands/test.ts

@@ -3,6 +3,7 @@ import { rename, stat, unlink } from 'node:fs/promises';
 import { basename, dirname, extname, isAbsolute, join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { Command } from 'commander';
+import { openInBrowser } from '../lib/browser.js';
 import {
   emitDryRunBanner,
   makeHttpClient,
@@ -4000,6 +4001,61 @@ export async function runLint(opts: LintOptions, deps: TestDeps = {}): Promise<C
   return report;
 }
 
+export interface OpenOptions extends CommonOptions {
+  testId: string;
+  /** Print the URL only; never spawn a browser (SSH/headless/CI/agents). */
+  noBrowser: boolean;
+}
+
+/**
+ * `test open <test-id>` (issue #121): jump from the terminal to the test's
+ * dashboard page. The CLI already computes this deep-link and prints it as
+ * text on other commands; this closes the last inch (the `gh browse` /
+ * `cypress open` hop). The URL is ALWAYS printed to stdout (so `--no-browser`
+ * and headless use still compose), then the OS browser is spawned unless
+ * --no-browser. An endpoint with no known portal mapping is a hard error
+ * rather than a silent no-op.
+ */
+export async function runOpen(
+  opts: OpenOptions,
+  deps: TestDeps = {},
+  opener: (url: string) => void = openInBrowser,
+): Promise<{ dashboardUrl: string }> {
+  const out = makeOutput(opts.output, deps);
+  const stderrFn = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+
+  if (opts.dryRun) {
+    emitDryRunBanner(stderrFn);
+    const sample = {
+      dashboardUrl: `https://www.testsprite.com/dashboard/tests/p_dryrun_2026/test/${opts.testId}`,
+    };
+    out.print(sample, data => (data as { dashboardUrl: string }).dashboardUrl);
+    return sample;
+  }
+
+  const client = makeClient(opts, deps);
+  // The deep-link needs the projectId; the test record is the source of truth.
+  const test = await client.get<CliTest>(`/tests/${encodeURIComponent(opts.testId)}`);
+  const dashboardUrl = resolvePortalUrl(resolveApiUrl(opts, deps), test.projectId, opts.testId);
+  if (dashboardUrl === undefined) {
+    throw new CLIError(
+      `no dashboard mapping for this API endpoint; set TESTSPRITE_PORTAL_URL to your Portal origin`,
+      1,
+    );
+  }
+  out.print({ dashboardUrl }, () => dashboardUrl);
+  if (!opts.noBrowser) {
+    try {
+      opener(dashboardUrl);
+    } catch {
+      // The URL is already on stdout; a missing opener (containers, minimal
+      // hosts) downgrades to "open it yourself" instead of a hard failure.
+      stderrFn('could not launch a browser; open the URL above manually (or use --no-browser)');
+    }
+  }
+  return { dashboardUrl };
+}
+
 export async function runSteps(
   opts: StepsOptions,
   deps: TestDeps = {},
@@ -7770,6 +7826,24 @@ export function createTestCommand(deps: TestDeps = {}): Command {
       );
     });
 
+  test
+    .command('open <test-id>')
+    .description(
+      'Open the test in the TestSprite dashboard: prints the deep-link URL, then spawns your default browser unless --no-browser.',
+    )
+    .option('--no-browser', 'print the URL only (SSH, headless, CI, agents)')
+    .addHelpText('after', GLOBAL_OPTS_HINT)
+    .action(async (testId: string, cmdOpts: { browser?: boolean }, command: Command) => {
+      await runOpen(
+        {
+          ...resolveCommonOptions(command),
+          testId,
+          noBrowser: cmdOpts.browser === false,
+        },
+        deps,
+      );
+    });
+
   test
     .command('steps <test-id>')
     .description(

src/lib/browser.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock the real spawner so the default `exec` path (detached spawn + unref)
+// is exercised without launching a real process.
+const spawnMock = vi.fn();
+vi.mock('node:child_process', () => ({
+  spawn: (command: string, args: readonly string[], opts: unknown) =>
+    spawnMock(command, args, opts),
+}));
+
+import { openInBrowser } from './browser.js';
+
+describe('openInBrowser', () => {
+  const url = 'https://portal.example.com/tests/t_123';
+
+  it('uses `open <url>` on darwin', () => {
+    const calls: Array<{ command: string; args: readonly string[] }> = [];
+    openInBrowser(url, {
+      platform: 'darwin',
+      exec: (command, args) => calls.push({ command, args }),
+    });
+    expect(calls).toEqual([{ command: 'open', args: [url] }]);
+  });
+
+  it('uses rundll32 FileProtocolHandler on win32', () => {
+    const calls: Array<{ command: string; args: readonly string[] }> = [];
+    openInBrowser(url, {
+      platform: 'win32',
+      exec: (command, args) => calls.push({ command, args }),
+    });
+    expect(calls).toEqual([{ command: 'rundll32', args: ['url.dll,FileProtocolHandler', url] }]);
+  });
+
+  it('uses xdg-open on other platforms', () => {
+    const calls: Array<{ command: string; args: readonly string[] }> = [];
+    openInBrowser(url, {
+      platform: 'linux',
+      exec: (command, args) => calls.push({ command, args }),
+    });
+    expect(calls).toEqual([{ command: 'xdg-open', args: [url] }]);
+  });
+
+  it('refuses a non-http(s) URL before spawning', () => {
+    const exec = vi.fn();
+    expect(() => openInBrowser('file:///etc/passwd', { platform: 'linux', exec })).toThrow(
+      /non-http\(s\)/,
+    );
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it('throws on a malformed URL', () => {
+    const exec = vi.fn();
+    expect(() => openInBrowser('not a url', { exec })).toThrow();
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  describe('default spawner', () => {
+    beforeEach(() => {
+      spawnMock.mockReset();
+    });
+
+    it('spawns detached, ignores stdio, and unrefs the child', () => {
+      const unref = vi.fn();
+      spawnMock.mockReturnValue({ unref });
+      openInBrowser(url, { platform: 'darwin' });
+      expect(spawnMock).toHaveBeenCalledWith('open', [url], { detached: true, stdio: 'ignore' });
+      expect(unref).toHaveBeenCalledTimes(1);
+    });
+  });
+});

src/lib/browser.ts

@@ -0,0 +1,46 @@
+/**
+ * Cross-platform "open this URL in the default browser" helper for
+ * `test open` (issue #121). Spawns the platform opener with an argv array
+ * (never a shell string) so a URL can never be shell-injected, and refuses
+ * anything that is not http(s) before any process is spawned.
+ *
+ * Platform openers:
+ *   darwin  open <url>
+ *   win32   rundll32 url.dll,FileProtocolHandler <url>  (avoids `cmd /c start`,
+ *           whose re-parsing would mangle `&` and other metachars in the URL)
+ *   other   xdg-open <url>
+ *
+ * The child is detached and unref'd so the CLI exits immediately; failures
+ * are the caller's to surface (it already printed the URL as the fallback).
+ */
+import { spawn } from 'node:child_process';
+
+export interface OpenInBrowserDeps {
+  platform?: NodeJS.Platform;
+  /** Process spawner taking an argv array. Defaults to a detached spawn. */
+  exec?: (command: string, args: readonly string[]) => void;
+}
+
+export function openInBrowser(url: string, deps: OpenInBrowserDeps = {}): void {
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`refusing to open a non-http(s) URL (${parsed.protocol})`);
+  }
+  const platform = deps.platform ?? process.platform;
+  const exec =
+    deps.exec ??
+    ((command: string, args: readonly string[]) => {
+      const child = spawn(command, [...args], { detached: true, stdio: 'ignore' });
+      child.unref();
+    });
+
+  if (platform === 'darwin') {
+    exec('open', [url]);
+    return;
+  }
+  if (platform === 'win32') {
+    exec('rundll32', ['url.dll,FileProtocolHandler', url]);
+    return;
+  }
+  exec('xdg-open', [url]);
+}

test/__snapshots__/help.snapshot.test.ts.snap

@@ -200,6 +200,10 @@ Commands:
                                         (--plan-from, FE-only, M3.2 piece-5)
   create-batch [options]                Create multiple FE tests from a JSONL
                                         of plan specs (FE-only)
+  open [options] <test-id>              Open the test in the TestSprite
+                                        dashboard: prints the deep-link URL,
+                                        then spawns your default browser unless
+                                        --no-browser.
   steps [options] <test-id>             List the steps for a test (server
                                         returns the cumulative log across every
                                         run; use --run-id to scope to one run)