π¬ A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots π
TypeScript browser-extensionchrome-extensiondocumentationfirefox-extensionguide-generatorlocal-firstmanifest-v3privacy-firstproductivityreactscreenshotstep-by-step-guidetutorialtypescriptworkflowwxt
test(guides): cover AI description ownership and the per-guide drain
Luis Ortiz3a842e5e78b4
diff --git a/src/core/guides/__tests__/ai-pending.test.ts b/src/core/guides/__tests__/ai-pending.test.tsnew file mode 100644index 0000000..8462ce8--- /dev/null+++ b/src/core/guides/__tests__/ai-pending.test.ts@@ -0,0 +1,195 @@+import 'fake-indexeddb/auto';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';++const { broadcasts } = vi.hoisted(() => {+ const broadcasts: unknown[] = [];+ globalThis.BroadcastChannel = class BroadcastChannel {+ name: string;+ constructor(name: string) {+ this.name = name;+ }+ postMessage(message: unknown) {+ broadcasts.push(message);+ }+ addEventListener() {}+ removeEventListener() {}+ close() {}+ onmessage = null;+ onmessageerror = null;+ dispatchEvent() {+ return true;+ }+ } as unknown as typeof BroadcastChannel;+ return { broadcasts };+});++import { db } from '../db';+import { applyNarrationToSteps, clearStepAiPending, type GuideChangeEvent, updateStepDescription } from '../service';+import type { Guide, Step } from '../types';++const FALLBACK = 'Clicked Save';+const AI_TEXT = 'Click Save to confirm the new password';++function guideEvents(): GuideChangeEvent[] {+ return broadcasts.filter((m): m is GuideChangeEvent => !!m && typeof m === 'object' && 'type' in m);+}++function makeStep(overrides: Partial<Step> & { id: string }): Step {+ return {+ guideId: 'g1',+ index: 0,+ description: FALLBACK,+ action: 'click',+ url: 'https://example.com/settings',+ timestamp: Date.now(),+ ...overrides,+ };+}++async function seedGuide(id: string, extras?: Partial<Guide>): Promise<Guide> {+ const guide: Guide = {+ id,+ title: 'Test Guide',+ createdAt: Date.now(),+ updatedAt: Date.now(),+ stepIds: [],+ starred: false,+ deletedAt: null,+ ...extras,+ };+ await db.guides.add(guide);+ return guide;+}++async function seedPendingStep(id: string, extras?: Partial<Step>): Promise<void> {+ await db.steps.add(makeStep({ id, aiPending: true, ...extras }));+}++beforeEach(async () => {+ await seedGuide('g1', { stepIds: ['s1'] });+ broadcasts.length = 0;+});++afterEach(async () => {+ await db.guides.clear();+ await db.steps.clear();+});++describe('clearStepAiPending', () => {+ it('writes the AI text and claims the source while the step is still pending and unclaimed', async () => {+ await seedPendingStep('s1');++ await clearStepAiPending('s1', AI_TEXT);++ const step = await db.steps.get('s1');+ expect(step?.description).toBe(AI_TEXT);+ expect(step?.descriptionSource).toBe('ai');+ expect(step?.aiPending).toBe(false);+ expect(guideEvents()).toEqual([{ type: 'mutated' }]);+ });++ it('claims a heuristic description, which no other writer owns', async () => {+ await seedPendingStep('s1', { descriptionSource: 'heuristic' });++ await clearStepAiPending('s1', AI_TEXT);++ const step = await db.steps.get('s1');+ expect(step?.description).toBe(AI_TEXT);+ expect(step?.descriptionSource).toBe('ai');+ });++ it('clears the flag and leaves the description alone when no AI text arrives', async () => {+ await seedPendingStep('s1');++ await clearStepAiPending('s1');++ const step = await db.steps.get('s1');+ expect(step?.description).toBe(FALLBACK);+ expect(step?.descriptionSource).toBeUndefined();+ expect(step?.aiPending).toBe(false);+ expect(guideEvents()).toEqual([]);+ });++ it('treats empty AI text as no result', async () => {+ await seedPendingStep('s1');++ await clearStepAiPending('s1', '');++ const step = await db.steps.get('s1');+ expect(step?.description).toBe(FALLBACK);+ expect(step?.descriptionSource).toBeUndefined();+ expect(step?.aiPending).toBe(false);+ expect(guideEvents()).toEqual([]);+ });++ it('never overwrites a voice narration that landed while the AI call was in flight', async () => {+ await seedPendingStep('s1');+ await applyNarrationToSteps([{ stepId: 's1', description: 'I open the password field and save' }]);+ broadcasts.length = 0;++ await clearStepAiPending('s1', AI_TEXT);++ const step = await db.steps.get('s1');+ expect(step?.description).toBe('I open the password field and save');+ expect(step?.descriptionSource).toBe('narration');+ expect(step?.aiPending).toBe(false);+ expect(guideEvents()).toEqual([]);+ });++ it('never overwrites a manual edit made after the pending flag was cleared', async () => {+ await seedPendingStep('s1');+ await clearStepAiPending('s1');+ await updateStepDescription('s1', 'My own words');+ broadcasts.length = 0;++ await clearStepAiPending('s1', AI_TEXT);++ const step = await db.steps.get('s1');+ expect(step?.description).toBe('My own words');+ expect(step?.descriptionSource).toBeUndefined();+ expect(step?.aiPending).toBe(false);+ expect(guideEvents()).toEqual([]);+ });++ it('never overwrites a manual edit made after an earlier AI result was claimed', async () => {+ await seedPendingStep('s1');+ await clearStepAiPending('s1', AI_TEXT);+ await updateStepDescription('s1', 'My own words');+ broadcasts.length = 0;++ await clearStepAiPending('s1', 'A second, later AI result');++ const step = await db.steps.get('s1');+ expect(step?.description).toBe('My own words');+ expect(step?.descriptionSource).toBe('ai');+ expect(guideEvents()).toEqual([]);+ });++ it('resolves without writing anything when the step was deleted mid-recording', async () => {+ await seedPendingStep('s1');+ await db.steps.delete('s1');++ await expect(clearStepAiPending('s1', AI_TEXT)).resolves.toBeUndefined();++ expect(await db.steps.count()).toBe(0);+ expect(guideEvents()).toEqual([]);+ });++ it('resolves without writing anything for a step id that never existed', async () => {+ await expect(clearStepAiPending('never-created', AI_TEXT)).resolves.toBeUndefined();++ expect(await db.steps.count()).toBe(0);+ expect(guideEvents()).toEqual([]);+ });++ it('leaves sibling steps untouched', async () => {+ await seedPendingStep('s1');+ await seedPendingStep('s2', { index: 1, description: 'Clicked Cancel' });++ await clearStepAiPending('s1', AI_TEXT);++ const sibling = await db.steps.get('s2');+ expect(sibling?.description).toBe('Clicked Cancel');+ expect(sibling?.aiPending).toBe(true);+ });+});diff --git a/src/entrypoints/background/__tests__/description-queue.test.ts b/src/entrypoints/background/__tests__/description-queue.test.tsnew file mode 100644index 0000000..d058ffe--- /dev/null+++ b/src/entrypoints/background/__tests__/description-queue.test.ts@@ -0,0 +1,219 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';++type QueueModule = typeof import('../description-queue');++interface Job {+ run: () => Promise<void>;+ settle: () => void;+ fail: (reason: unknown) => void;+ started: boolean;+ finished: boolean;+}++let queueDescription: QueueModule['queueDescription'];+let drainDescriptions: QueueModule['drainDescriptions'];++function job(): Job {+ let settle!: () => void;+ let fail!: (reason: unknown) => void;+ const gate = new Promise<void>((resolve, reject) => {+ settle = resolve;+ fail = reject;+ });+ const state: Job = {+ run: async () => {+ state.started = true;+ try {+ await gate;+ } finally {+ state.finished = true;+ }+ },+ settle,+ fail,+ started: false,+ finished: false,+ };+ return state;+}++function watch<T>(promise: Promise<T>): { promise: Promise<T>; done: () => boolean } {+ let done = false;+ const observed = promise.then((value) => {+ done = true;+ return value;+ });+ return { promise: observed, done: () => done };+}++async function flushMicrotasks(): Promise<void> {+ for (let i = 0; i < 20; i++) await Promise.resolve();+}++function raceAgainstDelay<T>(promise: Promise<T>, ms: number): Promise<T | 'blocked'> {+ return Promise.race([+ promise,+ new Promise<'blocked'>((resolve) => {+ setTimeout(() => resolve('blocked'), ms);+ }),+ ]);+}++beforeEach(async () => {+ vi.resetModules();+ ({ queueDescription, drainDescriptions } = await import('../description-queue'));+});++afterEach(() => {+ vi.useRealTimers();+});++describe('description queue', () => {+ it('resolves immediately for a guide with nothing queued', async () => {+ vi.useFakeTimers();++ await expect(drainDescriptions('guide-a')).resolves.toBeUndefined();+ });++ it('resolves immediately for a guide whose tasks all settled earlier', async () => {+ const first = job();+ queueDescription('guide-a', first.run);+ first.settle();+ await drainDescriptions('guide-a');++ vi.useFakeTimers();++ await expect(drainDescriptions('guide-a')).resolves.toBeUndefined();+ });++ it('waits for the guide task to settle before resolving', async () => {+ const only = job();+ queueDescription('guide-a', only.run);++ const drain = watch(drainDescriptions('guide-a'));+ await flushMicrotasks();+ expect(only.started).toBe(true);+ expect(drain.done()).toBe(false);++ only.settle();+ await drain.promise;++ expect(drain.done()).toBe(true);+ });++ it('runs one task at a time and waits for every task belonging to the guide', async () => {+ const first = job();+ const second = job();+ queueDescription('guide-a', first.run);+ queueDescription('guide-a', second.run);++ const drain = watch(drainDescriptions('guide-a'));+ await flushMicrotasks();+ expect(second.started).toBe(false);++ first.settle();+ await flushMicrotasks();+ expect(second.started).toBe(true);+ expect(drain.done()).toBe(false);++ second.settle();+ await drain.promise;++ expect(first.finished).toBe(true);+ expect(second.finished).toBe(true);+ });++ it('resolves for one guide while another guide still has work in flight', async () => {+ const forA = job();+ const forB = job();+ queueDescription('guide-a', forA.run);+ queueDescription('guide-b', forB.run);++ const drain = watch(drainDescriptions('guide-a'));+ await flushMicrotasks();+ expect(drain.done()).toBe(false);++ forA.settle();++ await expect(+ raceAgainstDelay(+ drain.promise.then(() => 'drained' as const),+ 200,+ ),+ ).resolves.toBe('drained');+ expect(forB.finished).toBe(false);++ forB.settle();+ await drainDescriptions('guide-b');+ });++ it('resolves for one guide while another guide still has work queued behind it', async () => {+ const forA = job();+ const forB = job();+ queueDescription('guide-b', forB.run);+ queueDescription('guide-a', forA.run);+ const stillQueued = job();++ const drain = watch(drainDescriptions('guide-a'));+ await flushMicrotasks();+ expect(forA.started).toBe(false);++ forB.settle();+ await flushMicrotasks();+ queueDescription('guide-b', stillQueued.run);+ forA.settle();++ await expect(+ raceAgainstDelay(+ drain.promise.then(() => 'drained' as const),+ 200,+ ),+ ).resolves.toBe('drained');+ expect(stillQueued.finished).toBe(false);++ stillQueued.settle();+ await drainDescriptions('guide-b');+ });++ it('swallows a failing task so the drain still resolves', async () => {+ const failing = job();+ queueDescription('guide-a', failing.run);++ const drain = watch(drainDescriptions('guide-a'));+ await flushMicrotasks();+ failing.fail(new Error('model unreachable'));++ await expect(drain.promise).resolves.toBeUndefined();+ });++ it('gives up after the twenty second cap when a task never settles', async () => {+ vi.useFakeTimers();+ const stuck = job();+ queueDescription('guide-a', stuck.run);++ const drain = watch(drainDescriptions('guide-a'));+ await vi.advanceTimersByTimeAsync(19_999);+ expect(drain.done()).toBe(false);++ await vi.advanceTimersByTimeAsync(1);++ await expect(drain.promise).resolves.toBeUndefined();+ expect(stuck.finished).toBe(false);+ });++ it('leaves no cap timer behind once the tasks settle on their own', async () => {+ vi.useFakeTimers();+ const only = job();+ queueDescription('guide-a', only.run);++ const drain = watch(drainDescriptions('guide-a'));+ await flushMicrotasks();+ expect(vi.getTimerCount()).toBeGreaterThan(0);++ only.settle();+ await drain.promise;+ await flushMicrotasks();++ expect(vi.getTimerCount()).toBe(0);+ });+});diff --git a/src/entrypoints/background/__tests__/guide-meta.test.ts b/src/entrypoints/background/__tests__/guide-meta.test.tsindex fa3d8f7..2c4eb59 100644--- a/src/entrypoints/background/__tests__/guide-meta.test.ts+++ b/src/entrypoints/background/__tests__/guide-meta.test.ts@@ -1,6 +1,7 @@import { beforeEach, describe, expect, it, vi } from 'vitest';const {+ clearStepAiPendingMock,generateGuideMetaMock,getGuideDomainMock,getStepsForGuideMock,@@ -8,6 +9,7 @@ const {updateGuideDescriptionMock,updateGuideTitleMock,} = vi.hoisted(() => ({+ clearStepAiPendingMock: vi.fn(),generateGuideMetaMock: vi.fn(),getGuideDomainMock: vi.fn(),getStepsForGuideMock: vi.fn(),@@ -19,6 +21,7 @@ const {vi.mock('@/core/capture/ai/meta', () => ({ generateGuideMeta: generateGuideMetaMock }));vi.mock('@/core/guides/service', () => ({+ clearStepAiPending: clearStepAiPendingMock,getGuideDomain: getGuideDomainMock,getStepsForGuide: getStepsForGuideMock,updateGuideDescription: updateGuideDescriptionMock,