File System Access API mock

File System Access API mocks.

Mocked members:
* FileSystemFileHandle class.
* FileSystemDirectoryHandle class.
* FileSystemSyncAccessHandle class.
* FileSystemWritableFileStream class.
* window.showDirectoryPicker() method.
* window.showOpenFilePicker() method.
* window.showSaveFilePicker() method.

Installation

``
npm i -D fsa-mock
`

Usage

Example code to test:
`ts
export async function saveFile(file: Blob) {
const fileHandle = await showSaveFilePicker();
const stream = await fileHandle.createWritable();
await stream.write(file);
await stream.close();
}
`

Example test using vitest:
`ts
import { mock } from "fsa-mock";
import { describe, it, expect, beforeEach, afterEach } from "vitest";
import { saveFile } from "./saveFile.ts";

describe("saveFile() function", () => {
let file: File;

beforeEach(() => {
// You can pass options to install() method
mock.install();
file = new File(["example file contents"], "file.txt");
});

afterEach(() => {
mock.uninstall();
});

it("should save file", async () => {
const path = "path/to/file.txt";
// set file picker callback to return path
// such as it was picked using save file picker
mock.onSaveFilePicker(() => path);

await saveFile(file);

// check if file appeared in file system
expect(mock.fs().isFile(path)).toBe(true);
// ...of shorthand
expect(mock.isFile(path)).toBe(true);
});

it("should reject with AbortError if user aborted file picker", async () => {
// set file picker callback to return undefined to simulate picker abortion
mock.onSaveFilePicker(() => undefined);

try {
await saveFile(file);
expect.fail();
} catch (e) {
expect(e).toBeInstanceOf(DOMException);
expect(e.name).toBe("AbortError");
}
});

it("should reject with NotAllowedError if no 'readwrite' permission was granted", async () => {
// set permissions request callback to return 'denied'
mock.onPromptPermission(() => "denied");

const path = "path/to/file.txt";
mock.onSaveFilePicker(() => path);

try {
await saveFile(file);
expect.fail();
} catch (e) {
expect(e).toBeInstanceOf(DOMException);
expect(e.name).toBe("NotAllowedError");
}
});
});
`

API

$3


Creates new context and replaces original File System Access API implementations to mocked ones.
See BootstrapOptions description in the next section.

$3

Restores original File System Access API implementations.

$3

Checks for path (either file or directory) existence in file system.

$3

Checks for file existence at given path.

$3

Checks for directory existence at given path.

$3

Recursively creates directory at given path. Used to create directory structure
before testing.

$3

Creates file at given path. Parent directories are created recursively.
File is empty and have size of 0 bytes, unless contents was passed.

$3

Returns file contents ArrayBuffer if it exists at given path.

$3

`ts
type PermissionResolvedState = "granted" | "denied";

interface PromptPermissionProvider {
(
mode: FileSystemPermissionMode,
fs: FileSystem,
path: string
): PermissionResolvedState | Promise;
}
`
Sets callback for access permission prompt.
Callback will be called only if current permission state is "prompt" and will be
passed following arguments:
* mode - file system permission mode: "read" or "readwrite"
* fs - file system object
* path - file of directory path for which permission is requested

Callback should return permission state other than "prompt" of Promise that resolves to such state.

$3


`ts
interface DirectoryPickerProvider {
(
fs: FileSystem,
options: DirectoryPickerOptions
): string | undefined | Promise;
}
`
Callback which will be called when showDirectoryPicker() is called.
It should return full directory path to emulate user selection of given directory.
To emulate user dialog abortion, return undefined from callback.
Returned path must exist in file system and be directory (not file) path.
Path shouldn't start with slash or backslash.
All options that were passed to showDirectoryFilePicker() function will be passed to callback via second argument.

$3

`ts
interface OpenFilePickerProvider {
(
fs: FileSystem,
options: OpenFilePickerOptions
): string[] | undefined | Promise;
}
`

Callback which will be called when showOpenFilePicker() is called.
It should return array of full file paths to emulate user selection of given files.
To emulate user dialog abortion, return undefined or empty array from callback.
All selected paths must be existing file (not directory) paths, and have same parent path.
Only first of provided paths will be used, unless 'multiple' option is set to true in showOpenFilePicker() call.
All options passed to showOpenFilePicker() function will be passed to callback via second argument.

$3


`ts
interface SaveFilePickerProvider {
(
fs: FileSystem,
options: SaveFilePickerOptions
): string | undefined | Promise;
}
`
Callback which will be called when showSaveFilePicker() is called.
It should return full file path to emulate user selection of given file.
To emulate user dialog abortion, return undefined from callback.
If returned file path doesn't exist, it will be created.
Returned path shouldn't start with slash or backslash, and must be a file (not directory) path.
All options passed to showSaveFilePicker() function will be passed to callback via second argument.

$3

Sets file system disk size.

$3

Sets permission state for given path and mode.

$3

Returns virtual file system. It is unlikely that you will use this in tests.

$3

Returns permissions manager. It is unlikely that you will use this in tests.

BootstrapOptions

Options that can be passed to the mock.install() method.

$3

Virtual disk size in bytes.
Can be set after installation using: mock.setDiskSize();
Default: Infinity

$3

Implementation of PermissionProvider interface. It is unlikely that you will need to change it.

$3

Initial "read" permission state for new file system entries.
Will be ignored if custom permissionProvider option is set.
Default: "propmt".

$3

Initial "readwrite" permission state for new file system entries.
Will be ignored if custom permissionProvider option is set.
Default: "propmt".

$3

Permission state to which permissions "prompt" state will be resolved, unless custom
PromptPermissionProvider callback (see below) is set.
Will be ignored if custom permissionProvider option is set of if custom PromptPermissionProvider is set.
Default: "granted".

$3

Callback to resolve permission state on prompt.
See details above at mock.onPromptPermission() method description.

$3

`ts
interface EntryNameValidator {
/**
* Returns boolean validation result of file system entry name.
*
* @param name Entry base name (not full path).
* @param isFileName Boolean indicating that name is file name (not directory name).
*/
isValidName(name: string, isFileName: boolean): boolean;
}
`
Default entry names validator forbids ".", "..", "" (empty string) as file and directory
names. It also forbids names that contain known forbidden characters.
If you need more control over names validation, you can set this option to custom
EntryNamesValidator interface implementation.

$3

Regular expression for testing for invalid characters. It is used by default EntryNameValidator
and is ignored if custom EntryNameValidator was set by previous option.
Default regular expressions forbids following characters in file and directory names:
"/", "\", ":", "*", "?", '"' (double quote), "<", ">", "|".

$3

Callback for directory picker. See details above in mock.onDirectoryPicker()
method description.

$3

Callback for open file picker. See details above in mock.onOpenFilePicker()
method description.

$3

Callback for save file picker. See details above in mock.onSaveFilePicker()`
method description.