What if read returns fewer bytes than requested?
What if write succeeds partially then fails?
What if output already exists?
What if temp cleanup fails?
What if filenames contain spaces, Unicode, or newline?
What if the filesystem is case-insensitive?
What if archive entries try to escape the target directory?
What if decoding fails halfway through the file?

class FileIngestorTest {
    @TempDir
    Path tempDir;

    @Test
    void ingestsFileIntoStagingThenCommit() throws IOException {
        Path input = tempDir.resolve("input.txt");
        Files.writeString(input, "hello", StandardCharsets.UTF_8);

        Path output = tempDir.resolve("out.txt");
        new FileIngestor().ingest(input, output);

        assertEquals("hello", Files.readString(output, StandardCharsets.UTF_8));
    }
}

@Test
void safeReplaceCreatesFinalFileOnlyAfterCompleteWrite(@TempDir Path dir) throws IOException {
    Path target = dir.resolve("target.dat");
    Path temp = dir.resolve("target.dat.tmp");

    Files.writeString(temp, "complete", StandardCharsets.UTF_8,
        StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE);

    Files.move(temp, target,
        StandardCopyOption.ATOMIC_MOVE,
        StandardCopyOption.REPLACE_EXISTING);

    assertEquals("complete", Files.readString(target, StandardCharsets.UTF_8));
    assertFalse(Files.exists(temp));
}

try (FileSystem fs = Jimfs.newFileSystem(Configuration.unix())) {
    Path root = fs.getPath("/work");
    Files.createDirectory(root);

    Path file = root.resolve("input.txt");
    Files.writeString(file, "hello", StandardCharsets.UTF_8);

    assertEquals("hello", Files.readString(file, StandardCharsets.UTF_8));
}

normal.txt
with space.txt
unicode-東京.txt
semi;colon.txt
quote'file.txt
brackets[1].txt
dots...txt
.hidden
UPPER.txt
upper.txt
nested/a/b/c.txt

static Path resolveInside(Path root, String userName) throws IOException {
    Path resolved = root.resolve(userName).normalize();
    if (!resolved.startsWith(root)) {
        throw new IOException("path escapes root: " + userName);
    }
    return resolved;
}

@Test
void rejectsParentTraversal(@TempDir Path root) {
    assertThrows(IOException.class, () -> resolveInside(root, "../escape.txt"));
}

Path realRoot = root.toRealPath(LinkOption.NOFOLLOW_LINKS);
Path realCandidateParent = candidate.getParent().toRealPath(LinkOption.NOFOLLOW_LINKS);

src/test/resources/golden/invoice-report/
  input.json
  expected.txt
  README.md

String expected = Files.readString(expectedPath, StandardCharsets.UTF_8)
    .replace("\r\n", "\n");
String actual = report.replace("\r\n", "\n");
assertEquals(expected, actual);

byte[] expected = Files.readAllBytes(expectedPath);
byte[] actual = encoder.encode(value);
assertArrayEquals(expected, actual);

first differing offset
expected byte
actual byte
nearby hex window
length difference

final class OneByteAtATimeInputStream extends FilterInputStream {
    OneByteAtATimeInputStream(InputStream delegate) {
        super(delegate);
    }

    @Override
    public int read(byte[] b, int off, int len) throws IOException {
        return super.read(b, off, Math.min(len, 1));
    }
}

@Test
void parserHandlesPartialReads() throws IOException {
    byte[] frame = makeFrame("hello".getBytes(StandardCharsets.UTF_8));

    try (InputStream in = new OneByteAtATimeInputStream(new ByteArrayInputStream(frame))) {
        assertEquals("hello", parser.readFrame(in));
    }
}

final class FailingInputStream extends FilterInputStream {
    private final long failAfter;
    private long read;

    FailingInputStream(InputStream delegate, long failAfter) {
        super(delegate);
        this.failAfter = failAfter;
    }

    @Override
    public int read(byte[] b, int off, int len) throws IOException {
        if (read >= failAfter) {
            throw new IOException("injected read failure after " + failAfter + " bytes");
        }
        int allowed = (int) Math.min(len, failAfter - read);
        int n = super.read(b, off, allowed);
        if (n > 0) {
            read += n;
        }
        return n;
    }
}

final class FailingOutputStream extends FilterOutputStream {
    private final long failAfter;
    private long written;

    FailingOutputStream(OutputStream delegate, long failAfter) {
        super(delegate);
        this.failAfter = failAfter;
    }

    @Override
    public void write(byte[] b, int off, int len) throws IOException {
        if (written >= failAfter) {
            throw new IOException("injected write failure after " + failAfter + " bytes");
        }
        int allowed = (int) Math.min(len, failAfter - written);
        out.write(b, off, allowed);
        written += allowed;
        if (allowed < len) {
            throw new IOException("injected partial write failure");
        }
    }

    @Override
    public void write(int b) throws IOException {
        if (written >= failAfter) {
            throw new IOException("injected write failure after " + failAfter + " bytes");
        }
        out.write(b);
        written++;
    }
}

final class PartialWritableByteChannel implements WritableByteChannel {
    private final WritableByteChannel delegate;
    private final int maxBytesPerWrite;
    private boolean open = true;

    PartialWritableByteChannel(WritableByteChannel delegate, int maxBytesPerWrite) {
        this.delegate = delegate;
        this.maxBytesPerWrite = maxBytesPerWrite;
    }

    @Override
    public int write(ByteBuffer src) throws IOException {
        int originalLimit = src.limit();
        int allowed = Math.min(src.remaining(), maxBytesPerWrite);
        src.limit(src.position() + allowed);
        try {
            return delegate.write(src);
        } finally {
            src.limit(originalLimit);
        }
    }

    @Override
    public boolean isOpen() {
        return open && delegate.isOpen();
    }

    @Override
    public void close() throws IOException {
        open = false;
        delegate.close();
    }
}

while (buffer.hasRemaining()) {
    channel.write(buffer);
}

@Test
void strictUtf8RejectsMalformedInput() {
    byte[] malformed = {(byte) 0xC3, (byte) 0x28};

    CharsetDecoder decoder = StandardCharsets.UTF_8.newDecoder()
        .onMalformedInput(CodingErrorAction.REPORT)
        .onUnmappableCharacter(CodingErrorAction.REPORT);

    assertThrows(CharacterCodingException.class, () -> decoder.decode(ByteBuffer.wrap(malformed)));
}

last line without newline
blank lines
comment lines
spaces around delimiter
quoted delimiter
escaped delimiter

[magic:4][version:1][length:4][payload:n][crc:4]

@Test
void rejectsHugeLengthBeforeAllocation() {
    byte[] header = ByteBuffer.allocate(9)
        .putInt(0xCAFE_BABE)
        .put((byte) 1)
        .putInt(Integer.MAX_VALUE)
        .array();

    assertThrows(FrameTooLargeException.class, () -> parser.read(new ByteArrayInputStream(header)));
}

@Test
void deletesStagingFileWhenWriteFails(@TempDir Path dir) throws IOException {
    Path target = dir.resolve("target.dat");
    Path staging = dir.resolve("target.dat.tmp");

    IOException ex = assertThrows(IOException.class, () ->
        writer.writeAtomically(
            new ByteArrayInputStream(new byte[10_000]),
            target,
            new FailingOutputStreamFactory(100)
        )
    );

    assertFalse(Files.exists(target), "target must not be committed");
    assertFalse(Files.exists(staging), "staging should be cleaned or moved to quarantine");
    assertNotNull(ex.getCause());
}

quarantine contains failed partial file
manifest records failure cause
target remains absent

final class CloseTrackingInputStream extends FilterInputStream {
    private boolean closed;

    CloseTrackingInputStream(InputStream delegate) {
        super(delegate);
    }

    @Override
    public void close() throws IOException {
        closed = true;
        super.close();
    }

    boolean closed() {
        return closed;
    }
}

@Test
void processorDoesNotCloseCallerOwnedStream() throws IOException {
    CloseTrackingInputStream in = new CloseTrackingInputStream(
        new ByteArrayInputStream("abc".getBytes(StandardCharsets.UTF_8))
    );

    processor.process(in);

    assertFalse(in.closed(), "caller-owned stream should remain open");
}

@Test
void processorClosesOwnedStreamSupplier() throws IOException {
    CloseTrackingInputStream in = new CloseTrackingInputStream(new ByteArrayInputStream(new byte[0]));

    processor.processOwned(() -> in);

    assertTrue(in.closed());
}

try (Stream<String> lines = Files.lines(path, StandardCharsets.UTF_8)) {
    assertEquals(List.of("a", "b"), lines.toList());
}

public <T> T withLines(Path path, Function<Stream<String>, T> fn) throws IOException {
    try (Stream<String> lines = Files.lines(path, StandardCharsets.UTF_8)) {
        return fn.apply(lines);
    }
}

@Test
void withLinesClosesResource(@TempDir Path dir) throws IOException {
    Path file = dir.resolve("a.txt");
    Files.writeString(file, "x\ny\n", StandardCharsets.UTF_8);

    List<String> result = reader.withLines(file, Stream::toList);

    assertEquals(List.of("x", "y"), result);
}

@Test
void rejectsZipSlipEntry(@TempDir Path dir) throws IOException {
    Path zip = dir.resolve("evil.zip");
    createZip(zip, Map.of("../escape.txt", "owned"));

    Path target = dir.resolve("out");
    Files.createDirectory(target);

    assertThrows(IOException.class, () -> extractor.extract(zip, target));
    assertFalse(Files.exists(dir.resolve("escape.txt")));
}

public final class SpamStderr {
    public static void main(String[] args) throws Exception {
        byte[] block = new byte[8192];
        Arrays.fill(block, (byte) 'x');
        for (int i = 0; i < 10_000; i++) {
            System.err.write(block);
        }
    }
}

write temp
fsync temp
move temp to target
fsync parent

enum FailPoint {
    BEFORE_TEMP_WRITE,
    AFTER_TEMP_WRITE,
    AFTER_TEMP_FORCE,
    AFTER_ATOMIC_MOVE,
    AFTER_PARENT_FORCE
}

after any injected failure, target is either old complete content or new complete content, never partial mixed content

for (FailPoint fp : FailPoint.values()) {
    Path dir = Files.createTempDirectory("atomic-test-");
    try {
        Files.writeString(dir.resolve("target"), "old", StandardCharsets.UTF_8);

        assertThrows(IOException.class, () -> writer.replace(dir.resolve("target"), "new", fp));

        String content = Files.readString(dir.resolve("target"), StandardCharsets.UTF_8);
        assertTrue(content.equals("old") || content.equals("new"));
    } finally {
        deleteRecursively(dir);
    }
}

.
├── committed/
│   └── file-a.txt = "hello"
├── staging/
└── manifest.json

static Map<String, String> readTextTree(Path root) throws IOException {
    try (Stream<Path> paths = Files.walk(root)) {
        return paths
            .filter(Files::isRegularFile)
            .collect(Collectors.toMap(
                p -> root.relativize(p).toString().replace(File.separatorChar, '/'),
                p -> {
                    try {
                        return Files.readString(p, StandardCharsets.UTF_8);
                    } catch (IOException e) {
                        throw new UncheckedIOException(e);
                    }
                },
                (a, b) -> { throw new IllegalStateException("duplicate"); },
                TreeMap::new
            ));
    }
}

assertEquals(Map.of(
    "committed/file-a.txt", "hello",
    "manifest.json", "{\"status\":\"COMMITTED\"}\n"
), readTextTree(root));

assertTrue(Files.list(dir).findFirst().isPresent());

try (Stream<Path> children = Files.list(dir)) {
    List<String> names = children
        .map(p -> p.getFileName().toString())
        .sorted()
        .toList();

    assertEquals(List.of("manifest.json", "payload.bin"), names);
}

void importFromDefaultLocation() throws IOException {
    Path input = Path.of(System.getProperty("user.home"), "data.csv");
    // parse, validate, write, log, move
}

ImportResult importFrom(Path input, Path workDir, Path outputDir) throws IOException

List<Record> parse(InputStream input) throws IOException

parse(InputStream) -> pure/fault-injection tests
importFrom(Path...) -> temp filesystem tests
scheduled import job -> integration tests

open file
create temp dir
start process
locate resource

parse bytes
validate frame
transform records
write encoded output

@RepeatedTest(100)
void noHandleLeakAcrossRepeatedImport(@TempDir Path dir) throws IOException {
    Path input = dir.resolve("input.txt");
    Files.writeString(input, "hello", StandardCharsets.UTF_8);

    importer.importFile(input, dir.resolve("out.txt"));

    Files.deleteIfExists(dir.resolve("out.txt"));
}

decode(encode(payload)) == payload

@Test
void frameRoundTripForRandomPayloads() throws IOException {
    Random random = new Random(1234);

    for (int i = 0; i < 1000; i++) {
        byte[] payload = new byte[random.nextInt(4096)];
        random.nextBytes(payload);

        byte[] encoded = frameCodec.encode(payload);
        byte[] decoded = frameCodec.decode(new ByteArrayInputStream(encoded));

        assertArrayEquals(payload, decoded);
    }
}

final class RepeatingInputStream extends InputStream {
    private long remaining;
    private final byte value;

    RepeatingInputStream(long size, byte value) {
        this.remaining = size;
        this.value = value;
    }

    @Override
    public int read() {
        if (remaining <= 0) {
            return -1;
        }
        remaining--;
        return value & 0xFF;
    }
}

unit tests:
  parser
  encoder
  stream fault injection
  path normalization

contract tests:
  real filesystem operations
  symlink/permission behavior when supported
  atomic move behavior

integration tests:
  external process tools
  actual archive fixtures
  container-mounted volumes
  OS-specific behavior

@Tag("filesystem-contract")
@Tag("external-tool")
@Tag("windows-specific")

Assumptions.assumeTrue(FileSystems.getDefault().supportedFileAttributeViews().contains("posix"));

normal.zip
zip-slip.zip
duplicate-entry.zip
many-entries.zip
huge-entry.zip
nested.zip

[ ] Test uses isolated temp directory or explicit fake filesystem.
[ ] Test does not depend on project working directory.
[ ] Charset is explicit.
[ ] File listing assertions are sorted/deterministic.
[ ] Text comparison handles line endings intentionally.
[ ] Parser tests include partial input and malformed input.
[ ] Writer tests include partial/failing output.
[ ] Large-data tests do not require huge committed fixtures.
[ ] Resource ownership is tested where API contract matters.
[ ] Cleanup or quarantine behavior is asserted.
[ ] Archive/path tests include traversal attempts.
[ ] Process tests drain stdout/stderr and enforce timeout.
[ ] Platform-specific semantics are tagged or guarded by assumptions.
[ ] Golden files are small, named, and documented.
[ ] Failure messages include enough diagnostic context.

small deterministic fixtures
+ explicit temp workspaces
+ partial read/write injection
+ malformed input corpus
+ cleanup assertions
+ real provider contract tests where necessary