seaweedfs/test/nfs

SeaweedFS NFS Integration Tests

End-to-end tests that boot a real SeaweedFS cluster (master + volume + filer) plus the experimental weed nfs frontend and drive it through the NFSv3 wire protocol. The tests talk to the server over TCP using github.com/willscott/go-nfs-client, which means they do not need a kernel NFS mount, privileged ports, or any platform-specific tooling.

Prerequisites

1. Build the weed binary:

   cd ../../weed
   go build -o weed .
   

2. Go 1.24 or later.

Running the tests

# Build weed and run everything
make test

# Verbose output, keeps the subprocess stdout
make test-verbose

# Skip integration tests — useful when iterating on the framework itself
make test-short

# Run a single test
go test -v -run TestNfsBasicReadWrite ./...

Every test starts its own cluster on random loopback ports, so runs are isolated and can execute in parallel.

Layout

• framework.go — launches weed master, weed volume, weed filer, and weed nfs as subprocesses, waits for each to accept TCP, and exposes a Mount() helper that returns an nfsclient.Target.
• basic_test.go — covers the most common NFS operations:
  • Read/write round-trip (TestNfsBasicReadWrite)
  • Mkdir / ReadDirPlus / RmDir (TestNfsMkdirAndRmdir)
  • Nested directory + leaf file (TestNfsNestedDirectories)
  • Rename preserves content (TestNfsRenamePreservesContent)
  • Overwrite shrinks file size (TestNfsOverwriteShrinksFile)
  • Large binary file round-trip (TestNfsLargeFile)
  • Arbitrary binary and empty files (TestNfsBinaryAndEmptyFiles)
  • Symlink + Readlink (TestNfsSymlinkRoundTrip)
  • ReadDirPlus ordering sanity (TestNfsReadDirPlusOrdering)
  • Remove on missing path errors cleanly (TestNfsRemoveMissingFailsCleanly)
  • FSINFO advertises non-zero limits (TestNfsFSInfoReturnsSaneLimits)
  • Sequential append writes concatenate (TestNfsAppendIsSequential)
  • ReadDir after remove (TestNfsReadDirAfterRemove)

Debugging a failing test

Keep the cluster temp dir for inspection:

config := DefaultTestConfig()
config.SkipCleanup = true

Enable subprocess stdout/stderr:

config := DefaultTestConfig()
config.EnableDebug = true

Or run with -v, which flips EnableDebug automatically via testing.Verbose().

Notes

• The NFS server binds to 127.0.0.1 with -ip.bind=127.0.0.1 and exports /nfs_export. The test framework pre-creates that directory via the filer's HTTP API before starting the NFS server — the NFS server requires its export root to exist in the filer's namespace with a real entry, and the filer's synthetic / root does not match the Name=="/" check the NFS server performs during ensureIndexedEntry.
• Ports are allocated dynamically. Each test run opens a short-lived listener on 127.0.0.1:0, reads back the assigned port, closes the listener, and hands the port to weed master/volume/filer/nfs. There is a tiny race window between close and reopen that has not been a problem in practice but is worth remembering if you see a "bind: address already in use" failure.
• All four weed components are started with explicit -port.grpc=... flags. Without them, the default is -port + 10000, which overflows 65535 whenever the HTTP port lands above 55535 — the kernel's ephemeral port range on macOS routinely does.