fa2json/test/PLAN.md

fa2json Test Plan

Overview

A Node.js test runner (test/test.mjs) that exercises fa2json against a temporary ext4 filesystem on a loop device. The test produces a single pass/fail result and cleans up after itself unconditionally.

Requires root (fanotify FID reporting and mount both need CAP_SYS_ADMIN).

---

Files

File	Purpose
test/test.mjs	Test runner
Makefile	make test target calls sudo node test/test.mjs

---

Setup

1. Create a temporary image file (mktemp /tmp/fa2json-test-XXXXXX.img)
2. truncate -s 10M the image (sparse file, no need for dd)
3. mkfs.ext4 the image
4. Create a temporary mount directory (mktemp -d /tmp/fa2json-mnt-XXXXXX)
5. sudo mount <img> <mntdir> (no losetup needed — mount accepts image files directly)
6. sudo chown $(id -u) <mntdir> to hand ownership to the current user
7. sync to flush before fa2json starts listening
8. sudo spawn fa2json <mountpoint> as a child process (needs CAP_SYS_ADMIN)
9. Attach a readline interface to its stdout; parse each line as JSON and push into an event buffer

Steps 6 and 7 ensure the chown event never enters the fa2json stream, and all subsequent FS operations run unprivileged.

---

Teardown

Runs unconditionally in a finally block:

1. Kill the fa2json child process
2. sudo umount <mountpoint>
3. rm the image file
4. rmdir the mount directory

---

Event Collection and the Marker Pattern

fa2json runs continuously for the entire test. To associate events with specific operations, a marker file is used as a synchronisation barrier:

1. Perform a filesystem operation
2. Immediately touch <mountpoint>/.marker_N (where N is a counter)
3. Wait until the event stream contains a CREATE event for .marker_N
4. Collect all events since the previous marker — this batch belongs to the current operation
5. Assert on the batch, then advance the counter

If a marker event never arrives the test hangs, which indicates a failure at the fa2json level itself.

---

Path Handling

fa2json emits full paths including the mount prefix (e.g. /tmp/fa2json-mnt-XXXXX/dir_a/file.txt). The runner strips this prefix so assertions work against a virtual root:

/tmp/fa2json-mnt-XXXXX/dir_a/file.txt  →  /dir_a/file.txt

---

Fanotify Mask Constants

Relevant flags (bitwise, check with mask & FLAG):

Constant	Value	Meaning
FAN_ATTRIB	0x4	Metadata/attribute change
FAN_CLOSE_WRITE	0x8	File closed after writing
FAN_CREATE	0x100	File or directory created
FAN_DELETE	0x200	File or directory deleted
FAN_RENAME	0x10000000	Rename (has old and new fields)
FAN_ONDIR	0x40000000	Event subject is a directory

---

Operations and Expected Events

Each row is one doOp() call. Events are matched by presence (not exact list) — extra events from ext4 internals are ignored.

Operation	Expected event(s)
mkdir /dir_a	CREATE | ONDIR, name /dir_a
touch /file_a.txt	CREATE, name /file_a.txt
echo "content" >> /file_a.txt	CLOSE_WRITE, name /file_a.txt
mkdir /dir_b	CREATE | ONDIR, name /dir_b
touch /dir_b/nested.txt	CREATE, name /dir_b/nested.txt
mv /file_a.txt /file_b.txt	RENAME, old /file_a.txt, new /file_b.txt
mv /dir_b /dir_a/dir_b_moved	RENAME | ONDIR, old /dir_b, new /dir_a/dir_b_moved
chmod 600 /file_b.txt	ATTRIB, name /file_b.txt
touch -m /file_b.txt	ATTRIB, name /file_b.txt
chmod 755 /dir_a	ATTRIB | ONDIR, name /dir_a
rm /file_b.txt	DELETE, name /file_b.txt
rm /dir_a/dir_b_moved/nested.txt	DELETE, name /dir_a/dir_b_moved/nested.txt
rmdir /dir_a/dir_b_moved	DELETE | ONDIR, name /dir_a/dir_b_moved
rmdir /dir_a	DELETE | ONDIR, name /dir_a

---

Pass / Fail

• All assertions pass → print summary, process.exit(0)
• Any assertion throws → print the failing operation, the expected event, and the actual batch received, then process.exit(1)