@unbound-app/api 0.11.0 → 1.1.0

package/testing/recorders.ts

@@ -0,0 +1,183 @@
+import type { NativePluginCapability, NativePluginPlatform } from '../src/native';
+import type { CommandArgs, LogEntry } from './install-addon-globals';
+import type { OpenedDialog, ShownToast } from './fake-feedback';
+import type { CommandContext, Reply } from '../src/commands';
+import type { NativeCall } from './fake-native-bridge';
+import type { PatchRecord } from './recording-patcher';
+import type { PluginLocale } from './plugin-types';
+import type { PluginSpec } from './fake-plugins';
+import type { FakeModule } from './fake-metro';
+import type { FluxAction } from '../src/flux';
+import type { StoreSeeds } from './fake-api';
+import type { FakeJava } from './fake-java';
+import type { FakeObjc } from './fake-objc';
+
+import { getSession } from './session';
+
+/** Every toast the plugin showed this test, in order. */
+export type ToastRecorder = { readonly shown: readonly ShownToast[] };
+
+/** Every dialog the plugin opened this test, in order, each with `respond` to answer it. */
+export type DialogRecorder = { readonly opened: readonly OpenedDialog[] };
+
+/** The plugin's registered commands, and `run` to call one as Discord would. */
+export type CommandRecorder = {
+	readonly registered: ReadonlyMap<string, object>;
+	/** Runs `/path` with parsed `args`, in a guild text channel unless `context` says otherwise. */
+	run: (path: string, args?: CommandArgs, context?: Partial<CommandContext>) => Promise<Reply>;
+};
+
+/** The patches the plugin holds right now, each with its kind, target and method. */
+export type PatchRecorder = { readonly applied: readonly PatchRecord[] };
+
+/** The fake Flux: the actions the plugin dispatched, and the stores a test seeds. */
+export type FluxRecorder = {
+	readonly dispatched: readonly FluxAction[];
+	/** Adds stores, or replaces a seeded store's methods and tells its readers. */
+	seed: (stores: StoreSeeds) => void;
+	/** Calls a seeded store's change listeners. */
+	emit: (name: string) => void;
+	/** Sends an action to the plugin's interceptors and listeners. */
+	dispatch: (action: FluxAction) => Promise<void>;
+};
+
+/** The fake metro's modules: `register` one for the plugin to find, such as `{ sendMessage }`. */
+export type MetroRecorder = { register: (module: FakeModule, path?: string) => void };
+
+/** The fake `native`: the platform `definePlatform` selects by, and the modules and capabilities it reports. */
+export type NativeRecorder = {
+	/** Switches the host platform, `ios` until set; `definePlatform` and `Platform.OS` follow it. */
+	setPlatform: (platform: NativePluginPlatform) => void;
+	/** Gives `getNativeModule(name)` a module to return. */
+	// UNKNOWN: a native module has whatever shape the plugin reads.
+	registerModule: (name: string, module: unknown) => void;
+	/** Sets what `native.has` reports. */
+	setCapabilities: (capabilities: NativePluginCapability[]) => void;
+	/** The Objective-C bridge a plugin gets on iOS: register classes and objects for its calls to reach. */
+	readonly objc: FakeObjc;
+	/** The Java bridge a plugin gets on Android: register classes and objects for its calls to reach. */
+	readonly java: FakeJava;
+	/** Every `objc`, `java` and `hooks` call the plugin made this test, in order. */
+	readonly calls: readonly NativeCall[];
+};
+
+/** The plugins the fake `plugins` lists: the plugin under test is there, started; a test sets the others. */
+export type PluginRecorder = {
+	/** Adds an installed plugin, or changes the one with this id; `plugins.get(id)` reads it. */
+	set: (id: string, spec?: PluginSpec) => void;
+	/** Removes an installed plugin. */
+	remove: (id: string) => void;
+};
+
+/** The fake `fs`: its in-memory files, by absolute path; a test may read, add or remove them. */
+export type FsRecorder = { readonly files: Map<string, string> };
+
+/** Every line the plugin's `logger` received this test. */
+export type LogRecorder = { readonly entries: readonly LogEntry[] };
+
+// Each recorder reads the session on every access, so it always shows the current test's fakes.
+function createRecorders() {
+	const toasts: ToastRecorder = {
+		get shown() {
+			return getSession().toasts.shown;
+		},
+	};
+	const dialogs: DialogRecorder = {
+		get opened() {
+			return getSession().dialogs.opened;
+		},
+	};
+	const commands: CommandRecorder = {
+		get registered() {
+			return getSession().scope.commands.registered;
+		},
+		run: (path, args, context) => getSession().scope.commands.run(path, args, context),
+	};
+	const patches: PatchRecorder = {
+		get applied() {
+			return getSession().scope.patcher.patches;
+		},
+	};
+	const flux: FluxRecorder = {
+		get dispatched() {
+			return getSession().flux.dispatched;
+		},
+		seed: (stores) => getSession().flux.seed(stores),
+		emit: (name) => getSession().flux.emit(name),
+		dispatch: (action) => getSession().flux.dispatch(action),
+	};
+	const metro: MetroRecorder = {
+		register: (module, path) => getSession().scope.metro.register(module, path),
+	};
+	const native: NativeRecorder = {
+		setPlatform: (platform) => void (getSession().native.state.platform = platform),
+		registerModule: (name, module) => void getSession().native.state.modules.set(name, module),
+		setCapabilities: (capabilities) =>
+			void (getSession().native.state.capabilities = capabilities),
+		get objc() {
+			return getSession().native.objc;
+		},
+		get java() {
+			return getSession().native.java;
+		},
+		get calls() {
+			return getSession().native.calls;
+		},
+	};
+	const plugins: PluginRecorder = {
+		set: (id, spec) => getSession().plugins.set(id, spec),
+		remove: (id) => getSession().plugins.remove(id),
+	};
+	const fs: FsRecorder = {
+		get files() {
+			return getSession().fs.files;
+		},
+	};
+	const logs: LogRecorder = {
+		get entries() {
+			return getSession().scope.logs;
+		},
+	};
+
+	return { toasts, dialogs, commands, patches, flux, metro, native, plugins, fs, logs };
+}
+
+export const { toasts, dialogs, commands, patches, flux, metro, native, plugins, fs, logs } =
+	createRecorders();
+
+/**
+ * @description Switches the locale `@unbound-app/i18n` reads, re-rendering every mounted component that reads it.
+ * A code the plugin ships no file for reads en-US, as on device. The preset puts en-US back before each test.
+ * @param code The locale code, such as `de`.
+ */
+export function setLocale(code: PluginLocale): void {
+	const { locales } = getSession();
+
+	if (!locales) {
+		throw new Error('Failed to set the locale: the plugin has no i18n/en-US.json.');
+	}
+
+	locales.setLocale(String(code));
+}
+
+/**
+ * @description Adds members to a fake of `@unbound-app/api`, so the plugin reads them. `mock.module('@unbound-app/api')` in a test
+ * replaces the whole module instead, dropping every fake the preset installed.
+ * @param path The namespace, or a nested one with dots, such as `ui` or `metro.components`.
+ * @param members The members to add or replace.
+ */
+export function extendApi(path: string, members: FakeModule): void {
+	let target: unknown = getSession().scope.unbound;
+
+	for (const name of path.split('.')) {
+		target = typeof target === 'object' && target !== null ? Reflect.get(target, name) : void 0;
+	}
+
+	if (typeof target !== 'object' || target === null) {
+		throw new Error(
+			`Failed to extend @unbound-app/api ${path}: the fake has no such namespace.`,
+		);
+	}
+
+	Object.assign(target, members);
+}

package/testing/recording-patcher.ts

@@ -0,0 +1,173 @@
+import type { PatchParent, ReactPatcher, after, before, instead } from '../src/patcher';
+
+import { createReactPatcher, type Install, type MethodContext } from './react-patcher';
+
+type PatchKind = 'before' | 'instead' | 'after';
+
+/** One patch a recording patcher applied, kept until it is removed. */
+export type PatchRecord = {
+	kind: PatchKind;
+	/** The object holding the method; the lazy handle while the patch is pending. */
+	target: PatchParent;
+	/** The patched method; empty while a React patch waits, which finds the render only once its module registers. */
+	method: string;
+	/** True while the patch waits for its lazy handle's module to register. */
+	pending: boolean;
+};
+
+/** A patcher that really patches, and records each patch it holds in `patches`. */
+export type RecordingPatcher = {
+	before: typeof before;
+	instead: typeof instead;
+	after: typeof after;
+	/** React patches, which record the render they wrap: a `memo`'s `type`, a `forwardRef`'s or class's `render`. */
+	react: ReactPatcher;
+	/** Removes every patch this patcher holds. */
+	unpatchAll: () => void;
+	patches: PatchRecord[];
+};
+
+// UNKNOWN: a patched method returns whatever the code under test returns.
+type Method = (...args: never[]) => unknown;
+
+type Context = MethodContext;
+
+// UNKNOWN: a patch callback returns whatever the test's patch returns.
+type Callback = (context: Context) => unknown;
+
+type Hook = {
+	original: Method;
+	callbacks: Map<PatchRecord, Callback>;
+};
+
+function run(hook: Hook, kind: PatchKind, context: Context) {
+	for (const [record, callback] of hook.callbacks) {
+		if (record.kind !== kind) {
+			continue;
+		}
+
+		const returned = callback.call(context.this, context);
+
+		if (kind === 'before') {
+			if (Array.isArray(returned)) {
+				context.args = returned as never[];
+			}
+		} else if (returned !== undefined) {
+			context.result = returned;
+		}
+	}
+}
+
+function hook(target: PatchParent, method: string): Hook {
+	const created: Hook = { original: Reflect.get(target, method), callbacks: new Map() };
+
+	function patched(this: PatchParent, ...args: never[]) {
+		const context: Context = {
+			args,
+			this: this,
+			original: (...next: never[]) => created.original.apply(this, next),
+			result: null,
+		};
+
+		run(created, 'before', context);
+
+		if ([...created.callbacks.keys()].some((record) => record.kind === 'instead')) {
+			run(created, 'instead', context);
+		} else {
+			context.result = context.original(...context.args);
+		}
+
+		run(created, 'after', context);
+
+		return context.result;
+	}
+
+	Reflect.set(target, method, patched);
+
+	return created;
+}
+
+/** Calls `onLoad` with the module a lazy handle resolves to once one is registered, at once for a plain object; returns what stops waiting. */
+export type WhenLoaded = (target: PatchParent, onLoad: (module: PatchParent) => void) => () => void;
+
+// A plain object is the target already, so nothing waits.
+function patchNow(target: PatchParent, onLoad: (module: PatchParent) => void): () => void {
+	onLoad(target);
+
+	return () => {};
+}
+
+/**
+ * @description Creates a patcher whose patches wrap the method for real and are listed in `patches` until removed.
+ * A patch on a lazy handle whose module is not registered yet is listed as pending and applies when it registers.
+ * @param whenLoaded Resolves a lazy handle to its module, as the fake metro does; omitted, every target is taken as it is.
+ * @returns The patcher.
+ */
+export function createRecordingPatcher(whenLoaded: WhenLoaded = patchNow): RecordingPatcher {
+	const patches: PatchRecord[] = [];
+	// Keyed by the resolved module, so a handle patches whichever module is registered for it in this session.
+	const hooks = new Map<PatchParent, Map<string, Hook>>();
+	const waiting = new Map<PatchRecord, () => void>();
+
+	function unpatch(record: PatchRecord) {
+		const index = patches.indexOf(record);
+
+		if (index === -1) return;
+
+		patches.splice(index, 1);
+		waiting.get(record)?.();
+		waiting.delete(record);
+
+		const methods = hooks.get(record.target);
+		const hooked = methods?.get(record.method);
+
+		if (!methods || !hooked) return;
+
+		hooked.callbacks.delete(record);
+
+		if (hooked.callbacks.size > 0) return;
+
+		Reflect.set(record.target, record.method, hooked.original);
+		methods.delete(record.method);
+	}
+
+	const install: Install = (kind, target, place, method = '') => {
+		const record: PatchRecord = { kind, target, method, pending: true };
+
+		patches.push(record);
+		waiting.set(
+			record,
+			whenLoaded(target, (module) => {
+				const placed = place(module);
+				const { parent, callback } = placed;
+				const methods = hooks.get(parent) ?? new Map<string, Hook>();
+				const hooked = methods.get(placed.method) ?? hook(parent, placed.method);
+
+				waiting.delete(record);
+				hooks.set(parent, methods);
+				methods.set(placed.method, hooked);
+				hooked.callbacks.set(record, callback);
+				Object.assign(record, { target: parent, method: placed.method, pending: false });
+			}),
+		);
+
+		return () => unpatch(record);
+	};
+
+	function patch(kind: PatchKind) {
+		return (target: PatchParent, method: string, callback: Callback) =>
+			install(kind, target, (module) => ({ parent: module, method, callback }), method);
+	}
+
+	return {
+		patches,
+		before: patch('before') as RecordingPatcher['before'],
+		instead: patch('instead') as RecordingPatcher['instead'],
+		after: patch('after') as RecordingPatcher['after'],
+		react: createReactPatcher(install),
+		unpatchAll: () => {
+			// `unpatch` splices `patches`, so walk a copy.
+			for (const record of patches.slice()) unpatch(record);
+		},
+	};
+}

package/testing/render.ts

@@ -0,0 +1,84 @@
+import type { ReactNode } from 'react';
+
+import type { PluginLocale, SettingsOverrides } from './plugin-types';
+import type { SettingValue } from './fake-settings';
+import type { FakeModule } from './fake-metro';
+import type { StoreSeeds } from './fake-api';
+
+import { act, createTestRenderer } from './test-renderer';
+import { queriesOf, type Queries } from './test-node';
+import { getSession } from './session';
+
+/** What `render` sets up before the first render. */
+export type RenderOptions = {
+	/** Settings to store first; the rest read their defaults. */
+	settings?: SettingsOverrides;
+	/** The locale `@unbound-app/i18n` reads. */
+	locale?: PluginLocale;
+	/** Flux stores `flux.getStore` and `flux.useStore` read, such as `{ User: { getCurrentUser: () => user } }`. */
+	stores?: StoreSeeds;
+};
+
+/** A mounted tree: queries over it, and the operations a test drives it with. */
+export type RenderResult = Queries & {
+	/** Renders a new element in place; components of the same type keep their state. */
+	rerender: (element: ReactNode) => void;
+	/** Unmounts the tree, running every effect's cleanup. The preset unmounts what a test leaves mounted. */
+	unmount: () => void;
+	/** Runs an interaction with renders held back, then renders once. */
+	act: typeof act;
+};
+
+function isLeaf(value: unknown): value is SettingValue {
+	return typeof value !== 'object' || value === null || Array.isArray(value);
+}
+
+function applySettings(overrides: FakeModule, prefix = '') {
+	const { settings } = getSession();
+
+	if (!settings) {
+		throw new Error('Failed to apply render settings: the plugin has no settings.ts.');
+	}
+
+	for (const [key, value] of Object.entries(overrides)) {
+		const path = prefix ? `${prefix}.${key}` : key;
+
+		if (isLeaf(value)) {
+			settings.set(path, value);
+		} else {
+			applySettings(value, path);
+		}
+	}
+}
+
+/**
+ * @description Renders an element with the plugin's fakes, after storing `settings`, switching to `locale` and
+ * seeding `stores`. Host components from `react-native` stay plain nodes `find` reaches by name.
+ * @param element The element, such as `<GreetingTitle />`.
+ * @param options The settings, locale and stores to set up first.
+ * @returns Queries over the tree, and `rerender`, `unmount` and `act`.
+ */
+export function render(element: ReactNode, options: RenderOptions = {}): RenderResult {
+	const session = getSession();
+
+	if (options.stores) {
+		session.flux.seed(options.stores);
+	}
+
+	if (options.settings) {
+		applySettings(options.settings);
+	}
+
+	if (options.locale !== undefined) {
+		session.locales?.setLocale(String(options.locale));
+	}
+
+	const renderer = createTestRenderer(element);
+
+	return {
+		...queriesOf(renderer.root),
+		rerender: (next) => act(() => renderer.update(next)),
+		unmount: renderer.unmount,
+		act,
+	};
+}

package/testing/session.ts

@@ -0,0 +1,77 @@
+import type { InstalledAddonGlobals } from './install-addon-globals';
+import type { FakeDialogs, FakeToasts } from './fake-feedback';
+import type { ListenerRegistry } from './listener-registry';
+import type { FakeAssets, FakeFlux } from './fake-api';
+import type { FakeSettings } from './fake-settings';
+import type { FakeLocales } from './fake-locales';
+import type { FakePlugins } from './fake-plugins';
+import type { FakeNative } from './fake-native';
+import type { FakeFs } from './fake-fs';
+
+import { unmountAll } from './test-renderer';
+
+/** The plugin under test and every fake the preset installed for it. */
+export type TestSession = {
+	root: string;
+	entry: string | undefined;
+	scope: InstalledAddonGlobals;
+	listeners: ListenerRegistry;
+	toasts: FakeToasts;
+	dialogs: FakeDialogs;
+	flux: FakeFlux;
+	assets: FakeAssets;
+	locales: FakeLocales | undefined;
+	settings: FakeSettings | undefined;
+	native: FakeNative;
+	plugins: FakePlugins;
+	fs: FakeFs;
+};
+
+let active: TestSession | undefined;
+
+/**
+ * @description Makes a session the one the recorders, `render` and `startPlugin` read. The preset calls it once.
+ * @param session The session.
+ */
+export function startSession(session: TestSession): void {
+	active = session;
+}
+
+/**
+ * @description Returns the session the preset started.
+ * @returns The session; throws naming the bunfig line when the preset is not loaded.
+ */
+export function getSession(): TestSession {
+	if (!active) {
+		throw new Error(
+			'The Unbound test preset is not loaded. Add `preload = ["@unbound-app/api/testing/preset"]` under [test] in bunfig.toml.',
+		);
+	}
+
+	return active;
+}
+
+/**
+ * @description Puts every fake back to how the preset made it: no mounted trees, patches, commands, listeners, timers,
+ * metro modules, files, stored settings, toasts, dialogs, stores or logs, the platform iOS, and en-US.
+ */
+export function resetSession(): void {
+	const session = getSession();
+	const { scope } = session;
+
+	unmountAll();
+	scope.patcher.unpatchAll();
+	scope.commands.unregisterAll();
+	scope.timers.clearAll();
+	scope.metro.reset();
+	session.listeners.clear();
+	session.native.reset();
+	session.plugins.reset();
+	session.fs.files.clear();
+	scope.storage.data.clear();
+	scope.logs.length = 0;
+	session.flux.reset();
+	session.toasts.shown.length = 0;
+	session.dialogs.opened.length = 0;
+	session.locales?.setLocale('en-US');
+}

package/testing/test-node.ts

@@ -0,0 +1,163 @@
+import type { HostName, HostPropsByName } from './fake-react-native';
+import type { Fiber, Props } from './test-renderer';
+
+/** The props of a host or component this kit has no type for: whatever the code under test gave it. */
+type AnyProps = Props;
+
+/**
+ * What `find` and `findAll` match, as `findComponent` does: a host or component name (a host's name, else
+ * `displayName`, else the function's name), or a predicate over each node.
+ */
+export type Matcher = string | ((node: TestNode) => boolean);
+
+/** Finds rendered nodes below a node. A host name types the props; pass `P` to type a component's. */
+export type Queries = {
+	/** The first node below that matches, depth first; throws naming what did render when none does. */
+	find: {
+		<N extends HostName>(name: N): TestNode<HostPropsByName[N]>;
+		<P = AnyProps>(match: Matcher): TestNode<P>;
+	};
+	/** Every node below that matches, depth first. */
+	findAll: {
+		<N extends HostName>(name: N): TestNode<HostPropsByName[N]>[];
+		<P = AnyProps>(match: Matcher): TestNode<P>[];
+	};
+	/** The text rendered below, joined. */
+	text: () => string;
+};
+
+/** A rendered host element or component, read live: after a re-render it shows the new props and children. */
+export type TestNode<P = AnyProps> = Queries & {
+	/** The element type: a host name such as `'Text'`, or the component. */
+	type: unknown;
+	/** The host name, or the component's `displayName` or function name. */
+	name: string;
+	props: P;
+	/** The nodes and strings rendered directly inside, Fragments and Providers flattened away. */
+	children: (TestNode | string)[];
+	parent: TestNode | undefined;
+};
+
+const nodes = new WeakMap<Fiber, TestNode>();
+
+function visible(fibers: Fiber[]): Fiber[] {
+	return fibers.flatMap((fiber) =>
+		fiber.kind === 'wrapper' ? visible(fiber.children) : [fiber],
+	);
+}
+
+function texts(fiber: Fiber): string {
+	return fiber.kind === 'text' ? fiber.text : fiber.children.map(texts).join('');
+}
+
+function matches(match: Matcher, node: TestNode): boolean {
+	return typeof match === 'string' ? node.name === match : match(node);
+}
+
+function describe(match: Matcher): string {
+	return typeof match === 'string' ? `"${match}"` : 'the predicate';
+}
+
+function walk(fiber: Fiber, visit: (node: TestNode) => boolean) {
+	for (const child of visible(fiber.children)) {
+		if (child.kind === 'text') {
+			continue;
+		}
+
+		if (visit(nodeOf(child)) || walk(child, visit)) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * @description Builds the queries over the nodes rendered below a fiber.
+ * @param fiber The fiber, such as a renderer's root.
+ * @returns `find`, `findAll` and `text`.
+ */
+export function queriesOf(fiber: Fiber): Queries {
+	function findAll(match: Matcher): TestNode[] {
+		const found: TestNode[] = [];
+
+		walk(fiber, (node) => {
+			if (matches(match, node)) {
+				found.push(node);
+			}
+
+			return false;
+		});
+
+		return found;
+	}
+
+	function find(match: Matcher): TestNode {
+		let found: TestNode | undefined;
+
+		walk(fiber, (node) => {
+			found = matches(match, node) ? node : void 0;
+
+			return Boolean(found);
+		});
+
+		if (!found) {
+			const rendered = new Set<string>();
+
+			walk(fiber, (node) => {
+				rendered.add(node.name);
+
+				return false;
+			});
+			throw new Error(
+				`No rendered node matches ${describe(match)}. Rendered: ${[...rendered].join(', ') || 'nothing'}.`,
+			);
+		}
+
+		return found;
+	}
+
+	return {
+		find: find,
+		findAll: findAll,
+		text: () => texts(fiber),
+	};
+}
+
+/**
+ * @description Wraps a fiber as a {@link TestNode}, once per fiber, so the same node is returned across renders.
+ * @param fiber A host or component fiber.
+ * @returns The node.
+ */
+export function nodeOf(fiber: Fiber): TestNode {
+	const cached = nodes.get(fiber);
+
+	if (cached) {
+		return cached;
+	}
+
+	const node: TestNode = {
+		...queriesOf(fiber),
+		type: fiber.type,
+		name: fiber.name,
+		get props() {
+			return fiber.props;
+		},
+		get children() {
+			return visible(fiber.children).map((child) =>
+				child.kind === 'text' ? child.text : nodeOf(child),
+			);
+		},
+		get parent() {
+			let parent = fiber.parent;
+
+			while (parent?.kind === 'wrapper') parent = parent.parent;
+
+			return parent && parent.kind !== 'root' ? nodeOf(parent) : void 0;
+		},
+	};
+
+	nodes.set(fiber, node);
+
+	return node;
+}