Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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,