test(brew): add coverage for Homebrew install method

- UpgradeError unsupported_operation: default message
- fetchLatestVersion/versionExists: brew routes to GitHub (same as curl)
- detectInstallationMethod: detects brew from /Cellar/ in execPath
- executeUpgrade(brew): success, non-zero exit, spawn error, correct args
- upgrade command: errors on brew + explicit version, check mode works

Author: BYK

test/commands/cli/upgrade.test.ts

@@ -216,6 +216,39 @@ describe("sentry cli upgrade", () => {
     });
   });
 
+  describe("brew method", () => {
+    test("errors immediately when specific version requested with brew", async () => {
+      // No fetch mock needed — error is thrown before any network call
+      const { context, output, errors } = createMockContext({
+        homeDir: testDir,
+      });
+
+      await run(app, ["cli", "upgrade", "--method", "brew", "1.2.3"], context);
+
+      const allOutput = [...output, ...errors].join("");
+      expect(allOutput).toContain(
+        "Homebrew does not support installing a specific version"
+      );
+    });
+
+    test("check mode works for brew method", async () => {
+      mockGitHubVersion("99.99.99");
+
+      const { context, output } = createMockContext({ homeDir: testDir });
+
+      await run(
+        app,
+        ["cli", "upgrade", "--check", "--method", "brew"],
+        context
+      );
+
+      const combined = output.join("");
+      expect(combined).toContain("Installation method: brew");
+      expect(combined).toContain("Latest version: 99.99.99");
+      expect(combined).toContain("Run 'sentry cli upgrade' to update.");
+    });
+  });
+
   describe("version validation", () => {
     test("reports error for non-existent version", async () => {
       // Mock: latest is 99.99.99, but 0.0.1 doesn't exist

test/isolated/brew-upgrade.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Isolated tests for Homebrew upgrade execution.
+ *
+ * Uses mock.module() to stub node:child_process/spawn, which leaks module
+ * state — kept isolated so it doesn't affect other test files.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+import {
+  execFile,
+  execFileSync,
+  execSync,
+  fork,
+  spawnSync,
+} from "node:child_process";
+import { EventEmitter } from "node:events";
+import { UpgradeError } from "../../src/lib/errors.js";
+
+/**
+ * Build a minimal fake ChildProcess EventEmitter that emits 'close'
+ * with the given exit code after a microtask tick.
+ */
+function fakeProcess(exitCode: number): EventEmitter {
+  const emitter = new EventEmitter();
+  // Emit close asynchronously so the Promise can attach listeners first
+  queueMicrotask(() => emitter.emit("close", exitCode));
+  return emitter;
+}
+
+// Mock node:child_process before importing the module under test.
+// Bun hoists mock.module() calls, so this runs before any imports below.
+// Pass through real non-spawn exports so transitive deps are unaffected.
+let spawnImpl: (cmd: string, args: string[], opts: object) => EventEmitter =
+  () => fakeProcess(0);
+
+mock.module("node:child_process", () => ({
+  execFile,
+  execFileSync,
+  execSync,
+  fork,
+  spawnSync,
+  spawn: (cmd: string, args: string[], opts: object) =>
+    spawnImpl(cmd, args, opts),
+}));
+
+// Import after mock is registered
+const { executeUpgrade } = await import("../../src/lib/upgrade.js");
+
+describe("executeUpgrade (brew)", () => {
+  test("returns null on successful brew upgrade", async () => {
+    spawnImpl = () => fakeProcess(0);
+
+    const result = await executeUpgrade("brew", "1.0.0");
+    expect(result).toBeNull();
+  });
+
+  test("throws UpgradeError with execution_failed reason on non-zero exit", async () => {
+    spawnImpl = () => fakeProcess(1);
+
+    await expect(executeUpgrade("brew", "1.0.0")).rejects.toThrow(UpgradeError);
+
+    try {
+      await executeUpgrade("brew", "1.0.0");
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(UpgradeError);
+      expect((err as UpgradeError).reason).toBe("execution_failed");
+      expect((err as UpgradeError).message).toContain("exit code 1");
+    }
+  });
+
+  test("throws UpgradeError with execution_failed reason on spawn error", async () => {
+    spawnImpl = () => {
+      const emitter = new EventEmitter();
+      queueMicrotask(() => emitter.emit("error", new Error("brew not found")));
+      return emitter;
+    };
+
+    try {
+      await executeUpgrade("brew", "1.0.0");
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(UpgradeError);
+      expect((err as UpgradeError).reason).toBe("execution_failed");
+      expect((err as UpgradeError).message).toContain("brew not found");
+    }
+  });
+
+  test("invokes brew with correct arguments", async () => {
+    let capturedCmd = "";
+    let capturedArgs: string[] = [];
+
+    spawnImpl = (cmd, args) => {
+      capturedCmd = cmd;
+      capturedArgs = args;
+      return fakeProcess(0);
+    };
+
+    await executeUpgrade("brew", "1.0.0");
+
+    expect(capturedCmd).toBe("brew");
+    expect(capturedArgs).toEqual(["upgrade", "getsentry/tools/sentry"]);
+  });
+});

test/lib/upgrade.test.ts

@@ -18,6 +18,7 @@ import {
 import { clearInstallInfo } from "../../src/lib/db/install-info.js";
 import { UpgradeError } from "../../src/lib/errors.js";
 import {
+  detectInstallationMethod,
   executeUpgrade,
   fetchLatestFromGitHub,
   fetchLatestFromNpm,
@@ -250,6 +251,14 @@ describe("UpgradeError", () => {
     expect(error.message).toBe("The specified version was not found.");
   });
 
+  test("creates error with default message for unsupported_operation", () => {
+    const error = new UpgradeError("unsupported_operation");
+    expect(error.reason).toBe("unsupported_operation");
+    expect(error.message).toBe(
+      "This operation is not supported for this installation method."
+    );
+  });
+
   test("allows custom message", () => {
     const error = new UpgradeError("network_error", "Custom error message");
     expect(error.reason).toBe("network_error");
@@ -323,6 +332,19 @@ describe("fetchLatestVersion", () => {
     expect(version).toBe("2.0.0");
   });
 
+  test("uses GitHub for brew method", async () => {
+    mockFetch(
+      async () =>
+        new Response(JSON.stringify({ tag_name: "v2.0.0" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        })
+    );
+
+    const version = await fetchLatestVersion("brew");
+    expect(version).toBe("2.0.0");
+  });
+
   test("uses npm for unknown method", async () => {
     mockFetch(
       async () =>
@@ -380,6 +402,20 @@ describe("versionExists", () => {
     expect(exists).toBe(true);
   });
 
+  test("checks GitHub for brew method - version exists", async () => {
+    mockFetch(async () => new Response(null, { status: 200 }));
+
+    const exists = await versionExists("brew", "1.0.0");
+    expect(exists).toBe(true);
+  });
+
+  test("checks GitHub for brew method - version does not exist", async () => {
+    mockFetch(async () => new Response(null, { status: 404 }));
+
+    const exists = await versionExists("brew", "99.99.99");
+    expect(exists).toBe(false);
+  });
+
   test("checks npm for yarn method", async () => {
     mockFetch(async () => new Response(null, { status: 200 }));
 
@@ -431,6 +467,54 @@ describe("executeUpgrade", () => {
   });
 });
 
+describe("Homebrew detection (detectInstallationMethod)", () => {
+  let originalExecPath: string;
+
+  beforeEach(() => {
+    originalExecPath = process.execPath;
+  });
+
+  afterEach(() => {
+    Object.defineProperty(process, "execPath", {
+      value: originalExecPath,
+      configurable: true,
+    });
+    clearInstallInfo();
+  });
+
+  test("detects brew when execPath resolves through /Cellar/", async () => {
+    Object.defineProperty(process, "execPath", {
+      value: "/opt/homebrew/Cellar/sentry/1.2.3/bin/sentry",
+      configurable: true,
+    });
+
+    const method = await detectInstallationMethod();
+    expect(method).toBe("brew");
+  });
+
+  test("detects brew for Intel Homebrew path (/usr/local/Cellar/)", async () => {
+    Object.defineProperty(process, "execPath", {
+      value: "/usr/local/Cellar/sentry/1.2.3/bin/sentry",
+      configurable: true,
+    });
+
+    const method = await detectInstallationMethod();
+    expect(method).toBe("brew");
+  });
+
+  test("does not detect brew for non-Homebrew paths", async () => {
+    // A plain curl-installed binary should not be detected as brew
+    Object.defineProperty(process, "execPath", {
+      value: "/home/user/.sentry/bin/sentry",
+      configurable: true,
+    });
+
+    // Will fall through to package manager checks and return "unknown" in test env
+    const method = await detectInstallationMethod();
+    expect(method).not.toBe("brew");
+  });
+});
+
 describe("getBinaryDownloadUrl", () => {
   test("builds correct URL for current platform", () => {
     const url = getBinaryDownloadUrl("1.0.0");