Testing with POSIX tools

Once your provider is mounted, the filesystem is the test harness. Every syscall the kernel routes through FUSE exercises the three WIT operations directly: lookup-child, list-children, and read-file. A correct provider passes all of the checks below without any omnifs-specific tooling.

The examples below assume the mount is at /omnifs. Substitute your actual mount point.

Verify list-children with ls

ls on a directory calls list-children. The response is a flat list of child names; the host assembles the directory entries. A correct provider returns exactly the children that exist for that path.

# Check the top-level of a repo
ls /omnifs/github/ollama/ollama
# Expected: _actions  _issues  _prs  _repo

# Check open issues exist
ls /omnifs/github/ollama/ollama/_issues/_open
# Expected: one entry per open issue number

# List running containers
ls /omnifs/docker/containers/_running
# Expected: container names with no duplicates

# List Linear issues for a team
ls /omnifs/linear/teams/ENG/issues/_open
# Expected: ENG-NNNN identifiers

# List DNS record types for a domain
ls /omnifs/dns/example.com
# Expected: A  AAAA  MX  NS  TXT  CNAME  SOA  _all  _raw

What to check: the count matches the upstream source, names contain no path separators, and no entry appears twice. If ls hangs, lookup-child on the parent path is blocking. If it returns nothing, list-children returned an empty slice when it should not have.

Verify read-file with cat

cat on a leaf calls read-file. The host streams the byte slice back verbatim. A correct provider returns the raw content with no extra framing.

# Read an issue title: should be a single line, no trailing newline ambiguity
cat /omnifs/github/ollama/ollama/_issues/_open/12345/title
# Expected: the exact title string from GitHub

# Read a container state: one word
cat /omnifs/docker/containers/by-name/postgres/state
# Expected: running

# Read a Linear issue priority: one word or number
cat /omnifs/linear/teams/ENG/issues/_open/ENG-1421/priority
# Expected: 1  (or: urgent, high, medium, no priority)

# Read a DNS MX record
cat /omnifs/dns/example.com/MX
# Expected: 10 mail.example.com.\n20 mail2.example.com.

# Read arXiv paper metadata
cat /omnifs/arxiv/papers/1706.03762/metadata.json | jq .title
# Expected: "Attention Is All You Need"

What to check: the content matches the upstream value at the time of the call, the file is not empty when the upstream object exists, and cat on a leaf does not recurse into directories. If cat returns a directory listing, your provider is returning children from read-file instead of bytes.

Verify composition with find and rg

Once ls and cat work, standard tools that compose them also work. This checks that your provider’s path graph is traversable and that file contents are grep-able.

# Walk every open issue under a repo and print its state file
find /omnifs/github/ollama/ollama/_issues/_open -name state -exec cat {} \;

# Find all containers whose inspect.json mentions a specific image
find /omnifs/docker/containers/_running -name inspect.json \
  | xargs grep '"Image": "nginx"'

# Ripgrep across all open Linear issues for a keyword
rg "authentication" /omnifs/linear/teams/ENG/issues/_open

# List every DNS record type available for several domains at once
find /omnifs/dns -maxdepth 1 -type d | xargs -I{} ls {}

find exercises recursive lookup-child and list-children calls. rg exercises read-file on every leaf it encounters. If either hangs mid-traversal, a specific path segment is not returning from one of the three ops; run ls on that segment in isolation to narrow it down.

Verify bulk traversal with tar and rsync

Bulk traversal tools call list-children and read-file on every reachable node. They expose off-by-one errors in child enumeration and incomplete reads.

# Archive a provider subtree to verify complete traversal
tar c /omnifs/github/ollama/ollama/_issues/_open > /tmp/issues.tar
tar t /tmp/issues.tar   # every leaf should appear exactly once

# Dry-run rsync to count transferred files
rsync -n -r /omnifs/docker/containers/_running/ /tmp/containers-snapshot/

Verify stable identity with stat

The host assigns each path a stable inode. Inode numbers must not change between mounts or across upstream renames, because tools like rsync and cp -a use inodes to detect identity.

# Record the inode for a path
stat -f "%i %N" /omnifs/github/ollama/ollama/_issues/_open/12345/title

# Unmount, remount, then stat again
# The inode number must be the same value
stat -f "%i %N" /omnifs/github/ollama/ollama/_issues/_open/12345/title

If the inode changes between mounts, the host cannot derive a stable key from the path segments your provider returns. Verify that your lookup-child responses use deterministic, content-addressed identifiers rather than opaque session tokens.

Check error cases

A correct provider signals absence through its return type, not through a panic or a byte-level error message in the file content.

# A path that does not exist should produce a normal ENOENT
cat /omnifs/github/ollama/ollama/_issues/_open/999999999/title
# Expected: cat: /omnifs/.../title: No such file or directory

# A leaf read should not return bytes that look like an error object
cat /omnifs/docker/containers/by-name/no-such-container/state
# Expected: ENOENT, not {"error":"container not found"}

If your provider embeds error strings in file content, downstream tools (grep, jq, scripts) will silently treat the error as data. Return an empty option from read-file to let the host map it to ENOENT.

The contract in one command

ls /omnifs/github/yourname/yourrepo \
  && cat /omnifs/github/yourname/yourrepo/_issues/_open/1/title \
  && echo "list-children and read-file: ok"

If both calls succeed and the output matches the upstream source, the provider satisfies the contract. There is no additional test runner to install.