@chipmobilesdk/rn-camera 0.2.1 → 0.4.0

package/src/react/hooks.ts

@@ -15,7 +15,7 @@ import {
 	type CameraControllerOptions,
 } from '../core/controller';
 
-export function useCameraController(options: CameraControllerOptions = {}): CameraController {
+export function useCameraController(options: CameraControllerOptions): CameraController {
 	// Options usually arrive as a fresh object literal each render; capturing
 	// them in a ref keeps the controller stable for the component's lifetime.
 	const optionsRef = useRef(options);

package/src/storage/artifactStore.ts

@@ -7,6 +7,8 @@
  * the package can refuse to delete anything it did not create (FR-028).
  */
 
+import { CameraError } from '../diagnostics/errors';
+
 export interface ArtifactStore {
 	/** Absolute path of the package-owned temporary directory. */
 	temporaryDirectory(): string;
@@ -112,7 +114,10 @@ export function createArtifactStore(
 				return uri;
 			}
 			if (!fs.move) {
-				throw new Error('This FileSystemBridge has no move(), so it cannot adopt a capture');
+				throw new CameraError(
+					'storageFailure',
+					'This FileSystemBridge has no move(), so it cannot adopt a capture',
+				);
 			}
 			await fs.ensureDirectory(root);
 			const name = path.slice(path.lastIndexOf('/') + 1) || `capture-${Date.now()}.jpg`;
@@ -132,7 +137,9 @@ export function createArtifactStore(
 export function createCacheArtifactStore(options: StoreOptions = {}): ArtifactStore {
 	const fs = options.fs;
 	if (!fs) {
-		throw new Error(
+		// A typed error, like every other failure this package reports.
+		throw new CameraError(
+			'storageFailure',
 			'createCacheArtifactStore requires a FileSystemBridge. Pass `fs`, or use ' +
 				'createTestCamera() in tests.',
 		);

package/src/testing/conformance.ts

@@ -0,0 +1,140 @@
+/**
+ * What any `PermissionPort` and `CameraEngine` must do (IOS-12, CAM-13).
+ *
+ * The same checks run against the in-memory test adapter and against the real
+ * VisionCamera adapters (native module mocked in Jest, or for real on a device),
+ * so the fake the app's tests rely on cannot drift from the adapter it stands in
+ * for. Each check builds its own port from a harness, under the conditions it
+ * needs.
+ */
+import {
+	ensure,
+	runChecks,
+	type Check,
+	type ConformanceReport,
+} from '@chipmobilesdk/rn-core/testing';
+
+import type { CameraPermissionState } from '../config/types';
+import type { CameraEngine } from '../native/cameraEngine';
+import type { PermissionPort } from '../permissions/permissionPort';
+
+export type SystemPermission = 'undetermined' | 'granted' | 'deniedPermanently';
+
+export interface PermissionHarness {
+	/** A port over a system whose permission starts in `initial`. */
+	create(initial: SystemPermission): {
+		readonly port: PermissionPort;
+		/** Changes the system permission, as Settings would. */
+		setSystemState(state: SystemPermission): void;
+		/** How many times the system prompt was shown. */
+		prompts(): number;
+	};
+}
+
+export interface CameraDeviceSpec {
+	readonly position: 'front' | 'back';
+	readonly hasFlash?: boolean;
+	readonly hasTorch?: boolean;
+}
+
+export interface EngineHarness {
+	/** An engine on a device with these cameras. */
+	create(devices: readonly CameraDeviceSpec[]): CameraEngine;
+}
+
+export const permissionPortChecks: readonly Check<PermissionHarness>[] = [
+	{
+		name: 'reads the status without prompting',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			ensure((await system.port.getStatus()) === 'undetermined', 'expected undetermined');
+			ensure(system.prompts() === 0, 'getStatus prompted');
+		},
+	},
+	{
+		name: 'reports a grant after prompting once',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			const state = await system.port.request();
+			ensure(state === 'granted', `expected granted, got ${state}`);
+			ensure(system.prompts() === 1, `expected one prompt, got ${system.prompts()}`);
+		},
+	},
+	{
+		name: 'never prompts again after a permanent denial',
+		async run(harness) {
+			const system = harness.create('deniedPermanently');
+			const state = await system.port.request();
+			ensure(state === 'deniedPermanently', `expected deniedPermanently, got ${state}`);
+			ensure(system.prompts() === 0, 'prompted after a permanent denial');
+		},
+	},
+	{
+		name: 'tells subscribers about a change, and nothing after unsubscribing',
+		async run(harness) {
+			const system = harness.create('undetermined');
+			const seen: CameraPermissionState[] = [];
+			const unsubscribe = system.port.subscribe(state => seen.push(state));
+			await system.port.request();
+			ensure(seen.includes('granted'), `subscriber saw ${JSON.stringify(seen)}`);
+			unsubscribe();
+			unsubscribe();
+			const before = seen.length;
+			system.setSystemState('deniedPermanently');
+			await system.port.getStatus();
+			ensure(seen.length === before, 'notified after unsubscribing');
+		},
+	},
+];
+
+export const cameraEngineChecks: readonly Check<EngineHarness>[] = [
+	{
+		name: 'refuses to start without a camera, as cameraUnavailable',
+		async run(harness) {
+			const engine = harness.create([]);
+			let code: unknown;
+			try {
+				await engine.start({});
+			} catch (error) {
+				code = (error as { code?: unknown }).code;
+			}
+			ensure(code === 'cameraUnavailable', `expected cameraUnavailable, got ${String(code)}`);
+		},
+	},
+	{
+		name: 'starts when a camera exists',
+		async run(harness) {
+			await harness.create([{ position: 'back' }]).start({});
+		},
+	},
+	{
+		name: 'reports capabilities from the cameras present',
+		async run(harness) {
+			const capabilities = await harness
+				.create([{ position: 'back', hasTorch: true, hasFlash: true }, { position: 'front' }])
+				.getCapabilities();
+			ensure(capabilities.hasCameraHardware, 'no camera hardware reported');
+			ensure(capabilities.hasTorch && capabilities.hasFlash, 'torch or flash not reported');
+			const positions = [...capabilities.availablePositions].sort();
+			ensure(positions.join(',') === 'back,front', `positions ${positions.join(',')}`);
+		},
+	},
+	{
+		name: 'stops safely, even without a start and twice',
+		async run(harness) {
+			const engine = harness.create([{ position: 'back' }]);
+			await engine.stop();
+			await engine.stop();
+		},
+	},
+];
+
+export function runPermissionPortConformance(
+	harness: PermissionHarness,
+): Promise<ConformanceReport> {
+	return runChecks(() => harness, permissionPortChecks);
+}
+
+export function runCameraEngineConformance(harness: EngineHarness): Promise<ConformanceReport> {
+	return runChecks(() => harness, cameraEngineChecks);
+}

package/src/testing/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `@chipmobilesdk/rn-camera/testing`: test doubles and the port conformance suites.
+ *
+ * A separate entrypoint so the suites cannot reach a production bundle. The test
+ * adapter is also exported from the main entrypoint for compatibility; it leaves
+ * there only in a major release.
+ */
+
+export {
+	createTestCamera,
+	createMemoryFileSystem,
+	DEFAULT_TEST_CAPABILITIES,
+} from './testCameraAdapter';
+export type { MemoryFileSystem, TestCameraConfig, TestCameraHandles } from './testCameraAdapter';
+
+export {
+	cameraEngineChecks,
+	permissionPortChecks,
+	runCameraEngineConformance,
+	runPermissionPortConformance,
+} from './conformance';
+export type {
+	CameraDeviceSpec,
+	EngineHarness,
+	PermissionHarness,
+	SystemPermission,
+} from './conformance';

package/src/testing/testCameraAdapter.ts

@@ -7,6 +7,8 @@
  * filesystem, or a permission API.
  */
 
+import { createListenerSet } from '@chipmobilesdk/rn-core';
+
 import {
 	known,
 	unavailable,
@@ -25,6 +27,7 @@ import {
 	type FileSystemBridge,
 } from '../storage/artifactStore';
 import type { AppStatus } from '../core/controller';
+import { clampQuality } from '../core/captureController';
 
 export interface MemoryFileSystem extends FileSystemBridge {
 	/** Seeds a file with an explicit creation time, for time-to-live tests. */
@@ -96,10 +99,19 @@ export interface TestCameraHandles {
 	setAppState(status: AppStatus): void;
 	/** Simulates a Settings-level permission change while running (FR-007). */
 	setPermission(state: CameraPermissionState): void;
-	/** Simulates an OS preemption such as an incoming call. */
-	emitInterruption(): void;
+	/**
+	 * Simulates the OS taking the camera away: an incoming call, another app,
+	 * a disconnected device. A live session tears down with that code, exactly
+	 * as the device adapter reports it (CAM-19), and the next start fails until
+	 * `setStartError(null)` clears it.
+	 */
+	emitInterruption(code?: CameraErrorCode): void;
+	/** Simulates the preview failing to produce frames. */
+	emitPermissionRequestFailure(enabled: boolean): void;
 	setCaptureError(code: CameraErrorCode | null): void;
 	setStartError(code: CameraErrorCode | null): void;
+	/** How many times `request` showed the system prompt. */
+	prompts(): number;
 	/** Every capture the engine produced, in order. */
 	captures(): readonly CapturedImage[];
 	torchState(): boolean;
@@ -122,37 +134,42 @@ export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandl
 	let starts = 0;
 	let stops = 0;
 	let sequence = 0;
+	let promptCount = 0;
 
 	const produced: CapturedImage[] = [];
-	const permissionListeners = new Set<(state: CameraPermissionState) => void>();
-	const appStateListeners = new Set<(status: AppStatus) => void>();
-	const interruptionListeners = new Set<() => void>();
+	// The same listener sets as the real adapters, so a throwing subscriber behaves
+	// identically here and on a device.
+	const permissionListeners = createListenerSet<[CameraPermissionState]>();
+	const appStateListeners = createListenerSet<[AppStatus]>();
+	const interruptionListeners = createListenerSet<[CameraErrorCode]>();
+	let requestThrows = false;
 
 	const permissions: PermissionPort = {
 		async getStatus() {
 			return permission;
 		},
 		async request() {
+			if (requestThrows) {
+				// What a native module that cannot be reached does.
+				throw new Error('permission request failed');
+			}
 			// Mirrors the real adapter: never re-prompt after a permanent denial.
 			if (permission === 'deniedPermanently') {
 				return permission;
 			}
-			permission =
-				permission === 'undetermined' || permission === 'denied' ? 'granted' : permission;
-			for (const listener of permissionListeners) {
-				listener(permission);
+			if (permission === 'undetermined' || permission === 'denied') {
+				promptCount += 1;
+				permission = 'granted';
 			}
+			permissionListeners.notify(permission);
 			return permission;
 		},
-		subscribe(listener) {
-			permissionListeners.add(listener);
-			return () => {
-				permissionListeners.delete(listener);
-			};
-		},
+		subscribe: listener => permissionListeners.add(listener),
 	};
 
 	const engine: CameraEngine = {
+		subscribeToInterruptions: listener => interruptionListeners.add(listener),
+
 		async start() {
 			starts += 1;
 			if (startError) {
@@ -185,7 +202,8 @@ export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandl
 				timestamp: Date.now(),
 				cameraPosition: position,
 				ownership: request.destination ? 'appOwned' : 'packageTemporary',
-				effectiveQuality: request.quality ?? 0.9,
+				// Clamped the way the real path clamps it, not a second copy of 0.9.
+				effectiveQuality: clampQuality(request.quality),
 				effectiveMaxDimension:
 					request.maxDimension === undefined ? unavailable() : known(request.maxDimension),
 				fileSize: known(1024),
@@ -211,33 +229,26 @@ export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandl
 		store,
 		fs,
 
-		subscribeToAppState(listener) {
-			appStateListeners.add(listener);
-			return () => {
-				appStateListeners.delete(listener);
-			};
-		},
+		subscribeToAppState: listener => appStateListeners.add(listener),
 
 		setAppState(status) {
-			for (const listener of appStateListeners) {
-				listener(status);
-			}
+			appStateListeners.notify(status);
 		},
 
 		setPermission(state) {
 			permission = state;
-			for (const listener of permissionListeners) {
-				listener(state);
-			}
+			permissionListeners.notify(state);
 		},
 
-		emitInterruption() {
-			for (const listener of interruptionListeners) {
-				listener();
-			}
-			// An interruption behaves like the OS taking the camera away: the next
-			// start attempt fails until the app clears it.
-			startError = 'interrupted';
+		emitInterruption(code: CameraErrorCode = 'interrupted') {
+			// The OS took the camera away. A live session hears about it, and the
+			// next start attempt fails until the app clears it.
+			startError = code;
+			interruptionListeners.notify(code);
+		},
+
+		emitPermissionRequestFailure(enabled) {
+			requestThrows = enabled;
 		},
 
 		setCaptureError(code) {
@@ -248,6 +259,7 @@ export function createTestCamera(config: TestCameraConfig = {}): TestCameraHandl
 			startError = code;
 		},
 
+		prompts: () => promptCount,
 		captures: () => produced,
 		torchState: () => torch,
 		startCount: () => starts,