TagSpaces is an offline, open source, document manager with tagging support
chore: added unit tests for capacitor-ui-utils
Ilian Sapundshiev68a4164e5ffe
diff --git a/src/renderer/services/capacitor-io-utils.ts b/src/renderer/services/capacitor-io-utils.tsnew file mode 100644index 000000000..945f939f3--- /dev/null+++ b/src/renderer/services/capacitor-io-utils.ts@@ -0,0 +1,200 @@+/**+ * TagSpaces - universal file and folder organizer+ * Copyright (C) 2017-present TagSpaces GmbH+ *+ * This program is free software: you can redistribute it and/or modify+ * it under the terms of the GNU Affero General Public License (version 3) as+ * published by the Free Software Foundation.+ *+ * This program is distributed in the hope that it will be useful,+ * but WITHOUT ANY WARRANTY; without even the implied warranty of+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+ * GNU Affero General Public License for more details.+ *+ * You should have received a copy of the GNU Affero General Public License+ * along with this program. If not, see <https://www.gnu.org/licenses/>.+ */++/**+ * Pure, dependency-free helpers extracted from io-capacitor.ts so the core+ * logic (path → Directory mapping, binary→base64 encoding, write-content+ * classification) can be unit-tested in Node without the native Capacitor+ * bridge. The `platform`, `Directory` and `Encoding` values are injected by the+ * caller (io-capacitor.ts passes `Capacitor.getPlatform()`, `Directory` and+ * `Encoding`) so these functions are deterministic.+ */++export interface CapacitorDirectories {+ Documents: string;+ ExternalStorage: string;+}++export interface ResolvedCapacitorPath {+ path: string;+ directory: string | undefined;+}++/**+ * Determine the Capacitor Directory enum value and relative path from an+ * absolute/location-relative path.+ * - iOS: relative to Directory.Documents (the App Documents location stores "/",+ * which maps to the Documents root → "."). iCloud ubiquity-container paths+ * ("/Mobile Documents/" or "file://…") are passed through as percent-encoded+ * raw file:// URLs with no `directory`.+ * - Android (MANAGE_EXTERNAL_STORAGE): everything maps to Directory.ExternalStorage,+ * stripping the sdcard / storage prefixes to a relative path.+ */+export function resolveCapacitorPath(+ absolutePath: string,+ platform: string,+ Directory: CapacitorDirectories,+): ResolvedCapacitorPath {+ let path = absolutePath;++ if (platform === 'ios') {+ // iCloud ubiquity-container paths live outside the app sandbox, so they+ // can't be addressed relative to Directory.Documents. They are passed as+ // raw absolute paths (containing "/Mobile Documents/"). @capacitor/filesystem+ // addresses raw paths when no `directory` is given, but resolves them with+ // URL(string:) — which returns nil for unencoded spaces. So build a+ // percent-encoded file:// URL here (slashes preserved, spaces → %20).+ if (path.startsWith('file://') || path.includes('/Mobile Documents/')) {+ const abs = path.startsWith('file://') ? path.substring(7) : path;+ const encoded = abs.split('/').map(encodeURIComponent).join('/');+ return { path: 'file://' + encoded, directory: undefined };+ }+ // iOS: paths are relative to Documents directory+ if (path.startsWith('/')) {+ path = path.substring(1);+ }+ // Root of Documents = empty string or just "/" → use "." for Capacitor+ if (!path || path === '') {+ path = '.';+ }+ return { path, directory: Directory.Documents };+ }++ // Android: use ExternalStorage for sdcard paths+ if (path.startsWith('sdcard/')) {+ path = path.substring(7); // Remove 'sdcard/' prefix+ if (!path || path === '') path = '.';+ return { path, directory: Directory.ExternalStorage };+ }+ if (path.startsWith('/sdcard/')) {+ path = path.substring(8);+ if (!path || path === '') path = '.';+ return { path, directory: Directory.ExternalStorage };+ }+ if (path.startsWith('/storage/emulated/0/')) {+ path = path.substring(20);+ if (!path || path === '') path = '.';+ return { path, directory: Directory.ExternalStorage };+ }+ if (path.startsWith('/')) {+ // Absolute path — use ExternalStorage with relative path+ // For paths outside /storage/emulated/0, this may need MANAGE_EXTERNAL_STORAGE+ path = path.substring(1);+ if (!path || path === '') path = '.';+ return { path, directory: Directory.ExternalStorage };+ }++ if (!path || path === '') path = '.';+ return { path, directory: Directory.ExternalStorage };+}++/** Collapse any run of 2+ slashes into one. Passes through falsy input. */+export function normalizePath(path: string): string {+ if (!path) return path;+ return path.replace(/\/+/g, '/');+}++/**+ * Standard device folder map per platform. Keys deliberately match the+ * core.json translation keys (*Folder) so auto-created locations and the+ * onboarding slide get localized names instead of raw keys.+ */+export function getDevicePathsForPlatform(+ platform: string,+): Record<string, string> {+ if (platform === 'ios') {+ // The app's sandboxed Documents directory. iCloud Drive is resolved+ // separately via getICloudContainer().+ return {+ appDocumentsFolder: '/',+ };+ }+ return {+ dcimFolder: 'sdcard/DCIM/',+ documentsFolder: 'sdcard/Documents/',+ downloadsFolder: 'sdcard/Download/',+ picturesFolder: 'sdcard/Pictures/',+ moviesFolder: 'sdcard/Movies/',+ };+}++/**+ * Convert an ArrayBuffer or any TypedArray *view* (Uint8Array, etc.) to a base64+ * string. Critical: base64ToUint8Array() returns a Uint8Array, which is a view —+ * `instanceof ArrayBuffer` is false. Without the `ArrayBuffer.isView` branch the+ * thumbnail save path falls through to btoa(String(Uint8Array)) and writes+ * "MCwxLDIs..." junk to disk, producing zero-thumbnails on iOS/Android Capacitor.+ */+export function binaryToBase64(blob: ArrayBuffer | ArrayBufferView): string {+ const bytes =+ blob instanceof ArrayBuffer+ ? new Uint8Array(blob)+ : new Uint8Array(blob.buffer, blob.byteOffset, blob.byteLength);+ // Chunked to avoid blowing the JS engine's argument limit on large payloads+ // (apply spreads each byte as a separate argument).+ let binary = '';+ const CHUNK = 0x8000;+ for (let i = 0; i < bytes.length; i += CHUNK) {+ binary += String.fromCharCode.apply(+ null,+ bytes.subarray(i, i + CHUNK) as any,+ );+ }+ return btoa(binary);+}++export interface WriteContentPlan {+ // 'text' → write data as-is with the given encoding (UTF8)+ // 'base64' → write data (already-extracted base64) with no encoding+ // 'binary' → caller must convert the original content to base64 (async)+ mode: 'text' | 'base64' | 'binary';+ data?: string;+ encoding?: string;+}++/**+ * Decide how a value passed to saveFilePromise should be written:+ * - isRaw + string → text (UTF8)+ * - non-raw data: URI → extract the base64 payload, write as base64+ * - non-raw string → text (UTF8)+ * - anything non-string → binary (caller base64-encodes the bytes)+ *+ * The async base64 conversion is intentionally left to the caller so this+ * function stays pure/synchronous.+ */+export function classifyWriteContent(+ content: any,+ isRaw: boolean,+ Encoding: { UTF8: string },+): WriteContentPlan {+ if (isRaw) {+ if (typeof content === 'string') {+ return { mode: 'text', data: content, encoding: Encoding.UTF8 };+ }+ return { mode: 'binary' };+ }+ if (typeof content === 'string' && content.indexOf(';base64,') > 0) {+ // Data URI with base64+ const contentArray = content.split(';base64,');+ const data = contentArray.length > 1 ? contentArray[1] : contentArray[0];+ return { mode: 'base64', data };+ }+ if (typeof content === 'string') {+ return { mode: 'text', data: content, encoding: Encoding.UTF8 };+ }+ return { mode: 'binary' };+}diff --git a/src/renderer/services/io-capacitor.ts b/src/renderer/services/io-capacitor.tsindex dc003db7c..dfbdabfba 100644--- a/src/renderer/services/io-capacitor.ts+++ b/src/renderer/services/io-capacitor.ts@@ -16,6 +16,8 @@ const {getMetaFileLocationForDir,getThumbFileLocationForDirectory,} = require('@tagspaces/tagspaces-common/paths');+// Pure (native-free) helpers, separated so they can be unit-tested in Node.+const U = require('./capacitor-io-utils');// Capacitor importsconst { Capacitor } = require('@capacitor/core');@@ -95,72 +97,23 @@ function getNativeFileUrlAsync(path) {}/**- * Determine the Capacitor Directory enum value and relative path from an absolute path.- * On Android with MANAGE_EXTERNAL_STORAGE, we work with absolute paths via ExternalStorage.- * On iOS, we work relative to the Documents directory.+ * Determine the Capacitor Directory enum value and relative path from an absolute+ * path. Thin wrapper around the pure helper (unit-tested in capacitor-io-utils),+ * injecting the runtime platform + Directory enum.*/function resolveCapacitorPath(absolutePath) {- const platform = Capacitor.getPlatform();- let path = absolutePath;-- if (platform === 'ios') {- // iCloud ubiquity-container paths live outside the app sandbox, so they- // can't be addressed relative to Directory.Documents. They are passed as- // raw absolute paths (containing "/Mobile Documents/"). @capacitor/filesystem- // addresses raw paths when no `directory` is given, but resolves them with- // URL(string:) — which returns nil for unencoded spaces. So build a- // percent-encoded file:// URL here (slashes preserved, spaces → %20).- if (path.startsWith('file://') || path.includes('/Mobile Documents/')) {- const abs = path.startsWith('file://') ? path.substring(7) : path;- const encoded = abs.split('/').map(encodeURIComponent).join('/');- return { path: 'file://' + encoded, directory: undefined };- }- // iOS: paths are relative to Documents directory- if (path.startsWith('/')) {- path = path.substring(1);- }- // Root of Documents = empty string or just "/" → use "." for Capacitor- if (!path || path === '') {- path = '.';- }- return { path, directory: Directory.Documents };- }-- // Android: use ExternalStorage for sdcard paths- if (path.startsWith('sdcard/')) {- path = path.substring(7); // Remove 'sdcard/' prefix- if (!path || path === '') path = '.';- return { path, directory: Directory.ExternalStorage };- }- if (path.startsWith('/sdcard/')) {- path = path.substring(8);- if (!path || path === '') path = '.';- return { path, directory: Directory.ExternalStorage };- }- if (path.startsWith('/storage/emulated/0/')) {- path = path.substring(20);- if (!path || path === '') path = '.';- return { path, directory: Directory.ExternalStorage };- }- if (path.startsWith('/')) {- // Absolute path — use ExternalStorage with relative path- // For paths outside /storage/emulated/0, this may need MANAGE_EXTERNAL_STORAGE- path = path.substring(1);- if (!path || path === '') path = '.';- return { path, directory: Directory.ExternalStorage };- }-- if (!path || path === '') path = '.';- return { path, directory: Directory.ExternalStorage };+ return U.resolveCapacitorPath(+ absolutePath,+ Capacitor.getPlatform(),+ Directory,+ );}/*** Normalize a path for internal use (strip leading slash inconsistencies)*/function normalizePath(path) {- if (!path) return path;- // Remove double slashes- return path.replace(/\/+/g, '/');+ return U.normalizePath(path);}// --- Lifecycle ---@@ -360,27 +313,7 @@ function loadSettingsTags() {// --- Platform API ---function getDevicePaths() {- let paths;- if (Capacitor.getPlatform() === 'ios') {- // The app's sandboxed Documents directory. iCloud Drive is resolved- // separately via getICloudContainer() — it is async and only available- // when the user is signed in to iCloud, so it can't be returned here.- paths = {- appDocumentsFolder: '/',- };- } else {- // Standard Android shared-storage folders. Keys deliberately match the- // core.json translation keys (*Folder) so auto-created locations and the- // onboarding slide get localized names instead of raw keys.- paths = {- dcimFolder: 'sdcard/DCIM/',- documentsFolder: 'sdcard/Documents/',- downloadsFolder: 'sdcard/Download/',- picturesFolder: 'sdcard/Pictures/',- moviesFolder: 'sdcard/Movies/',- };- }- return Promise.resolve(paths);+ return Promise.resolve(U.getDevicePathsForPlatform(Capacitor.getPlatform()));}/**@@ -708,34 +641,18 @@ function saveFilePromise(param, content, overWrite, isRaw) {const { path: capPath, directory } = resolveCapacitorPath(filePath);+ // Decide how to write the content (text / extracted-base64 / binary). The+ // routing is unit-tested in capacitor-io-utils.classifyWriteContent; the+ // async base64 conversion stays here.+ const plan = U.classifyWriteContent(content, isRaw, Encoding);let data;let encoding;-- if (isRaw) {- // Raw text content- if (typeof content === 'string') {- data = content;- encoding = Encoding.UTF8;- } else {- // Blob or ArrayBuffer — convert to base64- data = await blobToBase64(content);- encoding = undefined;- }- } else if (- typeof content === 'string' &&- content.indexOf(';base64,') > 0- ) {- // Data URI with base64- const contentArray = content.split(';base64,');- data = contentArray.length > 1 ? contentArray[1] : contentArray[0];- encoding = undefined; // base64 mode- } else if (typeof content === 'string') {- data = content;- encoding = Encoding.UTF8;- } else {- // Blob or ArrayBuffer+ if (plan.mode === 'binary') {data = await blobToBase64(content);encoding = undefined;+ } else {+ data = plan.data;+ encoding = plan.encoding;}const writeOptions = {@@ -767,28 +684,12 @@ function saveFilePromise(param, content, overWrite, isRaw) {function blobToBase64(blob) {return new Promise((resolve, reject) => {- // Handle ArrayBuffer and any TypedArray view (Uint8Array, etc.).- // Critical: base64ToUint8Array() returns a Uint8Array, which is a *view*- // — `instanceof ArrayBuffer` is false. Without this branch the thumbnail- // save path (saveThumbnailPromise → saveBinaryFilePromise) falls through- // to btoa(String(Uint8Array)) and writes "MCwxLDIs..." junk to disk,- // producing zero-thumbnails on iOS/Android Capacitor.+ // Handle ArrayBuffer and any TypedArray view (Uint8Array, etc.). The view+ // case is critical: base64ToUint8Array() returns a Uint8Array view, and+ // mishandling it writes "MCwxLDIs..." junk → zero-thumbnails. The encoding+ // logic lives in capacitor-io-utils.binaryToBase64 (unit-tested).if (blob instanceof ArrayBuffer || ArrayBuffer.isView(blob)) {- const bytes =- blob instanceof ArrayBuffer- ? new Uint8Array(blob)- : new Uint8Array(blob.buffer, blob.byteOffset, blob.byteLength);- // Chunked to avoid blowing the JS engine's argument limit on large- // payloads (apply spreads each byte as a separate argument).- let binary = '';- const CHUNK = 0x8000;- for (let i = 0; i < bytes.length; i += CHUNK) {- binary += String.fromCharCode.apply(- null,- bytes.subarray(i, i + CHUNK) as any,- );- }- resolve(btoa(binary));+ resolve(U.binaryToBase64(blob));return;}if (blob instanceof Blob) {diff --git a/tests/unit/capacitor-io-utils.test.js b/tests/unit/capacitor-io-utils.test.jsnew file mode 100644index 000000000..02ff5bc7e--- /dev/null+++ b/tests/unit/capacitor-io-utils.test.js@@ -0,0 +1,207 @@+import { describe, expect, test } from '@playwright/test';+import {+ resolveCapacitorPath,+ normalizePath,+ getDevicePathsForPlatform,+ binaryToBase64,+ classifyWriteContent,+} from '-/services/capacitor-io-utils';++const {+ getThumbFileLocationForFile,+ getMetaFileLocationForFile,+ cleanTrailingDirSeparator,+} = require('@tagspaces/tagspaces-common/paths');++// Injected enums (mock the @capacitor/filesystem values).+const Directory = { Documents: 'DOCUMENTS', ExternalStorage: 'EXTERNAL_STORAGE' };+const Encoding = { UTF8: 'utf8' };++const ios = (p) => resolveCapacitorPath(p, 'ios', Directory);+const android = (p) => resolveCapacitorPath(p, 'android', Directory);++describe('capacitor-io-utils', () => {+ // A. iOS path resolution — the App Documents location stores path "/".+ describe('resolveCapacitorPath — iOS', () => {+ test('file under root maps to Documents (relative, no leading slash)', () => {+ expect(ios('/IMG.jpeg')).toEqual({+ path: 'IMG.jpeg',+ directory: 'DOCUMENTS',+ });+ });+ test('meta/thumb path under root', () => {+ expect(ios('/.ts/IMG.jpeg.jpg')).toEqual({+ path: '.ts/IMG.jpeg.jpg',+ directory: 'DOCUMENTS',+ });+ });+ test('root "/" and "" become "."', () => {+ expect(ios('/')).toEqual({ path: '.', directory: 'DOCUMENTS' });+ expect(ios('')).toEqual({ path: '.', directory: 'DOCUMENTS' });+ });+ test('raw file:// path passes through encoded, no directory', () => {+ expect(ios('file:///var/x.jpg')).toEqual({+ path: 'file:///var/x.jpg',+ directory: undefined,+ });+ });+ test('iCloud "Mobile Documents" path is percent-encoded, no directory', () => {+ const res = ios(+ '/private/var/mobile/Library/Mobile Documents/iCloud~org/Documents/My File.jpg',+ );+ expect(res.directory).toBeUndefined();+ expect(res.path).toBe(+ 'file:///private/var/mobile/Library/Mobile%20Documents/iCloud~org/Documents/My%20File.jpg',+ );+ });+ });++ // B. Android path resolution — everything maps to ExternalStorage.+ describe('resolveCapacitorPath — Android', () => {+ test('strips sdcard/ and /sdcard/ prefixes', () => {+ expect(android('sdcard/DCIM/x.jpg')).toEqual({+ path: 'DCIM/x.jpg',+ directory: 'EXTERNAL_STORAGE',+ });+ expect(android('/sdcard/DCIM/x.jpg')).toEqual({+ path: 'DCIM/x.jpg',+ directory: 'EXTERNAL_STORAGE',+ });+ });+ test('strips /storage/emulated/0/ prefix', () => {+ expect(android('/storage/emulated/0/Download/x.jpg')).toEqual({+ path: 'Download/x.jpg',+ directory: 'EXTERNAL_STORAGE',+ });+ });+ test('other absolute paths drop the leading slash', () => {+ expect(android('/some/abs/x.jpg')).toEqual({+ path: 'some/abs/x.jpg',+ directory: 'EXTERNAL_STORAGE',+ });+ });+ test('relative path is unchanged; empty becomes "."', () => {+ expect(android('relative/x.jpg')).toEqual({+ path: 'relative/x.jpg',+ directory: 'EXTERNAL_STORAGE',+ });+ expect(android('')).toEqual({ path: '.', directory: 'EXTERNAL_STORAGE' });+ });+ });++ // C. binaryToBase64 — the "MCwxLDIs..." junk regression.+ describe('binaryToBase64', () => {+ test('Uint8Array view encodes bytes, NOT the stringified array', () => {+ const result = binaryToBase64(new Uint8Array([0, 1, 2, 3]));+ expect(result).toBe('AAECAw=='); // correct+ expect(result).not.toBe('MCwxLDIsMw=='); // btoa(String(view)) junk+ });+ test('ArrayBuffer input encodes the same as its view', () => {+ const view = new Uint8Array([65, 66, 67]); // "ABC"+ expect(binaryToBase64(view)).toBe('QUJD');+ expect(binaryToBase64(view.buffer)).toBe('QUJD');+ });+ test('sub-array view encodes only its own bytes (byteOffset honored)', () => {+ const full = new Uint8Array([9, 9, 65, 66, 67, 9]);+ const sub = full.subarray(2, 5); // bytes 65,66,67 at non-zero offset+ expect(binaryToBase64(sub)).toBe('QUJD');+ });+ test('large payload (> 0x8000) does not throw and round-trips', () => {+ const n = 0x8000 + 123;+ const bytes = new Uint8Array(n);+ for (let i = 0; i < n; i++) bytes[i] = i % 256;+ const b64 = binaryToBase64(bytes);+ const decoded = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));+ expect(decoded.length).toBe(n);+ expect(decoded[0]).toBe(0);+ expect(decoded[n - 1]).toBe((n - 1) % 256);+ });+ });++ // D. classifyWriteContent — write routing.+ describe('classifyWriteContent', () => {+ test('raw string → text/UTF8', () => {+ expect(classifyWriteContent('hello', true, Encoding)).toEqual({+ mode: 'text',+ data: 'hello',+ encoding: 'utf8',+ });+ });+ test('data: URI → base64 with extracted payload, no encoding', () => {+ expect(+ classifyWriteContent('data:image/jpeg;base64,QUJD', false, Encoding),+ ).toEqual({ mode: 'base64', data: 'QUJD' });+ });+ test('plain string → text/UTF8', () => {+ expect(classifyWriteContent('hello', false, Encoding)).toEqual({+ mode: 'text',+ data: 'hello',+ encoding: 'utf8',+ });+ });+ test('non-string content → binary (raw and non-raw)', () => {+ const bytes = new Uint8Array([1, 2, 3]);+ expect(classifyWriteContent(bytes, false, Encoding)).toEqual({+ mode: 'binary',+ });+ expect(classifyWriteContent(bytes, true, Encoding)).toEqual({+ mode: 'binary',+ });+ });+ });++ // E. normalizePath+ describe('normalizePath', () => {+ test('collapses runs of slashes', () => {+ expect(normalizePath('/a//b///c')).toBe('/a/b/c');+ });+ test('passes through falsy input', () => {+ expect(normalizePath('')).toBe('');+ expect(normalizePath(undefined)).toBe(undefined);+ });+ });++ // F. getDevicePathsForPlatform+ describe('getDevicePathsForPlatform', () => {+ test('iOS exposes the Documents root', () => {+ expect(getDevicePathsForPlatform('ios')).toEqual({+ appDocumentsFolder: '/',+ });+ });+ test('Android exposes the shared-storage folders', () => {+ const p = getDevicePathsForPlatform('android');+ expect(p.downloadsFolder).toBe('sdcard/Download/');+ expect(p.dcimFolder).toBe('sdcard/DCIM/');+ });+ });++ // G. The bare-filename contract (root cause of vanishing thumbnails). The+ // renderer matches with `relativePath.endsWith(metaEntry.path)`, so the+ // Capacitor listMetaDirectoryPromise MUST return bare filenames.+ describe('bare-filename contract (listMetaDirectoryPromise)', () => {+ test('thumb path matches a bare filename, never a full /.ts/ path', () => {+ const thumbPath = getThumbFileLocationForFile('/IMG_9017.jpeg', '/', false);+ expect(thumbPath).toBe('.ts/IMG_9017.jpeg.jpg');+ expect(thumbPath.endsWith('IMG_9017.jpeg.jpg')).toBe(true); // the fix+ expect(thumbPath.endsWith('/.ts/IMG_9017.jpeg.jpg')).toBe(false); // the bug+ });+ test('meta sidecar path matches a bare filename, never a full /.ts/ path', () => {+ const metaPath = getMetaFileLocationForFile('/IMG_9017.jpeg', '/');+ expect(metaPath).toBe('.ts/IMG_9017.jpeg.json');+ expect(metaPath.endsWith('IMG_9017.jpeg.json')).toBe(true);+ expect(metaPath.endsWith('/.ts/IMG_9017.jpeg.json')).toBe(false);+ });+ });++ // H. metaDir rebuild round-trip — io-capacitor rebuilds <dir>/.ts/<name> from+ // the bare filename, and that path resolves back to the Documents directory.+ test('metaDir rebuild round-trips through resolveCapacitorPath', () => {+ const rebuilt =+ cleanTrailingDirSeparator('/') + '/' + '.ts' + '/' + 'IMG.jpeg.json';+ expect(rebuilt).toBe('/.ts/IMG.jpeg.json');+ expect(ios(rebuilt)).toEqual({+ path: '.ts/IMG.jpeg.json',+ directory: 'DOCUMENTS',+ });+ });+});