@unbound-app/api 0.11.0 → 1.1.0

package/testing/plugin-lifecycle.ts

@@ -0,0 +1,149 @@
+import type { PatchRecord } from './recording-patcher';
+import type { PluginContext } from '../src/native';
+import type { StartContext } from './fake-native';
+
+import { getSession } from './session';
+
+type PluginExports = {
+	start?: (context: PluginContext) => void | Promise<void>;
+	stop?: () => void | Promise<void>;
+};
+
+type Held = {
+	patches: Set<PatchRecord>;
+	commands: Set<string>;
+	listeners: number;
+	direct: number;
+	timers: number;
+};
+
+let started: { plugin: PluginExports; context: PluginContext; before: Held } | undefined;
+
+function isPluginExports(value: unknown): value is PluginExports {
+	return typeof value === 'object' && value !== null;
+}
+
+function held(): Held {
+	const { scope, listeners, flux } = getSession();
+
+	return {
+		patches: new Set(scope.patcher.patches),
+		commands: new Set(scope.commands.registered.keys()),
+		listeners: listeners.active().length,
+		direct: flux.directListeners().length,
+		timers: scope.timers.pending(),
+	};
+}
+
+async function loadPlugin(): Promise<PluginExports> {
+	const { entry, root } = getSession();
+
+	if (!entry) {
+		throw new Error(
+			`Failed to start the plugin: ${root} has no src/index.tsx or src/index.ts.`,
+		);
+	}
+
+	const module: unknown = await import(entry);
+	const plugin: unknown =
+		isPluginExports(module) && 'default' in module ? module.default : module;
+
+	if (!isPluginExports(plugin)) {
+		throw new Error(`Failed to start the plugin: ${entry} exports no plugin object.`);
+	}
+
+	return plugin;
+}
+
+function describe(record: PatchRecord): string {
+	const target = Reflect.get(record.target, 'name');
+
+	return `patcher.${record.kind} on ${typeof target === 'string' && target ? `${target}.` : ''}${record.method}`;
+}
+
+// What the plugin added since `before` and still holds, as one line each.
+function since(before: Held, scopeOnly: boolean): string[] {
+	const { scope, listeners, flux } = getSession();
+
+	return [
+		...scope.patcher.patches.filter((record) => !before.patches.has(record)).map(describe),
+		...[...scope.commands.registered.keys()]
+			.filter((name) => !before.commands.has(name))
+			.map((name) => `command /${name}`),
+		...listeners.active().slice(before.listeners),
+		...Array.from(
+			{ length: Math.max(scope.timers.pending() - before.timers, 0) },
+			() => 'timer',
+		),
+		...(scopeOnly ? [] : flux.directListeners().slice(before.direct)),
+	];
+}
+
+/**
+ * @description Imports the plugin's entry once and runs its `start` with a `PluginContext`, as the client does when it is enabled.
+ * @param context Overrides for the context: its `platform`, `capabilities`, or the `native` bridge members the plugin calls.
+ * @returns A promise that settles once `start` has.
+ */
+export async function startPlugin(context: StartContext = {}): Promise<void> {
+	const { native, scope } = getSession();
+	const plugin = await loadPlugin();
+	const built = native.context(scope.addon.manifest, context);
+
+	started = { plugin, context: built, before: held() };
+	await plugin.start?.(built);
+}
+
+/**
+ * @description Lists what the plugin added since {@link startPlugin} and still holds: patches, commands, listeners and timers.
+ * Use it to check a feature undid itself without stopping the plugin, such as after a setting turned it off.
+ * @returns One line per thing held; empty when the plugin holds nothing.
+ */
+export function pluginHolds(): string[] {
+	if (!started) {
+		throw new Error('Failed to read what the plugin holds: call startPlugin() first.');
+	}
+
+	return since(started.before, true);
+}
+
+/**
+ * @description Runs the plugin's `stop`, then disposes what the plugin scope recorded, as the client does: its patches, commands,
+ * listeners and timers. The call rejects, which fails the test, listing what is still held after that, such as a
+ * change listener added directly to a Flux store, which Unbound does not remove either.
+ * @returns A promise that settles once `stop` has and nothing is left.
+ */
+export async function stopPlugin(): Promise<void> {
+	if (!started) {
+		throw new Error('Failed to stop the plugin: call startPlugin() first.');
+	}
+
+	const { plugin, context, before } = started;
+	const { scope, listeners } = getSession();
+
+	started = void 0;
+
+	try {
+		await plugin.stop?.();
+	} finally {
+		context.dispose();
+		scope.patcher.unpatchAll();
+		scope.timers.clearAll();
+		listeners.clear();
+		scope.commands.unregisterAll();
+	}
+
+	const leaks = since(before, false);
+
+	if (leaks.length === 0) return;
+
+	throw new Error(
+		`${scope.addon.name} left ${leaks.length} thing(s) behind after stop():\n${leaks.map((leak) => `  - ${leak}`).join('\n')}`,
+	);
+}
+
+/**
+ * @description Forgets a started plugin without stopping it. The preset calls it before each test.
+ */
+export function forgetPlugin(): void {
+	started = void 0;
+}

package/testing/plugin-types.ts

@@ -0,0 +1,34 @@
+import type { SettingsValues } from './fake-settings';
+
+/**
+ * The plugin under test's own types, which type `render`'s `settings` and `locale` and `setLocale`. Declare them
+ * once, beside the generated typings:
+ *
+ * ```ts
+ * import type { Settings } from '@unbound-app/settings';
+ *
+ * declare module '@unbound-app/api/testing' {
+ * 	interface PluginTypes { settings: Settings; locale: 'en-US' | 'de' }
+ * }
+ * ```
+ */
+// oxlint-disable-next-line typescript/no-empty-object-type, typescript/consistent-type-definitions -- declaration merging needs an interface, empty until a plugin adds to it
+export interface PluginTypes {}
+
+type Declared<K extends PropertyKey, Fallback> =
+	PluginTypes extends Record<K, infer T> ? T : Fallback;
+
+/** The plugin's settings, from {@link PluginTypes}; any settings object until it is declared. */
+export type PluginSettings = Declared<'settings', SettingsValues>;
+
+/** The plugin's locale codes, from {@link PluginTypes}; any string until they are declared. */
+export type PluginLocale = Declared<'locale', string>;
+
+/** Some of a plugin's settings, sections included in part: what a test overrides. */
+export type SettingsOverrides<S = PluginSettings> = {
+	[K in keyof S]?: S[K] extends readonly unknown[]
+		? S[K]
+		: S[K] extends object
+			? SettingsOverrides<S[K]>
+			: S[K];
+};

package/testing/preset.ts

@@ -0,0 +1,263 @@
+// The bun preload of a plugin's tests: `preload = ["@unbound-app/api/testing/preset"]` in bunfig.toml.
+import { afterEach, beforeEach, mock } from 'bun:test';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createElement } from 'react';
+import * as React from 'react';
+import { plugin } from 'bun';
+
+import {
+	assetNameOf,
+	findEntry,
+	findPluginRoot,
+	readLocaleTables,
+	readManifest,
+} from './plugin-files';
+import { createFakeDialogs, createFakeToasts, hasPlaceholders, KEY_LOOKUP } from './fake-feedback';
+import { createFakeSettings, defineSettings, setting, type SettingsSchema } from './fake-settings';
+import { createListenerRegistry, type ListenerRegistry } from './listener-registry';
+import { createFakeReactNative, type HostPropsByName } from './fake-react-native';
+import { installAddonGlobals, type FakeUnbound } from './install-addon-globals';
+import { createFakeLocales, SOURCE_LOCALE } from './fake-locales';
+import { createFakeAssets, createFakeFlux } from './fake-api';
+import { createJsxRuntimes } from './unfrozen-elements';
+import { resetSession, startSession } from './session';
+import { createFakePlugins } from './fake-plugins';
+import { forgetPlugin } from './plugin-lifecycle';
+import { createFakeUi } from './fake-components';
+import { createFakeNative } from './fake-native';
+import { createFakeUtils } from './fake-utils';
+import { unmountAll } from './test-renderer';
+import { createFakeFs } from './fake-fs';
+
+type SvgProps = Omit<HostPropsByName['SvgXml'], 'xml' | 'asset'>;
+
+// The namespaces that serve nested modules, as `unbound.metro.components` is `@unbound-app/api/metro/components`.
+const NESTED = new Map([
+	['metro', ['api', 'common', 'components', 'filters', 'stores']],
+	['utils', ['react']],
+]);
+
+const IMAGE = /\.(png|jpe?g|webp|gif)$/i;
+const SVG = /\.svg$/i;
+const SVG_ASSET = /\.svg\?asset$/i;
+const SVG_ASSET_NAMESPACE = 'unbound-svg-asset';
+
+function isSettingsSchema(value: unknown): value is SettingsSchema {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		Reflect.get(value, 'kind') === 'settings' &&
+		typeof Reflect.get(value, 'properties') === 'object'
+	);
+}
+
+// The plugin-facing `storage` and `metro` track their listeners, so `stopPlugin` sees any left behind.
+function trackedNamespaces(unbound: FakeUnbound, listeners: ListenerRegistry) {
+	const { storage, metro } = unbound;
+
+	return {
+		storage: {
+			...storage,
+			onChange: (...args: Parameters<typeof storage.onChange>) =>
+				listeners.track('storage.onChange', storage.onChange(...args)),
+		},
+		metro: {
+			...metro,
+			onModuleLoad: (listener: Parameters<typeof metro.onModuleLoad>[0]) =>
+				listeners.track('metro.onModuleLoad', metro.onModuleLoad(listener)),
+			onModuleLoaded: (...args: Parameters<typeof metro.onModuleLoaded>) =>
+				listeners.track('metro.onModuleLoaded', metro.onModuleLoaded(...args)),
+		},
+	};
+}
+
+// Runs the export of the plugin's src/actions.ts a settings button names, as the client's panel does.
+async function runAction(pluginRoot: string, name: string): Promise<void> {
+	const path = join(pluginRoot, 'src', 'actions.ts');
+
+	if (!existsSync(path)) {
+		throw new Error(`Failed to run action ${name}: ${pluginRoot} has no src/actions.ts.`);
+	}
+
+	const actions: unknown = await import(path);
+	const action =
+		typeof actions === 'object' && actions !== null ? Reflect.get(actions, name) : void 0;
+
+	if (typeof action !== 'function') {
+		throw new Error(`Failed to run action ${name}: src/actions.ts exports no such function.`);
+	}
+
+	await action();
+}
+
+function resolveImport(root: string, path: string, importer: string): string {
+	return path.startsWith('~/')
+		? join(root, 'src', path.slice(2))
+		: resolve(dirname(importer), path);
+}
+
+function svgComponent(asset: string, xml: string) {
+	function SvgImage(props: SvgProps) {
+		return createElement('SvgXml', { xml, asset, ...props });
+	}
+
+	SvgImage.displayName = `Svg(${asset})`;
+
+	return SvgImage;
+}
+
+async function readSettings(root: string): Promise<SettingsSchema | undefined> {
+	const path = join(root, 'settings.ts');
+
+	if (!existsSync(path)) return;
+
+	const module: unknown = await import(path);
+	const schema: unknown =
+		typeof module === 'object' && module !== null ? Reflect.get(module, 'default') : void 0;
+
+	if (!isSettingsSchema(schema)) {
+		throw new Error(`Failed to read ${path}: its default export is not defineSettings(...).`);
+	}
+
+	return schema;
+}
+
+const root = findPluginRoot();
+const manifest = readManifest(root);
+const listeners = createListenerRegistry();
+const tables = readLocaleTables(root);
+const locales = tables.size ? createFakeLocales(tables) : undefined;
+const source = tables.get(SOURCE_LOCALE) ?? {};
+const lookup = locales
+	? { resolveMessage: locales.format, takesVars: (key: string) => hasPlaceholders(source[key]) }
+	: KEY_LOOKUP;
+const toasts = createFakeToasts(() => lookup);
+const dialogs = createFakeDialogs(() => lookup);
+const flux = createFakeFlux(listeners);
+const assets = createFakeAssets(listeners);
+const native = createFakeNative();
+const fs = createFakeFs();
+const reactNative = createFakeReactNative(() => native.state.platform);
+const scope = installAddonGlobals({
+	manifest,
+	unbound: {
+		toasts,
+		dialogs,
+		flux,
+		assets,
+		native: native.namespace,
+		ui: createFakeUi(),
+		utils: createFakeUtils(),
+		fs,
+	},
+});
+
+const plugins = createFakePlugins(scope.addon.manifest);
+
+scope.unbound.plugins = plugins.namespace;
+Object.assign(scope.unbound, trackedNamespaces(scope.unbound, listeners));
+// On device the scope's `React` is Discord's real one; the fake one cannot re-render.
+Reflect.set(globalThis, 'React', React);
+Object.assign(scope.metro.common, { React, ReactNative: reactNative });
+Object.assign(scope.metro.stores, {
+	Accessibility: flux.getStore('Accessibility'),
+	Theme: flux.getStore('Theme'),
+	Users: flux.getStore('User'),
+	Guilds: flux.getStore('Guild'),
+});
+
+mock.module('react-native', () => reactNative);
+mock.module('@unbound-app/api', () => scope.unbound);
+
+for (const [name, namespace] of Object.entries(scope.unbound)) {
+	mock.module(`@unbound-app/api/${name}`, () => namespace);
+
+	// A namespace that nests others serves each one at its own path, such as `@unbound-app/api/metro/components`.
+	for (const [nested, members] of Object.entries(namespace)) {
+		if (NESTED.get(name)?.includes(nested)) {
+			mock.module(`@unbound-app/api/${name}/${nested}`, () => members);
+		}
+	}
+}
+
+for (const [specifier, runtime] of Object.entries(createJsxRuntimes())) {
+	mock.module(specifier, () => runtime);
+}
+
+if (locales) {
+	mock.module('@unbound-app/i18n', () => ({
+		messages: locales.messages,
+		format: locales.format,
+		useMessages: locales.useMessages,
+	}));
+}
+
+mock.module('@unbound-app/settings/schema', () => ({
+	setting,
+	defineSettings,
+	default: { setting, defineSettings },
+}));
+
+const schema = await readSettings(root);
+const settings = schema
+	? createFakeSettings(schema, scope.storage, scope.addon.id, {
+			translate: (key) => locales?.messages[key] ?? key,
+			runAction: (name) => runAction(root, name),
+		})
+	: undefined;
+
+if (settings) {
+	mock.module('@unbound-app/settings', () => ({
+		settings: settings.settings,
+		useSetting: settings.useSetting,
+		resetSettings: settings.resetSettings,
+		SettingsPanel: settings.SettingsPanel,
+		getSettingsPanel: settings.getSettingsPanel,
+	}));
+}
+
+plugin({
+	name: 'unbound-test-assets',
+	setup(build) {
+		build.onResolve({ filter: SVG_ASSET }, ({ path, importer }) => ({
+			path: resolveImport(root, path.slice(0, -'?asset'.length), importer),
+			namespace: SVG_ASSET_NAMESPACE,
+		}));
+		build.onLoad({ filter: /.*/, namespace: SVG_ASSET_NAMESPACE }, ({ path }) => ({
+			loader: 'object',
+			exports: { default: assets.getIdByName(assetNameOf(root, path), 'png') },
+		}));
+		build.onLoad({ filter: IMAGE }, ({ path }) => ({
+			loader: 'object',
+			exports: { default: assets.getIdByName(assetNameOf(root, path)) },
+		}));
+		build.onLoad({ filter: SVG }, ({ path }) => ({
+			loader: 'object',
+			exports: { default: svgComponent(assetNameOf(root, path), readFileSync(path, 'utf8')) },
+		}));
+	},
+});
+
+startSession({
+	root,
+	entry: findEntry(root),
+	scope,
+	listeners,
+	toasts,
+	dialogs,
+	flux,
+	assets,
+	locales,
+	settings,
+	native,
+	plugins,
+	fs,
+});
+
+beforeEach(() => {
+	forgetPlugin();
+	resetSession();
+});
+
+afterEach(unmountAll);

package/testing/react-patcher.ts

@@ -0,0 +1,154 @@
+import type { AnyObject, PatchParent, ReactPatcher } from '../src/patcher';
+
+type PatchKind = 'before' | 'instead' | 'after';
+
+// UNKNOWN: a patched render takes and returns whatever the component under test does.
+type Method = (...args: never[]) => unknown;
+
+/** The context the recording patcher hands a method patch. */
+export type MethodContext = {
+	args: never[];
+	this: PatchParent;
+	original: Method;
+	result: unknown;
+};
+
+// UNKNOWN: a method patch returns whatever the test's patch returns.
+type MethodCallback = (context: MethodContext) => unknown;
+
+/** Where a patch lands once its target is known: the object holding the method, the method, and the callback to run. */
+export type Placement = { parent: PatchParent; method: string; callback: MethodCallback };
+
+/** Patches what `place` finds on the target, waiting for a lazy handle's module as the client's `patchWhenLoaded` does. */
+export type Install = (
+	kind: PatchKind,
+	target: PatchParent,
+	place: (module: PatchParent) => Placement,
+	/** The method's name, listed for the patch while it waits for its module. */
+	method?: string,
+) => () => void;
+
+type Render = { parent: PatchParent; method: string; isClass: boolean };
+
+// UNKNOWN: the props, instance and tree of a component under test are whatever it renders with.
+type ReactContext = {
+	props: unknown;
+	this: unknown;
+	result: unknown;
+	original: ReactRender;
+};
+
+// UNKNOWN: renders the untyped component with untyped props.
+type ReactRender = (props?: unknown) => unknown;
+
+// UNKNOWN: a React patch returns a tree or new props.
+type ReactCallback = (context: ReactContext) => unknown;
+
+const MEMO = Symbol.for('react.memo');
+const FORWARD_REF = Symbol.for('react.forward_ref');
+
+function isCallback(value: unknown): value is ReactCallback {
+	return typeof value === 'function';
+}
+
+// UNKNOWN: any export, function or not, may be a class component.
+function isClass(component: unknown): boolean {
+	return typeof component === 'function' && Boolean(component.prototype?.isReactComponent);
+}
+
+// Unwraps `memo` to what React calls, as the client's patcher does: the inner function, a `forwardRef`'s `render`, or a class's `prototype.render`.
+function renderOf(component: AnyObject | undefined): Render | undefined {
+	if (isClass(component)) {
+		return { parent: component?.prototype, method: 'render', isClass: true };
+	}
+
+	if (component?.$$typeof === FORWARD_REF) {
+		return { parent: component, method: 'render', isClass: false };
+	}
+
+	if (component?.$$typeof !== MEMO) return;
+
+	return typeof component.type === 'function' && !isClass(component.type)
+		? { parent: component, method: 'type', isClass: false }
+		: renderOf(component.type);
+}
+
+function locate(target: AnyObject, key: string | undefined): Render {
+	const component = key === undefined ? target : target[key];
+	const render =
+		key !== undefined && typeof component === 'function' && !isClass(component)
+			? { parent: target, method: key, isClass: false }
+			: renderOf(component);
+
+	if (!render) {
+		throw new TypeError(
+			`Failed to patch component ${key ?? String(component)}: pass the object holding a function component and its key.`,
+		);
+	}
+
+	return render;
+}
+
+/**
+ * @description Builds `patcher.react` on a recording patcher, so React patches wrap the render for real and are listed with the others.
+ * @param install The recording patcher's install, which defers a patch on a lazy handle until its module registers.
+ * @returns The `before`, `instead` and `after` hooks for React components.
+ */
+export function createReactPatcher(install: Install): ReactPatcher {
+	function hook(kind: PatchKind) {
+		return (target: AnyObject, ...args: unknown[]) => {
+			const [key, callback] = isCallback(args[0])
+				? [undefined, args[0]]
+				: [String(args[0]), args[1]];
+
+			if (!isCallback(callback)) {
+				throw new TypeError('Failed to patch a component: pass a callback.');
+			}
+
+			return install(
+				kind,
+				target,
+				(module) => {
+					const render = locate(module, key);
+
+					return {
+						parent: render.parent,
+						method: render.method,
+						callback(context) {
+							const props = render.isClass
+								? Reflect.get(context.this, 'props')
+								: context.args[0];
+							const rest = context.args.slice(1);
+							const value = callback({
+								props,
+								this: render.isClass ? context.this : undefined,
+								result: context.result,
+								original: (next = props) =>
+									render.isClass
+										? context.original()
+										: context.original(...([next, ...rest] as never[])),
+							});
+
+							if (kind !== 'before') {
+								return value;
+							}
+
+							return !render.isClass && value !== undefined
+								? [value, ...rest]
+								: undefined;
+						},
+					};
+				},
+				key,
+			);
+		};
+	}
+
+	const patcher: ReactPatcher = {
+		before: hook('before'),
+		instead: hook('instead'),
+		after: hook('after'),
+	};
+
+	return patcher;
+}

package/testing/react-value.ts

@@ -0,0 +1,3 @@
+// UNKNOWN: React hands the test renderer whatever the component under test gives it: state, props, refs and children.
+/** A value React passes through the test renderer's hooks and renders, typed by the component, not by the renderer. */
+export type ReactValue = unknown;