mergerfs/tests

POSIX Soft Conformance Suite

This directory contains integration tests that exercise mergerfs FUSE operations and compare behavior against equivalent native syscalls on a local filesystem.

The suite is "soft POSIX": it focuses on practical parity for return values, errno, and key side effects, including common error paths.

Each test mounts its own ephemeral mergerfs instance with random temporary branches and cleans everything up automatically.

Run with:

python3 tests/run-tests

Coverage Matrix

• access -> TEST_posix_access
• chmod / fchmod -> TEST_posix_chmod, TEST_use_fchmod_after_unlink
• chown / fchown -> TEST_posix_chown, TEST_use_fchown_after_unlink
• create / mknod -> TEST_posix_create_mknod
• getattr / fgetattr -> TEST_posix_getattr_fgetattr, TEST_use_fstat_after_unlink
• open / read / write -> TEST_posix_open_read_write, TEST_o_direct
• flush / release / fsync / fsyncdir -> TEST_posix_fsync_flush
• release close semantics -> TEST_posix_release
• releasedir close semantics -> TEST_posix_releasedir
• truncate / ftruncate -> TEST_posix_truncate_ftruncate, TEST_use_ftruncate_after_unlink
• utimens / futimens -> TEST_posix_utimens, TEST_use_futimens_after_unlink
• fallocate -> TEST_use_fallocate_after_unlink
• copy_file_range -> TEST_posix_copy_file_range
• ioctl -> TEST_posix_ioctl
• poll -> TEST_posix_poll
• tmpfile (O_TMPFILE) -> TEST_posix_tmpfile
• bmap (via FIBMAP ioctl parity) -> TEST_posix_bmap
• readlink -> TEST_readlink_semantics
• link / symlink -> TEST_posix_link_symlink
• mkdir / rmdir -> TEST_posix_mkdir_rmdir
• unlink / rename -> TEST_posix_unlink_rename, TEST_unlink_rename
• statfs -> TEST_posix_statfs
• statx -> TEST_posix_statx
• syncfs -> TEST_posix_syncfs
• flock / lock -> TEST_posix_locking
• setxattr / getxattr / listxattr / removexattr -> TEST_posix_xattr
• xattr object/flag matrix (file, dir, symlink l*, create/replace) -> TEST_posix_xattr_matrix
• xattr mode runtime toggles (passthrough/noattr/nosys) -> TEST_cfg_xattr_modes
• statfs mode and statfs-ignore runtime toggles -> TEST_cfg_statfs_ignore
• EXDEV fallback runtime toggles for link/rename -> TEST_cfg_link_rename_exdev
• readdir (+ seek/tell behavior) -> TEST_posix_readdir
• readdir_plus semantic parity (list+stat and readdir policy toggles) -> TEST_posix_readdir_plus
• lifecycle (init/destroy) harness check -> TEST_mount_lifecycle
• hidden temp exposure checks -> TEST_no_fuse_hidden

Error Conditions Emphasized

Across tests, parity checks include combinations of:

• ENOENT
• ENOTDIR
• EEXIST
• ENOTEMPTY
• EISDIR
• EBADF
• privilege-sensitive outcomes (for example EPERM) where applicable

Notes

• Some behavior is runtime/environment dependent (kernel, mount options, uid/gid, capabilities). Tests compare mergerfs to native behavior in the same runtime to keep assertions robust.
• Tests that cannot exercise a behavior in the current environment may exit 77 and are reported as SKIP by tests/run-tests.
• The xattr test uses a user.* key and assumes user xattrs are enabled.
• Tests mount their own ephemeral mergerfs instances using the mergerfs_mount context manager in posix_parity.py. Random directories are created and cleaned up automatically.