The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, expect, it } from 'vitest';
import {
EXTENSION_SITES,
EXTENSION_TABS,
FIND_DOC,
FIXES,
SETTINGS_TABS,
JOURNEYS,
KEYMAP,
MENU,
MENU_ITEMS,
PAGES,
WORKSPACE_LEADS,
allShots,
journeysThrough,
landingFor,
opensFrom,
pinSpots,
shotOf,
stepMarks,
stepShot,
tabLabel,
} from './guide.js';
import { CASE_WORKSPACE, TOOL_LABELS, WORKSPACES } from './workspaces.js';
import { FIND_GUIDE } from './onboarding.js';
const RAIL_AND_CASE = [...WORKSPACES, CASE_WORKSPACE];
const TOOLS = RAIL_AND_CASE.flatMap((ws) => ws.tools);
/**
* Every component of the app, and the capture extension's pages and panel, as written:
* where an anchor the guide frames must stand.
*/
const EXTENSION = fileURLToPath(new URL('../../../extension/', import.meta.url));
const COMPONENTS = [
...Object.values(import.meta.glob('../**/*.svelte', { query: '?raw', import: 'default', eager: true })),
...readdirSync(EXTENSION)
.filter((name) => /\.(js|html)$/.test(name))
.map((name) => readFileSync(join(EXTENSION, name), 'utf8')),
].join('\n');
/** Every sentence the guide puts in front of a reader. */
function prose() {
const lines = [...Object.values(WORKSPACE_LEADS)];
const marks = (list) => {
for (const mark of list ?? []) {
lines.push(mark.title, mark.text);
if (mark.opens) {
lines.push(mark.opens.lead);
marks(mark.opens.marks);
for (const tip of mark.opens.tips ?? []) lines.push(tip.title, tip.text);
}
}
};
for (const page of Object.values(PAGES)) {
lines.push(page.lead);
marks(page.marks);
for (const tip of page.tips ?? []) lines.push(tip.title, tip.text);
}
for (const journey of JOURNEYS) lines.push(journey.title, journey.lead, ...journey.steps.map((step) => step.text));
return lines;
}
describe('the guide tracks the app rather than falling behind it', () => {
it('lists every workspace with its tools, in the order of the rail and the case after it', () => {
const tools = MENU.find((group) => group.title === 'Tools').items;
expect(tools.map((item) => item.id)).toEqual(RAIL_AND_CASE.map((ws) => ws.id));
for (const item of tools) {
expect(item.tools).toEqual(RAIL_AND_CASE.find((ws) => ws.id === item.id).tools);
expect(item.lead, `${item.id} says nothing about itself`).toBeTruthy();
}
});
it('has a page for every tool an analyst can stand in', () => {
// a tool that joins a workspace and has no page opens the guide on an empty tab
for (const tool of TOOLS) expect(PAGES[tool], `no guide page for ${tool}`).toBeTruthy();
});
it('pages nothing the app does not have', () => {
const own = new Set(['start', 'extension', 'extension-capture', 'extension-tools', ...SETTINGS_TABS.map((tab) => tab.id)]);
for (const id of Object.keys(PAGES)) expect(own.has(id) || TOOLS.includes(id), id).toBe(true);
});
it('opens on the start and the extension, before any journey or workspace', () => {
expect(MENU_ITEMS.slice(0, 2).map((item) => item.id)).toEqual(['start', 'extension']);
const ids = MENU_ITEMS.map((item) => item.id);
expect(new Set(ids).size).toBe(ids.length);
});
it('reads the extension in tabs, setting it up first, each tab a page or the table of sites', () => {
const extension = MENU_ITEMS.find((item) => item.id === 'extension');
expect(extension.kind).toBe('tabs');
expect(extension.tools).toEqual(EXTENSION_TABS.map((tab) => tab.id));
expect(extension.tools[0]).toBe('extension');
for (const tab of EXTENSION_TABS) {
expect(Boolean(PAGES[tab.id]) || tab.id === 'extension-sites', tab.id).toBe(true);
expect(tabLabel(tab.id)).toBe(tab.label);
}
expect(landingFor('extension-tools')).toEqual({ item: 'extension', tool: 'extension-tools' });
});
it('explains Settings section by section, in the order of its own screen', () => {
const settings = MENU_ITEMS.find((item) => item.id === 'settings');
expect(settings.kind).toBe('tabs');
expect(settings.tools).toEqual(SETTINGS_TABS.map((tab) => tab.id));
expect(SETTINGS_TABS.map((tab) => tab.label)).toEqual(['General', 'Publishing', 'Imagery', 'Templates', 'Icons', 'Storage', 'System']);
for (const tab of SETTINGS_TABS) {
expect(PAGES[tab.id], tab.id).toBeTruthy();
expect(tabLabel(tab.id)).toBe(tab.label);
}
expect(landingFor('settings')).toEqual({ item: 'settings', tool: 'settings' });
});
it('says where the extension works in a table as wide as its columns', () => {
for (const row of EXTENSION_SITES.rows) expect(row.cells, row.view).toHaveLength(EXTENSION_SITES.columns.length);
expect(EXTENSION_SITES.rows.map((row) => row.view)).toContain('Street View');
// the nine sites engine/mapsites.py reads a map from
expect(EXTENSION_SITES.sites).toHaveLength(9);
});
it('says to install the extension on the page somebody reads first', () => {
expect(PAGES.start.tips.some((tip) => /extension/i.test(tip.title))).toBe(true);
});
it('names both hosts wherever it describes the update check', () => {
const lines = prose().filter((line) => /new versions/i.test(line));
expect(lines.length).toBeGreaterThan(0);
for (const line of lines) expect(line).toMatch(/GitHub[\s\S]*PyPI/);
});
});
describe('a page and its pictures', () => {
const shots = allShots();
it('takes every picture it shows, and names each one once', () => {
const names = shots.map((one) => one.shot);
expect(new Set(names).size).toBe(names.length);
});
for (const { shot, anchors } of shots) {
it(`${shot}: was made, and every frame has a rectangle inside it`, () => {
const picture = shotOf(shot);
expect(picture, `run npm run guide:shots to make ${shot}.webp`).not.toBeNull();
for (const anchor of anchors) {
const rect = picture.anchors[anchor];
expect(rect, `${anchor} was not measured on ${shot}; run npm run guide:shots`).toBeTruthy();
expect(rect.x).toBeGreaterThanOrEqual(0);
expect(rect.y).toBeGreaterThanOrEqual(0);
expect(rect.x + rect.w).toBeLessThanOrEqual(picture.width + 1);
expect(rect.y + rect.h).toBeLessThanOrEqual(picture.height + 1);
}
});
it(`${shot}: frames controls the app still has`, () => {
// the control a frame points at went away or was renamed: the picture is stale
// even if nobody has looked at it yet
for (const anchor of anchors) {
expect(COMPONENTS, `no component carries data-guide "${anchor}"`).toMatch(
new RegExp(`["']${anchor.replace('.', '\\.')}["']`)
);
}
});
}
it('keeps every picture landscape, so the guide shows it whole without scrolling', () => {
for (const { shot } of shots) {
const picture = shotOf(shot);
if (!picture) continue;
expect(picture.height / picture.width, `${shot} is ${picture.width}×${picture.height}, too tall`).toBeLessThanOrEqual(0.75);
}
});
it('ships no picture the guide no longer shows', () => {
const dir = fileURLToPath(new URL('../assets/guide/', import.meta.url));
const wanted = new Set(shots.map((one) => one.shot));
for (const file of readdirSync(dir).filter((name) => !name.startsWith('.'))) {
expect(wanted.has(file.replace(/\.(webp|json|webm)$/, '')), `${file} is no longer shown`).toBe(true);
}
});
it('keeps every page to a handful of frames, and a picture behind each number that leads on', () => {
for (const [id, page] of Object.entries(PAGES)) {
expect(page.marks.length, `${id} frames nothing`).toBeGreaterThan(0);
expect(page.marks.length, `${id} frames too much to read`).toBeLessThanOrEqual(9);
for (const mark of page.marks) if (mark.opens) expect(mark.opens.shot).toBeTruthy();
}
});
});
describe('journeys', () => {
it('walk through tools that exist, each step on a frame its tool’s page draws', () => {
for (const journey of JOURNEYS) {
expect(journey.steps.length, `${journey.title} is not a walk`).toBeGreaterThan(2);
for (const step of journey.steps) {
expect(TOOLS).toContain(step.tool);
expect(TOOL_LABELS[step.tool]).toBeTruthy();
expect(step.text.trim().endsWith('.')).toBe(true);
expect(stepMarks(step).map((mark) => mark.anchor)).toEqual(step.marks);
}
}
});
it('name the journeys a tool takes part in, at their step', () => {
expect(journeysThrough('media')).toEqual([{ id: 'geolocate-a-photo', title: 'Geolocate a photo', step: 1 }]);
expect(journeysThrough('post')).toEqual([{ id: 'geolocate-a-photo', title: 'Geolocate a photo', step: 6 }]);
expect(journeysThrough('settings')).toEqual([]);
});
it('measure a step taken on a picture of its own on that picture', () => {
const shots = allShots();
for (const journey of JOURNEYS) {
for (const step of journey.steps.filter((one) => one.shot)) {
const taken = shots.find((one) => one.shot === stepShot(step));
expect(taken, step.shot).toBeTruthy();
for (const anchor of step.marks) expect(taken.anchors).toContain(anchor);
}
if (journey.result) expect(shots.map((one) => one.shot)).toContain(journey.result.shot);
}
});
it('build an analyzer inside Detect, each step named for what it does, ending on the saved one', () => {
const build = JOURNEYS.find((journey) => journey.id === 'create-an-analyzer');
expect(build.steps.every((step) => step.tool === 'detect')).toBe(true);
const labels = build.steps.map((step) => step.label);
expect(labels.every(Boolean)).toBe(true);
expect(new Set(labels).size).toBe(labels.length);
expect(build.steps.at(-1).marks).toEqual(['detect.builder-save']);
expect(build.result.shot).toBeTruthy();
expect(journeysThrough('detect')).toEqual([{ id: 'create-an-analyzer', title: 'Create your analyzer', step: 1 }]);
});
it('read a sequel of a sequel, as the analyzer builder opens from the library', () => {
const marks = stepMarks({ tool: 'detect', marks: ['detect.rules', 'detect.reads'] });
expect(marks.map((mark) => mark.title)).toEqual(['Rules', 'What it reads']);
const shots = allShots().map((one) => one.shot);
for (const shot of ['detect-library', 'detect-analyzer-new', 'detect-builder']) expect(shots).toContain(shot);
});
it('search with Find inside Horizon, a step a mark, ending on the place laid', () => {
const search = JOURNEYS.find((journey) => journey.id === 'search-with-find');
expect(search.steps.every((step) => step.tool === 'horizon' && step.shot)).toBe(true);
const labels = search.steps.map((step) => step.label);
expect(new Set(labels).size).toBe(labels.length);
expect(search.steps.at(-1).marks).toEqual(['find.trust', 'find.places']);
expect(search.result.shot).toBe('find-look');
// the place found plays, and the search itself is a press away
expect(shotOf('find-look').film).toBeTruthy();
expect(search.result.example).toBe(true);
// the screen Find's notice opens on leads to it
expect(opensFrom('horizon', FIND_GUIDE).walk).toBe('search-with-find');
expect(journeysThrough('horizon')).toEqual([{ id: 'search-with-find', title: 'Search with Find', step: 1 }]);
});
it('take a geolocation as far as the published thread', () => {
const geolocate = JOURNEYS.find((journey) => journey.id === 'geolocate-a-photo');
expect(geolocate.steps.at(-1)).toMatchObject({ tool: 'post', marks: ['post.first', 'post.publish'] });
});
});
describe('where the numbers sit', () => {
const shot = { width: 1000, height: 600 };
const far = (spots, apart) =>
spots.every(({ pin }, i) => spots.slice(i + 1).every((other) => Math.hypot(other.pin.x - pin.x, other.pin.y - pin.y) >= apart));
it('keeps every number inside the picture, and checks it where it is drawn', () => {
// three controls in the top left corner: the numbers pushed in from the edge must
// not land on each other there
const frames = [
{ x: 0, y: 0, w: 70, h: 30 },
{ x: 0, y: 30, w: 30, h: 500 },
{ x: 25, y: 40, w: 180, h: 30 },
];
const spots = pinSpots(frames, shot, 30);
for (const { pin } of spots) {
expect(pin.x).toBeGreaterThanOrEqual(15);
expect(pin.y).toBeGreaterThanOrEqual(15);
expect(pin.x).toBeLessThanOrEqual(985);
expect(pin.y).toBeLessThanOrEqual(585);
}
expect(far(spots, 30)).toBe(true);
});
it('tries the middle of an edge once the corners are taken', () => {
// four small controls at the corners of a panel, then the panel itself
const frames = [
{ x: 100, y: 100, w: 10, h: 10 },
{ x: 300, y: 100, w: 10, h: 10 },
{ x: 100, y: 400, w: 10, h: 10 },
{ x: 300, y: 400, w: 10, h: 10 },
{ x: 100, y: 100, w: 200, h: 300 },
];
const spots = pinSpots(frames, shot, 30);
expect(far(spots, 30)).toBe(true);
expect(spots[4].pin).toEqual({ x: 200, y: 100 });
});
it('puts the number of a frame covering most of the picture in its middle', () => {
const [map] = pinSpots([{ x: 60, y: 40, w: 940, h: 560 }], shot);
expect(map.pin).toEqual({ x: 530, y: 320 });
});
it('stands just off the corner of a small control, so it hides none of it', () => {
const [button] = pinSpots([{ x: 200, y: 200, w: 60, h: 24 }], shot, 30);
expect(button.pin).toEqual({ x: 194, y: 194 });
});
it('sits on the corner of a panel, which is padding', () => {
const [panel] = pinSpots([{ x: 100, y: 100, w: 300, h: 200 }], shot, 30);
expect(panel.pin).toEqual({ x: 100, y: 100 });
});
it('moves under its control rather than stacking on the number of the one beside it', () => {
const [, second] = pinSpots([{ x: 100, y: 100, w: 40, h: 20 }, { x: 120, y: 100, w: 40, h: 20 }], shot, 30);
expect(second.pin).toEqual({ x: 114, y: 126 });
});
it('keeps off another numbered control, though the seam between two is fine', () => {
const frames = [
{ x: 0, y: 0, w: 400, h: 90 },
{ x: 200, y: 85, w: 40, h: 20 },
];
expect(pinSpots(frames, shot, 30)[1].pin).toEqual({ x: 194, y: 111 });
});
it('never lets the picture’s edge push a small control’s number back onto it', () => {
const [corner] = pinSpots([{ x: 0, y: 0, w: 40, h: 20 }], shot, 30);
expect(corner.pin).toEqual({ x: 46, y: 26 });
});
it('asks for more room in the picture’s pixels when it is shown smaller', () => {
// two buttons 40 pixels apart: clear at full size, too close once halved on screen
const frames = [{ x: 100, y: 100, w: 40, h: 20 }, { x: 140, y: 100, w: 40, h: 20 }];
expect(pinSpots(frames, shot, 30)[1].pin).toEqual({ x: 134, y: 94 });
expect(pinSpots(frames, shot, 60)[1].pin).not.toEqual({ x: 128, y: 88 });
});
});
describe('where the guide opens', () => {
it('on the tab of the tool it was asked from', () => {
expect(landingFor('media')).toEqual({ item: 'collect', tool: 'media' });
expect(landingFor('timeline')).toEqual({ item: 'case', tool: 'timeline' });
});
it('on a page asked by its id, Settings included', () => {
expect(landingFor('settings')).toEqual({ item: 'settings', tool: 'settings' });
expect(landingFor('journey:geolocate-a-photo')).toEqual({ item: 'journey:geolocate-a-photo', tool: null });
});
it('on the screen a number opens, asked by its anchor', () => {
expect(landingFor(FIND_GUIDE)).toEqual({ ...landingFor('horizon'), opens: 'horizon.find' });
const find = opensFrom('horizon', FIND_GUIDE);
expect(find.shot).toBe('horizon-find');
expect(find.from).toBe('Find, in beta');
expect(find.more.href).toBe(FIND_DOC);
// an anchor that opens nothing is no landing
expect(landingFor('horizon.picture')).toEqual({ item: 'start', tool: null });
expect(opensFrom('horizon', 'horizon.picture')).toBeNull();
});
it('points the full Find guide at a page the repository holds', () => {
const doc = FIND_DOC.replace('https://github.com/OsintMeThat/azimut/blob/main/', '../../../');
expect(existsSync(fileURLToPath(new URL(doc, import.meta.url)))).toBe(true);
});
it('at the start for anything else', () => {
expect(landingFor('overview')).toEqual({ item: 'start', tool: null });
expect(landingFor(undefined)).toEqual({ item: 'start', tool: null });
});
});
describe('the register the guide is written in', () => {
it('leads with one sentence, or two at most', () => {
for (const page of Object.values(PAGES)) expect(page.lead.split('. ').length, page.lead).toBeLessThan(3);
});
it('uses no em-dash appositive, which the house copy rules refuse', () => {
for (const line of prose()) expect(line, 'em-dash in UI copy').not.toMatch(/—/);
});
it('ends every line of text with a full stop, and every title without one', () => {
for (const page of Object.values(PAGES)) {
for (const mark of page.marks) {
expect(mark.text.trim().endsWith('.'), mark.text).toBe(true);
expect(mark.title.trim().endsWith('.'), mark.title).toBe(false);
}
for (const tip of page.tips ?? []) expect(tip.text.trim().endsWith('.'), tip.text).toBe(true);
}
});
it('quotes only words the app puts on screen', () => {
// a quoted label is what the reader searches the screen for, so a renamed
// dialog or button has to fail here rather than send them looking for nothing
const root = fileURLToPath(new URL('../', import.meta.url));
const sources = [];
const walk = (dir) => {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const at = join(dir, entry.name);
if (entry.isDirectory()) {
if (entry.name !== 'node_modules' && entry.name !== 'assets') walk(at);
} else if (/\.(svelte|js)$/.test(entry.name) && !entry.name.endsWith('.test.js') && entry.name !== 'guide.js') {
sources.push(readFileSync(at, 'utf8'));
}
}
};
walk(root);
const app = sources.join('\n');
const quoted = prose().flatMap((line) => [...line.matchAll(/"([^"]+)"/g)].map((match) => match[1]));
expect(quoted.length).toBeGreaterThan(0);
for (const label of quoted) expect(app.includes(label), `the guide quotes "${label}", which no screen shows`).toBe(true);
});
it('says what a key does wherever it lists one, under a tool the app has', () => {
const labels = new Set(Object.values(TOOL_LABELS));
for (const group of KEYMAP) {
expect(group.keys.length).toBeGreaterThan(0);
const tools = group.where.split(', ');
expect(group.where === 'Anywhere' || tools.every((tool) => labels.has(tool)), group.where).toBe(true);
for (const key of group.keys) {
expect(key.combo.trim()).toBeTruthy();
expect(key.does.trim()).toBeTruthy();
}
}
});
it('answers every symptom it raises', () => {
for (const fix of FIXES) {
expect(fix.symptom.trim()).toBeTruthy();
expect(fix.fix.trim().endsWith('.')).toBe(true);
}
});
});