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(export): cover video frame composition, cards and abort handling

Luis Ortizfe39bf7afefd
diff --git a/src/core/export/__tests__/video-export-encode.test.ts b/src/core/export/__tests__/video-export-encode.test.ts
new file mode 100644
index 0000000..c24dd90
--- /dev/null
+++ b/src/core/export/__tests__/video-export-encode.test.ts
@@ -0,0 +1,431 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ExportOptions } from '@/core/export/options';
+import { DEFAULT_EXPORT_OPTIONS } from '@/core/export/options';
+import type { Guide, Screenshot, Step } from '@/core/guides/types';
+
+const rec = vi.hoisted(() => ({
+ calls: [] as { m: string; a: unknown[] }[],
+ added: [] as { at: number; dur: number }[],
+ closed: 0,
+ container: 'mp4' as 'mp4' | 'webm' | null,
+ probed: [] as string[],
+ started: 0,
+ finalized: 0,
+ cancelled: 0,
+ buffer: true,
+}));
+
+const branding = vi.hoisted(() => ({
+ value: {
+ logo: null as null | { dataUrl: string; width: number; height: number },
+ footer: '',
+ attribution: false,
+ accent: '#4F46E5',
+ custom: false,
+ },
+}));
+
+function fakeCtx() {
+ const store: Record<string, unknown> = { filter: 'none' };
+ const base: Record<string, unknown> = {
+ canvas: { width: 1280, height: 720 },
+ measureText: (t: unknown) => ({ width: String(t).length * 8 }),
+ };
+ return new Proxy(base, {
+ has: () => true,
+ get(target, key) {
+ const k = String(key);
+ if (k in target) return target[k];
+ if (k in store) return store[k];
+ return (...a: unknown[]) => {
+ rec.calls.push({ m: k, a });
+ };
+ },
+ set(_target, key, value) {
+ store[String(key)] = value;
+ rec.calls.push({ m: `set:${String(key)}`, a: [value] });
+ return true;
+ },
+ }) as unknown as CanvasRenderingContext2D;
+}
+
+vi.mock('mediabunny', () => ({
+ QUALITY_HIGH: 'high',
+ Mp4OutputFormat: class {},
+ WebMOutputFormat: class {},
+ BufferTarget: class {
+ get buffer() {
+ return rec.buffer ? new ArrayBuffer(16) : null;
+ }
+ },
+ CanvasSource: class {
+ async add(at: number, dur: number) {
+ rec.added.push({ at, dur });
+ }
+ },
+ Output: class {
+ target: { buffer: ArrayBuffer | null };
+ constructor(o: { target: { buffer: ArrayBuffer | null } }) {
+ this.target = o.target;
+ }
+ addVideoTrack() {}
+ async start() {
+ rec.started += 1;
+ }
+ async finalize() {
+ rec.finalized += 1;
+ }
+ async cancel() {
+ rec.cancelled += 1;
+ }
+ },
+}));
+
+vi.mock('@/core/export/video-support', async () => {
+ const actual = await vi.importActual<typeof import('@/core/export/video-support')>('@/core/export/video-support');
+ return {
+ ...actual,
+ pickContainer: vi.fn(async (r = '720p') => {
+ rec.probed.push(r);
+ return rec.container;
+ }),
+ };
+});
+
+vi.mock('@/core/screenshot/render', () => ({
+ renderScreenshot: vi.fn(async () => new Blob(['webp'])),
+}));
+
+vi.mock('@/core/export/branding', async () => {
+ const actual = await vi.importActual<typeof import('@/core/export/branding')>('@/core/export/branding');
+ return { ...actual, loadBranding: vi.fn(async () => branding.value) };
+});
+
+const { exportGuideAsVideo } = await import('@/core/export/video-export');
+const { renderScreenshot } = await import('@/core/screenshot/render');
+const { FPS } = await import('@/core/export/video-support');
+
+const guide: Guide = {
+ id: 'g1',
+ title: 'Reset your password',
+ createdAt: new Date('2026-03-04T10:00:00Z').getTime(),
+ updatedAt: new Date('2026-03-04T10:00:00Z').getTime(),
+ stepIds: [],
+ starred: false,
+ deletedAt: null,
+};
+
+function makeStep(i: number, overrides: Partial<Step> = {}): Step {
+ return {
+ id: `s${i}`,
+ guideId: 'g1',
+ index: i,
+ description: `Click the button labelled ${i}`,
+ action: 'click',
+ url: 'https://example.com/settings',
+ timestamp: guide.createdAt,
+ screenshotId: `shot-${i}`,
+ ...overrides,
+ };
+}
+
+function makeShot(stepId: string, overrides: Partial<Screenshot> = {}): Screenshot {
+ return {
+ id: `shot-${stepId}`,
+ stepId,
+ blob: new Blob(['raw']),
+ mimeType: 'image/webp',
+ width: 1280,
+ height: 720,
+ bounds: { x: 100, y: 200, width: 120, height: 40 },
+ pixelRatio: 1,
+ ...overrides,
+ };
+}
+
+function shotsFor(steps: Step[]): Map<string, Screenshot> {
+ return new Map(steps.filter((s) => !s.blockType).map((s) => [s.id, makeShot(s.id)]));
+}
+
+const opts = (o: Partial<ExportOptions> = {}): ExportOptions => ({ ...DEFAULT_EXPORT_OPTIONS, ...o });
+
+beforeEach(() => {
+ rec.calls = [];
+ rec.added = [];
+ rec.closed = 0;
+ rec.container = 'mp4';
+ rec.probed = [];
+ rec.started = 0;
+ rec.finalized = 0;
+ rec.cancelled = 0;
+ rec.buffer = true;
+ branding.value = { logo: null, footer: '', attribution: false, accent: '#4F46E5', custom: false };
+ vi.mocked(renderScreenshot).mockClear();
+ vi.mocked(renderScreenshot).mockResolvedValue(new Blob(['webp']));
+
+ class FakeOffscreen {
+ constructor(
+ public width: number,
+ public height: number,
+ ) {}
+ getContext() {
+ return fakeCtx();
+ }
+ }
+ vi.stubGlobal('OffscreenCanvas', FakeOffscreen);
+ vi.stubGlobal(
+ 'createImageBitmap',
+ vi.fn(async () => ({
+ width: 1280,
+ height: 720,
+ close: () => {
+ rec.closed += 1;
+ },
+ })),
+ );
+ vi.stubGlobal('document', {
+ createElement: () => ({ width: 0, height: 0, getContext: () => fakeCtx() }),
+ });
+});
+
+describe('exportGuideAsVideo guards', () => {
+ it('refuses a guide with nothing to show', async () => {
+ await expect(exportGuideAsVideo(guide, [makeStep(0)], new Map(), opts())).rejects.toThrow(/no screenshots/i);
+ });
+
+ it('refuses when the browser cannot encode at all', async () => {
+ rec.container = null;
+ const steps = [makeStep(0)];
+ await expect(exportGuideAsVideo(guide, steps, shotsFor(steps), opts())).rejects.toThrow(/cannot encode/i);
+ });
+
+ it('fails when encoding yields no buffer', async () => {
+ rec.buffer = false;
+ const steps = [makeStep(0)];
+ await expect(exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }))).rejects.toThrow(
+ /no output/i,
+ );
+ });
+});
+
+describe('exportGuideAsVideo output', () => {
+ it('produces an mp4 when the container is available', async () => {
+ const steps = [makeStep(0)];
+ const result = await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ expect(result.extension).toBe('mp4');
+ expect(result.blob.type).toBe('video/mp4');
+ expect(result.blob).toBeInstanceOf(Blob);
+ });
+
+ it('falls back to webm when mp4 is unavailable', async () => {
+ rec.container = 'webm';
+ const steps = [makeStep(0)];
+ const result = await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ expect(result.extension).toBe('webm');
+ expect(result.blob.type).toBe('video/webm');
+ });
+
+ it('starts and finalizes the output exactly once', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ expect(rec.started).toBe(1);
+ expect(rec.finalized).toBe(1);
+ expect(rec.cancelled).toBe(0);
+ });
+
+ it('returns chapters describing the timeline', async () => {
+ const steps = [makeStep(0), makeStep(1)];
+ const result = await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ expect(result.chapters.length).toBeGreaterThan(0);
+ expect(result.chapters[0]).toHaveProperty('title');
+ });
+
+ it('emits one encoded segment per frame at the frame rate', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ expect(rec.added.length).toBeGreaterThan(FPS);
+ expect(rec.added.every((s) => s.dur === 1 / FPS)).toBe(true);
+ expect(rec.added[0].at).toBe(0);
+ });
+
+ it('falls back to 720p when the requested resolution cannot be encoded', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false, resolution: '1080p' }));
+
+ expect(rec.probed[0]).toBe('1080p');
+ });
+});
+
+describe('exportGuideAsVideo cover cards', () => {
+ it('brackets the steps with an opening and closing card', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: true }));
+
+ const holds = rec.added.filter((s) => s.dur === 3);
+ expect(holds.length).toBe(2);
+ expect(holds[0].at).toBe(0);
+ });
+
+ it('offsets the step frames past the opening card', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: true }));
+
+ const stepSegments = rec.added.filter((s) => s.dur === 1 / FPS);
+ expect(stepSegments[0].at).toBe(3);
+ });
+
+ it('adds no cards when the cover is off', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ expect(rec.added.filter((s) => s.dur === 3).length).toBe(0);
+ });
+
+ it('draws the brand logo on the card when one is set', async () => {
+ branding.value = { ...branding.value, logo: { dataUrl: 'data:image/png;base64,AAA', width: 80, height: 30 } };
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: true }));
+
+ expect(rec.calls.some((c) => c.m === 'drawImage')).toBe(true);
+ });
+});
+
+describe('exportGuideAsVideo progress and abort', () => {
+ it('reports progress that ends on the total', async () => {
+ const steps = [makeStep(0)];
+ const seen: [number, number][] = [];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: true }), {
+ onProgress: (done, total) => seen.push([done, total]),
+ });
+
+ expect(seen.length).toBeGreaterThan(0);
+ const [done, total] = seen[seen.length - 1];
+ expect(done).toBe(total);
+ });
+
+ it('counts both cards into the total', async () => {
+ const steps = [makeStep(0)];
+ const seen: [number, number][] = [];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: true }), {
+ onProgress: (done, total) => seen.push([done, total]),
+ });
+ const withCover = seen[0][1];
+
+ seen.length = 0;
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }), {
+ onProgress: (done, total) => seen.push([done, total]),
+ });
+
+ expect(withCover - seen[0][1]).toBe(2);
+ });
+
+ it('aborts before any encoding when the signal is already set', async () => {
+ const controller = new AbortController();
+ controller.abort();
+ const steps = [makeStep(0)];
+
+ await expect(
+ exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }), { signal: controller.signal }),
+ ).rejects.toThrow(/aborted/i);
+ });
+
+ it('cancels the output when aborted', async () => {
+ const controller = new AbortController();
+ controller.abort();
+ const steps = [makeStep(0)];
+
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }), {
+ signal: controller.signal,
+ }).catch(() => undefined);
+
+ expect(rec.cancelled).toBe(1);
+ expect(rec.finalized).toBe(0);
+ });
+
+ it('releases every decoded bitmap even when it aborts', async () => {
+ const controller = new AbortController();
+ const steps = [makeStep(0), makeStep(1)];
+ let ticks = 0;
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }), {
+ signal: controller.signal,
+ onProgress: () => {
+ ticks += 1;
+ if (ticks === 5) controller.abort();
+ },
+ }).catch(() => undefined);
+
+ expect(rec.closed).toBeGreaterThan(0);
+ });
+});
+
+describe('exportGuideAsVideo layers', () => {
+ it('renders each screenshot once and reuses the decoded frame', async () => {
+ const steps = [makeStep(0), makeStep(1)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ expect(renderScreenshot).toHaveBeenCalledTimes(2);
+ });
+
+ it('renders the screenshot without the baked target outline', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ expect(vi.mocked(renderScreenshot).mock.calls[0][1]).toMatchObject({ target: false });
+ });
+
+ it('drops step descriptions when the option is off', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false, stepDescriptions: false }));
+
+ const written = rec.calls.filter((c) => c.m === 'fillText').flatMap((c) => String(c.a[0]));
+ expect(written.some((t) => t.includes('Click the button labelled'))).toBe(false);
+ });
+
+ it('writes the step description into the tooltip when the option is on', async () => {
+ const steps = [makeStep(0)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false, stepDescriptions: true }));
+
+ const written = rec.calls.filter((c) => c.m === 'fillText').flatMap((c) => String(c.a[0]));
+ expect(written.some((t) => t.includes('Click the button labelled'))).toBe(true);
+ });
+
+ it('renders a block step over a blurred backdrop of the previous screenshot', async () => {
+ const steps = [makeStep(0), makeStep(1, { blockType: 'heading', description: 'Part two' })];
+ const shots = shotsFor(steps);
+ await exportGuideAsVideo(guide, steps, shots, opts({ cover: false }));
+
+ expect(renderScreenshot).toHaveBeenCalledTimes(2);
+ const written = rec.calls.filter((c) => c.m === 'fillText').flatMap((c) => String(c.a[0]));
+ expect(written.some((t) => t.includes('Part two'))).toBe(true);
+ });
+
+ it('renders a leading block step with no backdrop behind it', async () => {
+ const steps = [makeStep(0, { blockType: 'callout', description: 'Heads up' }), makeStep(1)];
+ const shots = shotsFor(steps);
+ await exportGuideAsVideo(guide, steps, shots, opts({ cover: false }));
+
+ const written = rec.calls.filter((c) => c.m === 'fillText').flatMap((c) => String(c.a[0]));
+ expect(written.some((t) => t.includes('Heads up'))).toBe(true);
+ });
+
+ it('handles a screenshot with no click target', async () => {
+ const steps = [makeStep(0)];
+ const shots = new Map([['s0', makeShot('s0', { bounds: undefined })]]);
+ const result = await exportGuideAsVideo(guide, steps, shots, opts({ cover: false }));
+
+ expect(result.blob).toBeInstanceOf(Blob);
+ });
+
+ it('cross dissolves between consecutive steps', async () => {
+ const steps = [makeStep(0), makeStep(1)];
+ await exportGuideAsVideo(guide, steps, shotsFor(steps), opts({ cover: false }));
+
+ const alphas = rec.calls.filter((c) => c.m === 'set:globalAlpha').map((c) => c.a[0] as number);
+ expect(alphas.some((a) => a > 0 && a < 1)).toBe(true);
+ });
+});