Update POSIX-Compliance.md

Chris Lu committed 2026-05-02 11:33:27 -07:00
1 parent 1111acee49
commit cdab925459
1 file changed
+21 -29
+21 -29
@@ -1,63 +1,55 @@
# POSIX Compliance for `weed mount`
**`weed mount` passes 100% of the pjdfstest POSIX compliance suite
(236 test files, 8,819 assertions, zero skipped).**
SeaweedFS runs the [pjdfstest](https://github.com/pjd/pjdfstest) POSIX
compliance suite against `weed mount` on every change to `weed/mount/**`,
`weed/filer/**`, or the test harness itself. The job is defined in
[`.github/workflows/pjdfstest.yml`](https://github.com/seaweedfs/seaweedfs/blob/master/.github/workflows/pjdfstest.yml)
and the harness lives under [`test/pjdfstest/`](https://github.com/seaweedfs/seaweedfs/tree/master/test/pjdfstest).
The suite is pinned to the [`sanwan/pjdfstest`](https://github.com/sanwan/pjdfstest)
fork, which adds NAME_MAX-aware variants of the upstream tests.
## How it runs
1. A SeaweedFS e2e image (master + volume + filer + mount) is built and
started via `test/pjdfstest/docker-compose.yml`.
2. `test/pjdfstest/run.sh` mounts the filesystem with `weed mount
-allowOthers=true` and clones pjdfstest pinned to an immutable upstream
commit for reproducibility.
3. `prove -rv` runs every `tests/**/*.t` except the entries listed in
[`known_failures.txt`](https://github.com/seaweedfs/seaweedfs/blob/master/test/pjdfstest/known_failures.txt).
Any failure outside that allow-list fails CI.
-allowOthers=true` and clones pjdfstest pinned to an immutable commit
for reproducibility.
3. `prove -rv` runs every `tests/**/*.t`. Any failure that is not listed
in [`known_failures.txt`](https://github.com/seaweedfs/seaweedfs/blob/master/test/pjdfstest/known_failures.txt)
fails CI.
## Tests passing
## Status
All pjdfstest syscall groups pass on `weed mount`, except for the three
test files called out below. The groups exercised by the suite are:
**100% passing.** All 236 pjdfstest test files (8,819 individual
assertions) pass on `weed mount`, with zero tests skipped. The
`known_failures.txt` allow-list is empty, so any regression in any test
fails CI immediately.
The syscall groups exercised by the suite are:
| Group | Coverage |
|-------|----------|
| `tests/chflags/` | BSD file flags (skipped on Linux by the suite itself) |
| `tests/chmod/` | `chmod(2)` permission, errno, and setuid/setgid behavior |
| `tests/chown/` | `chown(2)` ownership, errno, and clearing of set\*id bits |
| `tests/link/` | `link(2)` creation, permission, and errno cases (except `00.t`) |
| `tests/link/` | `link(2)` creation, permission, and errno cases |
| `tests/mkdir/` | `mkdir(2)` creation and errno paths |
| `tests/mkfifo/` | `mkfifo(2)` FIFO creation |
| `tests/mknod/` | `mknod(2)` regular/FIFO node creation |
| `tests/open/` | `open(2)` flags, permissions, `O_CREAT`, `O_TRUNC`, errno |
| `tests/rename/` | `rename(2)` same/cross-directory, errno cases (except `21.t`) |
| `tests/rename/` | `rename(2)` same/cross-directory, errno cases |
| `tests/rmdir/` | `rmdir(2)` empty-directory and errno cases |
| `tests/symlink/` | `symlink(2)` creation, traversal, errno cases |
| `tests/truncate/` | `truncate(2)` resize, permission, and errno cases |
| `tests/unlink/` | `unlink(2)` removal and errno cases (except `00.t`) |
| `tests/unlink/` | `unlink(2)` removal and errno cases |
| `tests/utimensat/` | `utimensat(2)` atime/mtime/ctime semantics, errno paths |
| `tests/granular/` | Granular timestamp update checks |
## Tests not passing
The following tests are listed in
[`test/pjdfstest/known_failures.txt`](https://github.com/seaweedfs/seaweedfs/blob/master/test/pjdfstest/known_failures.txt)
and are skipped in CI. They are deterministic and tracked as known issues:
| Test | Category | Reason |
|------|----------|--------|
| `tests/rename/21.t` | rename | Cross-directory rename of a subdirectory with restricted permissions triggers cascading failures in the rest of the test file. |
| `tests/link/00.t` | link | `nlink` assertion mismatch (e.g. expected `nlink=2`, got `nlink=3`) after hard link creation. Filer-side hard-link counter issue. |
| `tests/unlink/00.t` | unlink | Same filer-side hard-link counter issue surfaced on the removal path. |
The two `nlink` failures are filer-side hard-link counter bugs rather than
FUSE mount bugs, and are deterministic under the current meta-cache load
ordering. The rename failure is a permission edge case on cross-directory
rename. Contributions that fix any of these are welcome — once a test is
green, remove it from `known_failures.txt` so CI enforces it going forward.
## Running locally
```sh