π¬ 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(screenshot): cover the export redraw, annotations and redactions
Luis Ortizbb4d6b8873bd
diff --git a/src/core/screenshot/__tests__/draw.test.ts b/src/core/screenshot/__tests__/draw.test.tsnew file mode 100644index 0000000..748f4cd--- /dev/null+++ b/src/core/screenshot/__tests__/draw.test.ts@@ -0,0 +1,339 @@+import { describe, expect, it } from 'vitest';+import { type Ctx, drawAnnotation, drawRoundedRect, TARGET_RADIUS, TARGET_STROKE } from '@/core/screenshot/draw';+import { type Annotation, DEFAULT_LINE_HEIGHT, FONT_FAMILIES, LINE_WIDTHS } from '@/core/screenshot/types';++interface Call {+ m: string;+ a: unknown[];+}++const TRACKED = ['lineWidth', 'strokeStyle', 'fillStyle', 'lineCap', 'lineJoin', 'font', 'filter'];++const METHODS = [+ 'beginPath',+ 'closePath',+ 'moveTo',+ 'lineTo',+ 'arcTo',+ 'arc',+ 'rect',+ 'ellipse',+ 'stroke',+ 'fill',+ 'fillRect',+ 'fillText',+ 'drawImage',+ 'save',+ 'restore',+ 'translate',+ 'rotate',+ 'setLineDash',+];++function recorder() {+ const calls: Call[] = [];+ const state: Record<string, unknown> = {};+ const ctx: Record<string, unknown> = { canvas: { width: 800, height: 600 } };++ for (const m of METHODS) {+ ctx[m] = (...a: unknown[]) => {+ calls.push({ m, a });+ };+ }+ for (const p of TRACKED) {+ Object.defineProperty(ctx, p, {+ get: () => state[p],+ set: (v: unknown) => {+ state[p] = v;+ calls.push({ m: `set:${p}`, a: [v] });+ },+ });+ }++ return {+ ctx: ctx as unknown as Ctx,+ calls,+ names: () => calls.map((c) => c.m),+ first: (m: string) => calls.find((c) => c.m === m)?.a,+ all: (m: string) => calls.filter((c) => c.m === m).map((c) => c.a),+ count: (m: string) => calls.filter((c) => c.m === m).length,+ };+}++describe('drawRoundedRect', () => {+ it('emits a closed path of four corner arcs', () => {+ const r = recorder();+ drawRoundedRect(r.ctx, 10, 20, 100, 50, 8);++ expect(r.names()).toEqual(['beginPath', 'moveTo', 'arcTo', 'arcTo', 'arcTo', 'arcTo', 'closePath']);+ expect(r.first('moveTo')).toEqual([18, 20]);+ expect(r.all('arcTo')[0]).toEqual([110, 20, 110, 70, 8]);+ });+});++describe('drawAnnotation redact', () => {+ it('paints an opaque rectangle for a solid redaction', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { id: 'r1', type: 'redact', style: 'solid', x: 40, y: 50, w: 120, h: 30 }, 0, 0);++ expect(r.first('set:fillStyle')).toEqual(['#1E1B4B']);+ expect(r.first('fillRect')).toEqual([40, 50, 120, 30]);+ expect(r.count('drawImage')).toBe(0);+ });++ it('blurs by resampling the canvas over itself', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { id: 'r2', type: 'redact', style: 'blur', x: 40, y: 50, w: 120, h: 30 }, 0, 0);++ expect(r.first('set:filter')).toEqual(['blur(12px)']);+ expect(r.first('drawImage')).toEqual([{ width: 800, height: 600 }, 40, 50, 120, 30, 40, 50, 120, 30]);+ expect(r.count('fillRect')).toBe(0);+ });++ it('offsets the blur source by the viewport origin so a cropped export blurs the same pixels', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { id: 'r3', type: 'redact', style: 'blur', x: 300, y: 220, w: 80, h: 40 }, 100, 60);++ const [, sx, sy, sw, sh, dx, dy, dw, dh] = r.first('drawImage') as number[];+ expect([sx, sy]).toEqual([200, 160]);+ expect([dx, dy]).toEqual([300, 220]);+ expect([sw, sh, dw, dh]).toEqual([80, 40, 80, 40]);+ });++ it('leaves the origin out of a solid redaction, which is drawn in destination space', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { id: 'r4', type: 'redact', style: 'solid', x: 300, y: 220, w: 80, h: 40 }, 100, 60);++ expect(r.first('fillRect')).toEqual([300, 220, 80, 40]);+ });++ it('balances save and restore so a redaction cannot leak its filter onto later annotations', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { id: 'r5', type: 'redact', style: 'blur', x: 0, y: 0, w: 10, h: 10 }, 0, 0);++ expect(r.count('save')).toBe(1);+ expect(r.count('restore')).toBe(1);+ expect(r.names().at(0)).toBe('save');+ expect(r.names().at(-1)).toBe('restore');+ });+});++describe('drawAnnotation box', () => {+ const base = { id: 'b', type: 'box', x: 5, y: 6, w: 70, h: 40, color: '#EF4444' } as const;++ it('strokes without filling when the fill is transparent', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, fill: 'transparent' }, 0, 0);++ expect(r.count('fill')).toBe(0);+ expect(r.count('stroke')).toBe(1);+ expect(r.first('set:strokeStyle')).toEqual(['#EF4444']);+ });++ it('fills and strokes when a fill colour is set', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, fill: '#FACC15' }, 0, 0);++ expect(r.first('set:fillStyle')).toEqual(['#FACC15']);+ expect(r.count('fill')).toBe(1);+ expect(r.count('stroke')).toBe(1);+ });++ it('skips the stroke when the line width is none', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, lineWidth: 'none', fill: '#FACC15' }, 0, 0);++ expect(r.count('fill')).toBe(1);+ expect(r.count('stroke')).toBe(0);+ });++ it('defaults the line width to ms', () => {+ const r = recorder();+ drawAnnotation(r.ctx, base, 0, 0);++ expect(r.first('set:lineWidth')).toEqual([LINE_WIDTHS.ms]);+ });++ it('honours an explicit corner radius', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, radius: 14 }, 0, 0);++ expect(r.first('moveTo')).toEqual([base.x + 14, base.y]);+ });+});++describe('drawAnnotation ellipse', () => {+ it('centres the ellipse in its bounding box and uses absolute radii', () => {+ const r = recorder();+ drawAnnotation(+ r.ctx,+ { id: 'e', type: 'ellipse', x: 10, y: 20, w: -60, h: 40, color: '#22C55E', fill: 'transparent' },+ 0,+ 0,+ );++ expect(r.first('ellipse')).toEqual([-20, 40, 30, 20, 0, 0, Math.PI * 2]);+ expect(r.count('fill')).toBe(0);+ expect(r.count('stroke')).toBe(1);+ });++ it('fills before stroking when given a fill', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { id: 'e', type: 'ellipse', x: 0, y: 0, w: 10, h: 10, color: '#000', fill: '#FFF' }, 0, 0);++ expect(r.names().indexOf('fill')).toBeLessThan(r.names().indexOf('stroke'));+ });+});++describe('drawAnnotation target', () => {+ const base = { id: 't', type: 'target', x: 12, y: 14, w: 200, h: 90, color: '#4F46E5' } as const;++ it('dashes the outline when the border is dashed', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, border: 'dashed' }, 0, 0);++ expect(r.first('setLineDash')).toEqual([[8, 5]]);+ expect(r.first('set:lineWidth')).toEqual([TARGET_STROKE]);+ expect(r.first('moveTo')).toEqual([base.x + TARGET_RADIUS, base.y]);+ });++ it('leaves the outline solid when the border is solid', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, border: 'solid' }, 0, 0);++ expect(r.count('setLineDash')).toBe(0);+ expect(r.count('stroke')).toBe(1);+ });+});++describe('drawAnnotation arrow', () => {+ const base = { id: 'a', type: 'arrow', x1: 0, y1: 0, x2: 100, y2: 0, color: '#2563EB' } as const;++ it('draws the shaft between both points', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, end: 'none' }, 0, 0);++ expect(r.first('moveTo')).toEqual([0, 0]);+ expect(r.first('lineTo')).toEqual([100, 0]);+ expect(r.count('translate')).toBe(0);+ });++ it('rotates the head to the shaft angle', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, x2: 0, y2: 100, end: 'arrow' }, 0, 0);++ expect(r.first('translate')).toEqual([0, 100]);+ expect(r.first('rotate')).toEqual([Math.PI / 2]);+ });++ it.each([+ ['bar', { stroke: 1, fill: 0 }],+ ['arrow', { stroke: 1, fill: 0 }],+ ['arrow-solid', { stroke: 0, fill: 1 }],+ ['circle', { stroke: 1, fill: 0 }],+ ['circle-solid', { stroke: 0, fill: 1 }],+ ['square', { stroke: 1, fill: 0 }],+ ['square-solid', { stroke: 0, fill: 1 }],+ ] as const)('renders the %s head', (end, expected) => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, end }, 0, 0);++ expect(r.count('stroke') - 1).toBe(expected.stroke);+ expect(r.count('fill')).toBe(expected.fill);+ });++ it('defaults to a solid arrow head', () => {+ const r = recorder();+ drawAnnotation(r.ctx, base, 0, 0);++ expect(r.count('fill')).toBe(1);+ });+});++describe('drawAnnotation text', () => {+ const base = { id: 'x', type: 'text', x: 20, y: 40, text: 'Hello', color: '#000', size: 32 } as const;++ it('writes one line at the anchor', () => {+ const r = recorder();+ drawAnnotation(r.ctx, base, 0, 0);++ expect(r.all('fillText')).toEqual([['Hello', 20, 40]]);+ });++ it('stacks each newline by the line height', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, text: 'a\nb\nc' }, 0, 0);++ const step = 32 * DEFAULT_LINE_HEIGHT;+ expect(r.all('fillText')).toEqual([+ ['a', 20, 40],+ ['b', 20, 40 + step],+ ['c', 20, 40 + 2 * step],+ ]);+ });++ it('honours an explicit line height', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, text: 'a\nb', lineHeight: 2 }, 0, 0);++ expect(r.all('fillText')[1]).toEqual(['b', 20, 40 + 64]);+ });++ it('composes weight, slant and family into the font string', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { ...base, bold: true, italic: true, fontFamily: 'serif' }, 0, 0);++ expect(r.first('set:font')).toEqual([`italic 700 32px ${FONT_FAMILIES.serif}`]);+ });++ it('defaults to medium weight, upright, sans-serif', () => {+ const r = recorder();+ drawAnnotation(r.ctx, base, 0, 0);++ expect(r.first('set:font')).toEqual([`500 32px ${FONT_FAMILIES['sans-serif']}`]);+ });+});++describe('drawAnnotation freehand', () => {+ it('traces every point pair in order', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { id: 'f', type: 'freehand', points: [1, 2, 3, 4, 5, 6], color: '#EC4899' }, 0, 0);++ expect(r.first('moveTo')).toEqual([1, 2]);+ expect(r.all('lineTo')).toEqual([+ [3, 4],+ [5, 6],+ ]);+ });++ it('defaults the stroke to md and rounds the joins', () => {+ const r = recorder();+ drawAnnotation(r.ctx, { id: 'f', type: 'freehand', points: [0, 0, 1, 1], color: '#000' }, 0, 0);++ expect(r.first('set:lineWidth')).toEqual([LINE_WIDTHS.md]);+ expect(r.first('set:lineJoin')).toEqual(['round']);+ expect(r.first('set:lineCap')).toEqual(['round']);+ });+});++describe('drawAnnotation state isolation', () => {+ const each: Annotation[] = [+ { id: '1', type: 'box', x: 0, y: 0, w: 1, h: 1, color: '#000' },+ { id: '2', type: 'ellipse', x: 0, y: 0, w: 1, h: 1, color: '#000' },+ { id: '3', type: 'target', x: 0, y: 0, w: 1, h: 1, color: '#000', border: 'dashed' },+ { id: '4', type: 'arrow', x1: 0, y1: 0, x2: 1, y2: 1, color: '#000' },+ { id: '5', type: 'text', x: 0, y: 0, text: 'a', color: '#000', size: 12 },+ { id: '6', type: 'freehand', points: [0, 0, 1, 1], color: '#000' },+ { id: '7', type: 'redact', x: 0, y: 0, w: 1, h: 1, style: 'solid' },+ { id: '8', type: 'redact', x: 0, y: 0, w: 1, h: 1, style: 'blur' },+ ];++ it.each(each.map((a) => [`${a.type}:${a.id}`, a] as const))('balances save and restore for %s', (_label, a) => {+ const r = recorder();+ drawAnnotation(r.ctx, a, 0, 0);++ expect(r.count('save')).toBe(r.count('restore'));+ expect(r.names().at(0)).toBe('save');+ expect(r.names().at(-1)).toBe('restore');+ });+});diff --git a/src/core/screenshot/__tests__/render.test.ts b/src/core/screenshot/__tests__/render.test.tsnew file mode 100644index 0000000..9459b9c--- /dev/null+++ b/src/core/screenshot/__tests__/render.test.ts@@ -0,0 +1,228 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';+import type { Screenshot } from '@/core/guides/types';+import type { Annotation } from '@/core/screenshot/types';+import { DEFAULT_TARGET_COLOR } from '@/core/screenshot/types';++const drawAnnotation = vi.hoisted(() => vi.fn());+vi.mock('@/core/screenshot/draw', () => ({ drawAnnotation }));++const { imageDimensions, renderScreenshot } = await import('@/core/screenshot/render');++interface Call {+ m: string;+ a: unknown[];+}++let calls: Call[] = [];+let closed = 0;+let canvases: FakeCanvas[] = [];+let convertArgs: unknown[] = [];++class FakeCanvas {+ ctx: Record<string, unknown>;++ constructor(+ public width: number,+ public height: number,+ ) {+ canvases.push(this);+ const record =+ (m: string) =>+ (...a: unknown[]) => {+ calls.push({ m, a });+ };+ this.ctx = {+ canvas: this,+ drawImage: record('drawImage'),+ translate: record('translate'),+ save: record('save'),+ restore: record('restore'),+ };+ }++ getContext() {+ return this.ctx;+ }++ convertToBlob(opts: unknown) {+ convertArgs.push(opts);+ return Promise.resolve(new Blob(['out']));+ }+}++function makeScreenshot(overrides: Partial<Screenshot> = {}): Screenshot {+ return {+ id: 'ss-1',+ stepId: 'step-1',+ blob: new Blob(['raw']),+ mimeType: 'image/png',+ width: 1200,+ height: 900,+ ...overrides,+ };+}++beforeEach(() => {+ calls = [];+ canvases = [];+ convertArgs = [];+ closed = 0;+ drawAnnotation.mockClear();+ vi.stubGlobal(+ 'createImageBitmap',+ vi.fn(async () => ({+ width: 1200,+ height: 900,+ close: () => {+ closed += 1;+ },+ })),+ );+ vi.stubGlobal('OffscreenCanvas', FakeCanvas);+});++describe('imageDimensions', () => {+ it('reads the bitmap size and releases it', async () => {+ await expect(imageDimensions(new Blob(['x']))).resolves.toEqual({ width: 1200, height: 900 });+ expect(closed).toBe(1);+ });+});++describe('renderScreenshot', () => {+ it('sizes the canvas to the full image when there is no crop', async () => {+ await renderScreenshot(makeScreenshot());++ expect(canvases[0].width).toBe(1200);+ expect(canvases[0].height).toBe(900);+ });++ it('rounds a fractional viewport to whole pixels', async () => {+ const s = makeScreenshot({ edits: { viewport: { x: 10, y: 20, width: 640.6, height: 480.2 } } });+ await renderScreenshot(s);++ expect(canvases[0].width).toBe(641);+ expect(canvases[0].height).toBe(480);+ });++ it('maps the viewport rectangle onto the whole canvas', async () => {+ const s = makeScreenshot({ edits: { viewport: { x: 100, y: 50, width: 600, height: 400 } } });+ await renderScreenshot(s);++ const [, sx, sy, sw, sh, dx, dy, dw, dh] = calls.find((c) => c.m === 'drawImage')?.a as number[];+ expect([sx, sy, sw, sh]).toEqual([100, 50, 600, 400]);+ expect([dx, dy, dw, dh]).toEqual([0, 0, 600, 400]);+ });++ it('shifts the origin so annotations can use full image coordinates', async () => {+ const s = makeScreenshot({ edits: { viewport: { x: 100, y: 50, width: 600, height: 400 } } });+ await renderScreenshot(s);++ expect(calls.find((c) => c.m === 'translate')?.a).toEqual([-100, -50]);+ });++ it('releases the bitmap after drawing it', async () => {+ await renderScreenshot(makeScreenshot());++ expect(closed).toBe(1);+ });++ it('defaults to webp at 0.85', async () => {+ await renderScreenshot(makeScreenshot());++ expect(convertArgs[0]).toEqual({ type: 'image/webp', quality: 0.85 });+ });++ it('honours an explicit format and quality', async () => {+ await renderScreenshot(makeScreenshot(), { format: 'image/jpeg', quality: 0.5 });++ expect(convertArgs[0]).toEqual({ type: 'image/jpeg', quality: 0.5 });+ });++ it('returns the encoded blob', async () => {+ await expect(renderScreenshot(makeScreenshot())).resolves.toBeInstanceOf(Blob);+ });+});++describe('renderScreenshot click target', () => {+ const bounded = () => makeScreenshot({ bounds: { x: 30, y: 40, width: 120, height: 60 }, pixelRatio: 2 });++ it('outlines the click target derived from bounds and pixel ratio', async () => {+ await renderScreenshot(bounded());++ expect(drawAnnotation).toHaveBeenCalledTimes(1);+ expect(drawAnnotation.mock.calls[0][1]).toEqual({+ id: 'target',+ type: 'target',+ x: 60,+ y: 80,+ w: 240,+ h: 120,+ color: DEFAULT_TARGET_COLOR,+ border: 'dashed',+ });+ });++ it('skips the outline when the caller opts out', async () => {+ await renderScreenshot(bounded(), { target: false });++ expect(drawAnnotation).not.toHaveBeenCalled();+ });++ it('draws no outline when the screenshot has no bounds', async () => {+ await renderScreenshot(makeScreenshot());++ expect(drawAnnotation).not.toHaveBeenCalled();+ });++ it('prefers an explicit edited target over the captured bounds', async () => {+ const s = makeScreenshot({+ bounds: { x: 30, y: 40, width: 120, height: 60 },+ edits: { target: { x: 5, y: 6, width: 7, height: 8, border: 'solid', color: '#F43F5E' } },+ });+ await renderScreenshot(s);++ expect(drawAnnotation.mock.calls[0][1]).toMatchObject({ x: 5, y: 6, w: 7, h: 8, border: 'solid' });+ });++ it('honours an edited target that was cleared', async () => {+ const s = makeScreenshot({ bounds: { x: 30, y: 40, width: 120, height: 60 }, edits: { target: null } });+ await renderScreenshot(s);++ expect(drawAnnotation).not.toHaveBeenCalled();+ });+});++describe('renderScreenshot annotations', () => {+ const annotations: Annotation[] = [+ { id: 'a1', type: 'box', x: 1, y: 2, w: 3, h: 4, color: '#000' },+ { id: 'a2', type: 'redact', x: 5, y: 6, w: 7, h: 8, style: 'blur' },+ ];++ it('draws every annotation in order after the target', async () => {+ const s = makeScreenshot({+ bounds: { x: 10, y: 10, width: 20, height: 20 },+ edits: { annotations },+ });+ await renderScreenshot(s);++ const ids = drawAnnotation.mock.calls.map((c) => (c[1] as Annotation).id);+ expect(ids).toEqual(['target', 'a1', 'a2']);+ });++ it('passes the viewport origin so a redaction lands on the right pixels', async () => {+ const s = makeScreenshot({+ edits: { viewport: { x: 100, y: 50, width: 600, height: 400 }, annotations },+ });+ await renderScreenshot(s);++ for (const call of drawAnnotation.mock.calls) {+ expect([call[2], call[3]]).toEqual([100, 50]);+ }+ });++ it('draws nothing extra when there are no annotations', async () => {+ await renderScreenshot(makeScreenshot({ edits: { annotations: [] } }));++ expect(drawAnnotation).not.toHaveBeenCalled();+ });+});