Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
import { afterEach, describe, expect, it, vi } from "vitest";
function browser(search = "?debug=1") {
const page = Object.assign(new EventTarget(), {
location: new URL(`https://private.example/r/1234${search}#v=private-grant`),
setTimeout: globalThis.setTimeout, clearTimeout: globalThis.clearTimeout,
}) as unknown as Window;
vi.stubGlobal("window", page);
vi.stubGlobal("document", { visibilityState: "visible" });
vi.stubGlobal("navigator", { userAgent: "test-browser", language: "en", onLine: true });
vi.spyOn(console, "info").mockImplementation(() => undefined);
return page;
}
afterEach(() => {
vi.useRealTimers();
vi.unstubAllGlobals();
vi.restoreAllMocks();
vi.resetModules();
});
describe("opt-in Browser diagnostics", () => {
it("exports validated Native capture failure codes through the existing event recorder", async () => {
browser();
const debug = await import("../src/client/lib/debug");
const { nativeEventSchema } = await import("../src/client/native/wire");
const ended = { version: 10, type: "share-ended", shareId: "share_123456", failed: true,
failure: { stage: "windows-runtime", hresult: "0x887a0005", exitCode: 2 } };
debug.debugEvent("native", "event", nativeEventSchema.parse(ended));
const report = JSON.parse(await debug.exportBrowserDebug());
expect(report.events).toContainEqual(expect.objectContaining({ scope: "native", event: "event", details: ended }));
for (const failure of [{ ...ended.failure, detail: "private" }, { ...ended.failure, stage: "private/path" },
{ ...ended.failure, hresult: "private" }, { ...ended.failure, exitCode: 2.5 }]) {
expect(nativeEventSchema.safeParse({ ...ended, failure }).success).toBe(false);
}
expect(nativeEventSchema.safeParse({ ...ended, failed: false }).success).toBe(false);
expect(nativeEventSchema.safeParse({ ...ended, failed: false, failure: undefined }).success).toBe(true);
});
it("distinguishes Host input failure from a local stalled queue without exporting input authority or text", async () => {
browser();
const debug = await import("../src/client/lib/debug");
const { RemoteInputSession } = await import("../src/client/remote-control/input-session");
class Channel extends EventTarget {
readyState = "open";
bufferedAmount = 0;
sent: Record<string, unknown>[] = [];
send(data: string) { this.sent.push(JSON.parse(data)); }
close() { this.readyState = "closed"; }
receive(data: object) { this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify(data) })); }
}
const channel = new Channel();
const session = new RemoteInputSession(channel as unknown as RTCDataChannel, () => {});
const grant = "b".repeat(64);
const activate = () => {
channel.receive({ platform: "windows", mode: "room", state: "ready" });
session.request();
const intent = channel.sent.at(-1)!.intent;
channel.receive({ platform: "windows", mode: "room", state: "active", grant, intent });
return intent;
};
const first = activate();
channel.receive({ platform: "windows", mode: "room", state: "failed", intent: first });
expect(session.state?.state).toBe("failed");
const second = activate();
channel.bufferedAmount = 8193;
session.input({ type: "text", text: "private input content" });
expect(session.state?.state).toBe("failed");
expect(channel.readyState).toBe("closed");
const exported = await debug.exportBrowserDebug();
const report = JSON.parse(exported);
expect(report.events).toEqual([
expect.objectContaining({ scope: "remote-input", event: "host-failed", details: { previousState: "active", mode: "room" } }),
expect.objectContaining({ scope: "remote-input", event: "send-failed", details: expect.objectContaining({ state: "active", readyState: "open", bufferedAmount: 8193 }) }),
]);
for (const value of [grant, first, second, "private input content"]) expect(exported).not.toContain(value);
session.dispose();
});
it("collects current preview receive and playback evidence only at export, until owner retirement", async () => {
browser();
const debug = await import("../src/client/lib/debug");
const rtc = await import("../src/client/lib/debug-webrtc");
let decoded = 0;
const connection = Object.assign(new EventTarget(), {
connectionState: "connected", getSenders: () => [], getReceivers: () => [],
getStats: vi.fn(async () => new Map([["video", {
id: "video", type: "inbound-rtp", bytesReceived: 1234, framesDecoded: decoded,
}]])),
});
const releaseConnection = rtc.observeDebugConnection(connection as unknown as RTCPeerConnection,
{ role: "native-preview", generation: 3 });
const releasePlayback = rtc.observeDebugPlayback({
videoWidth: 854, videoHeight: 480, readyState: 4, paused: false, ended: false,
getVideoPlaybackQuality: () => ({ totalVideoFrames: 7, droppedVideoFrames: 1 }),
} as unknown as HTMLVideoElement, { role: "host-preview", generation: 3 });
expect(connection.getStats).not.toHaveBeenCalled();
decoded = 8;
const report = JSON.parse(await debug.exportBrowserDebug());
expect(report.partial).toBe(false);
expect(report.events).toContainEqual(expect.objectContaining({ event: "stats", details: expect.objectContaining({
role: "native-preview", generation: 3,
stats: [expect.objectContaining({ framesDecoded: 8, bytesReceived: 1234 })],
}) }));
expect(report.events).toContainEqual(expect.objectContaining({ event: "snapshot", details: expect.objectContaining({
role: "host-preview", generation: 3, width: 854, height: 480, totalVideoFrames: 7, droppedVideoFrames: 1,
}) }));
connection.connectionState = "closed";
releaseConnection(); // Browser close() need not dispatch a state-change event.
releasePlayback();
const retired = JSON.parse(await debug.exportBrowserDebug());
expect(retired.events.filter((event: { event: string }) => event.event === "stats" || event.event === "snapshot")).toHaveLength(2);
expect(connection.getStats).toHaveBeenCalledOnce();
});
it("bounds a stalled export snapshot without changing its media owner", async () => {
browser();
vi.useFakeTimers();
const debug = await import("../src/client/lib/debug");
const release = debug.registerDebugCollector("preview", () => new Promise(() => {}));
const exporting = debug.exportBrowserDebug();
await vi.advanceTimersByTimeAsync(1_000);
const report = JSON.parse(await exporting);
expect(report.partial).toBe(true);
expect(report.collectorErrors).toContainEqual(expect.objectContaining({ collector: "preview" }));
release();
expect(vi.getTimerCount()).toBe(0);
});
it("keeps explicit diagnostics through room and App entry without copying source credentials", async () => {
const page = browser("?debug=1&token=source-secret");
const { withBrowserDebug } = await import("../src/client/lib/debug");
const { clientLaunchURL, roomRouteForExplicitEntry, readViewerRoute } = await import("../src/client/lib/session");
const launched = new URL(clientLaunchURL(
"https://site.example/?existing=1#client-access=target-capability&piik-client=1",
{ lang: "en", vis: false, theme: "light" },
));
expect(launched.origin).toBe("https://site.example");
expect(launched.search).toBe("?existing=1&debug=1");
expect(new URLSearchParams(launched.hash.slice(1)).get("client-access")).toBe("target-capability");
expect(launched.href).not.toContain("source-secret");
expect(new URL(clientLaunchURL("https://site.example/",
{ lang: "en", vis: false, theme: "light" }, false)).search).toBe("");
expect(new URL(clientLaunchURL("https://site.example/",
{ lang: "en", vis: false, theme: "light" }, true)).search).toBe("?debug=1");
expect(roomRouteForExplicitEntry("5678")).toBe("https://private.example/r/5678?debug=1");
expect(withBrowserDebug("/join")).toBe("https://private.example/join?debug=1");
const replaceState = vi.fn();
Object.assign(page, { history: { state: null, replaceState } });
const grant = `${"a".repeat(21)}A`;
page.location.hash = `#v=${grant}`;
expect(readViewerRoute()?.viewerGrant).toBe(grant);
// Consuming the invitation removes its credential and unrelated query
// parameters while keeping diagnostics enabled for a later reload.
expect(replaceState).toHaveBeenCalledWith(null, "", "https://private.example/r/1234?debug=1");
});
it("does no diagnostic collection without the explicit flag", async () => {
const page = browser("");
const debug = await import("../src/client/lib/debug");
expect(debug.withBrowserDebug("/join")).toBe("/join");
expect(debug.installBrowserDebug()).toBeUndefined();
debug.debugEvent("capture", "requested", { resolution: "1080p" });
debug.debugError("capture", "failed", new Error("private detail"));
expect(console.info).not.toHaveBeenCalled();
expect(page.__PIIK_DEBUG__).toBeUndefined();
});
it("retains error causes, stacks and technical context while removing credentials and media", async () => {
const page = browser();
const debug = await import("../src/client/lib/debug");
const cleanup = debug.installBrowserDebug();
const error = new Error('Encoding failed: {"password":"secret-password"}', {
cause: new Error("fetch https://user:[email protected]/api?token=secret-query#secret-fragment failed; Bearer secret-bearer"),
});
debug.debugError("capture", "failed", error, {
connectionId: "connection-123", address: "192.0.2.1", requested: { width: 1920, fps: 60 },
hostToken: "secret-host", nested: { icePwd: "secret-ice", cookie: "secret-cookie", sdp: "secret-sdp", remoteSdp: "secret-remote-sdp" },
data: "secret-pixels", payload: "secret-audio",
roomInteraction: { payload: { kind: "chat", text: "private-chat-contents" } },
viewerGrant: "secret-grant", passwordHash: "secret-hash",
transportError: "piik-client-v10.secret-capability Basic secret-basic\nCookie: session=secret-session; refresh=secret-refresh",
});
const report = await page.__PIIK_DEBUG__!.export();
for (const secret of ["secret-password", "secret-auth", "secret-query", "secret-fragment", "secret-bearer",
"secret-host", "secret-ice", "secret-cookie", "secret-sdp", "secret-remote-sdp", "secret-pixels", "secret-audio", "private-grant",
"secret-grant", "secret-hash", "secret-capability", "secret-basic", "secret-session", "secret-refresh", "private-chat-contents"])
expect(report).not.toContain(secret);
for (const useful of ["Encoding failed", "fetch", "stack", "cause", "connection-123", "192.0.2.1", "1920"])
expect(report).toContain(useful);
cleanup?.();
});
it("bounds history and reports eviction, truncation, retained range and collector failure", async () => {
const page = browser();
const debug = await import("../src/client/lib/debug");
debug.installBrowserDebug();
for (let revision = 0; revision < 8_300; revision++) debug.debugEvent("signal", "route", { revision });
const saved = page.__PIIK_DEBUG__!.events();
expect(saved).toHaveLength(8_192);
saved[0]!.details.revision = -1;
expect(page.__PIIK_DEBUG__!.events()[0]!.details.revision).toBe(108);
// Exercise the byte limit separately from the event-count limit.
for (let index = 0; index < 1_100; index++) debug.debugEvent("capture", "state", { message: "界".repeat(9_000) });
debug.debugError("webrtc", "collector-failed", new Error("stats unavailable"), { collector: "getStats", connectionId: "edge" });
const report = JSON.parse(await debug.exportBrowserDebug());
expect(report.history.retainedBytes).toBeLessThanOrEqual(8 * 1024 * 1024);
expect(report.history.retainedEvents).toBeLessThan(1_100);
expect(report.history.evictedEvents).toBeGreaterThan(108);
expect(report.history.truncatedEvents).toBe(1_100);
expect(report.history.firstSequence).toBe(report.events[0].sequence);
expect(report.history.lastAt).toBe(report.events.at(-1).at);
expect(report.partial).toBe(true);
expect(report.collectorErrors).toContainEqual(expect.objectContaining({ collector: "getStats", connectionId: "edge" }));
});
it("returns retained evidence when optional Browser metadata never completes", async () => {
browser();
vi.useFakeTimers();
vi.stubGlobal("navigator", { userAgent: "known-browser", userAgentData: {
getHighEntropyValues: () => new Promise(() => undefined),
} });
const debug = await import("../src/client/lib/debug");
debug.debugEvent("capture", "active", { width: 1280 });
const exporting = debug.exportBrowserDebug();
await vi.advanceTimersByTimeAsync(1_000);
const report = JSON.parse(await exporting);
expect(report.environment.userAgent).toBe("known-browser");
expect(report.events).toHaveLength(1);
expect(report.partial).toBe(true);
expect(report.collectorErrors[0].collector).toBe("environment");
expect(vi.getTimerCount()).toBe(0);
});
it("correlates existing RTC samples and DTLS events without adding statistics polls", async () => {
const page = browser();
vi.useFakeTimers();
const debug = await import("../src/client/lib/debug");
const rtc = await import("../src/client/lib/debug-webrtc");
debug.installBrowserDebug();
const transport = Object.assign(new EventTarget(), { state: "connecting" });
const connection = Object.assign(new EventTarget(), {
connectionState: "connecting", iceConnectionState: "checking", iceGatheringState: "complete", signalingState: "stable",
getSenders: () => [{ transport }], getReceivers: () => [], getStats: vi.fn(),
});
const peer = connection as unknown as RTCPeerConnection;
rtc.observeDebugConnection(peer, { connectionId: "local-edge", role: "send" });
transport.state = "connected";
transport.dispatchEvent(new Event("statechange"));
rtc.debugRtcStats(peer, new Map([
["video", { id: "video", type: "outbound-rtp", framesEncoded: 60, totalEncodeTime: 0.3 }],
["codec", { id: "codec", type: "codec", mimeType: "video/H264", sdpFmtpLine: "packetization-mode=1;profile-level-id=42e01f" }],
["private", { id: "private", type: "certificate", base64Certificate: "private-certificate" }],
]) as unknown as RTCStatsReport);
await vi.advanceTimersByTimeAsync(5_000);
expect(connection.getStats).not.toHaveBeenCalled();
expect(vi.getTimerCount()).toBe(0);
const history = page.__PIIK_DEBUG__!.events();
expect(history.filter((event) => event.scope === "webrtc").every((event) => event.details.connectionId === "local-edge")).toBe(true);
expect(history).toContainEqual(expect.objectContaining({ event: "dtls-state", details: expect.objectContaining({ state: "connected" }) }));
const report = await debug.exportBrowserDebug();
expect(report).toContain("framesEncoded");
expect(report).toContain("packetization-mode=1;profile-level-id=42e01f");
expect(report).not.toContain("private-certificate");
});
it("keeps selected ICE evidence when many interface pairs exceed the raw report limit", async () => {
browser();
const debug = await import("../src/client/lib/debug");
const rtc = await import("../src/client/lib/debug-webrtc");
const connection = Object.assign(new EventTarget(), { getSenders: () => [], getReceivers: () => [] });
const peer = connection as unknown as RTCPeerConnection;
rtc.observeDebugConnection(peer, { connectionId: "many-interfaces", role: "receive" });
const records = new Map<string, object>();
for (let index = 0; index < 70; index++) {
records.set(`pair-${index}`, { type: "candidate-pair", state: "failed" });
}
records.set("chosen", { type: "candidate-pair", state: "succeeded",
localCandidateId: "local", remoteCandidateId: "remote", requestsSent: 4, responsesReceived: 3 });
records.set("local", { type: "local-candidate", candidateType: "host", protocol: "udp", address: "192.0.2.1" });
records.set("remote", { type: "remote-candidate", candidateType: "srflx", foundation: "sp1", address: "192.0.2.2" });
records.set("transport", { type: "transport", selectedCandidatePairId: "chosen" });
rtc.debugRtcStats(peer, records as unknown as RTCStatsReport);
const report = JSON.parse(await debug.exportBrowserDebug());
const sample = report.events.find((entry: { event: string }) => entry.event === "stats");
expect(report.partial).toBe(true);
expect(sample.details.stats).toHaveLength(64);
expect(sample.details.ice.pairs).toMatchObject({ total: 71, failed: 70, succeeded: 1 });
expect(sample.details.ice.selected).toEqual([{
state: "succeeded", dtlsState: null,
localType: "host", remoteType: "srflx", protocol: "udp", natTraversalPath: "predicted",
requestsSent: 4, responsesReceived: 3, currentRoundTripTime: null,
}]);
expect(JSON.stringify(sample.details.ice)).not.toContain("192.0.2.");
});
it("correlates actual Native request and response using their existing wire identity", async () => {
const page = browser();
const token = "x".repeat(43);
class Socket extends EventTarget {
static OPEN = 1; static CLOSING = 2;
readyState = 1; protocol = `piik-client-v10.${token}`;
constructor() { super(); queueMicrotask(() => this.dispatchEvent(new Event("open"))); }
close() { this.readyState = 3; }
send(raw: string) {
const request = JSON.parse(raw);
queueMicrotask(() => this.dispatchEvent(Object.assign(new Event("message"), {
data: JSON.stringify({ version: 10, id: request.id,
type: request.type === "hello" ? "ready" : "share-updated",
...(request.shareId ? { shareId: request.shareId } : {}) }),
})));
}
}
vi.stubGlobal("WebSocket", Socket);
vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({
protocol: 10, service: "piik-client", port: 39721, instanceToken: token,
nativeMedia: { video: true, processAudio: false, systemAudio: true, hardwareH264: true, softwareVP8: true },
}), { status: 200 })));
const debug = await import("../src/client/lib/debug");
debug.installBrowserDebug();
const { NativeClient } = await import("../src/client/native/client");
const { DEFAULT_QUALITY_SETTINGS } = await import("../src/shared/protocol");
const client = await NativeClient.connect();
expect(client).not.toBeNull();
try { await client!.updateShare("share_123456", DEFAULT_QUALITY_SETTINGS); }
finally { client!.close(); }
const history = page.__PIIK_DEBUG__!.events().filter((event) => event.details.type === "update-share");
expect(history.map((event) => event.event)).toEqual(["request", "response"]);
expect(history[1]!.details.requestId).toBe(history[0]!.details.requestId);
expect(history[1]!.details.durationMs).toBeGreaterThanOrEqual(0);
expect(history[0]!.details.requested).toMatchObject({ profile: DEFAULT_QUALITY_SETTINGS });
expect(await debug.exportBrowserDebug()).not.toContain(token);
});
it("reports an observed App mismatch without exposing its capability token", async () => {
const page = browser();
const token = "x".repeat(43);
vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({
protocol: 8, service: "piik-client", port: 39721, instanceToken: token,
}))));
const debug = await import("../src/client/lib/debug");
debug.installBrowserDebug();
const { NativeClient } = await import("../src/client/native/client");
await expect(NativeClient.connect()).rejects.toMatchObject({ name: "NativeCompatibilityError" });
expect(page.__PIIK_DEBUG__!.events()).toContainEqual(expect.objectContaining({
scope: "native", event: "incompatible", details: { actualProtocol: 8, expectedProtocol: 10 },
}));
expect(await debug.exportBrowserDebug()).not.toContain(token);
});
});