// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! Tests for `Uri.fromPath` and `Uri.toPath`, the `file:` URI conversions. const std = @import("std"); const uri = @import("root.zig"); const Uri = uri.Uri; const expectEqual = std.testing.expectEqual; const expectEqualStrings = std.testing.expectEqualStrings; const expectError = std.testing.expectError; const Case = struct { path: []const u8, /// The URI that path names, as text. text: []const u8, /// What `toPath` gives back. Null when that is the path itself, which is /// every POSIX case and every Windows path already in canonical form. back: ?[]const u8 = null, }; // -- POSIX ----------------------------------------------------------------- const posix_cases = [_]Case{ .{ .path = "/", .text = "file:///" }, .{ .path = "/a", .text = "file:///a" }, .{ .path = "/a/b", .text = "file:///a/b" }, // A trailing separator is a trailing empty segment, which is what makes // the URI name a directory. .{ .path = "/a/b/", .text = "file:///a/b/" }, .{ .path = "/etc/hosts", .text = "file:///etc/hosts" }, // Escaping is the formatter's job: the segments hold the bytes as given. .{ .path = "/home/jeff/a b.txt", .text = "file:///home/jeff/a%20b.txt" }, .{ .path = "/a#b", .text = "file:///a%23b" }, .{ .path = "/a?b", .text = "file:///a%3Fb" }, .{ .path = "/a%b", .text = "file:///a%25b" }, // A backslash is an ordinary character in a POSIX filename, so it stays // inside the one segment it was written in. .{ .path = "/a\\b", .text = "file:///a%5Cb" }, // Bytes are bytes: a path is not required to be UTF-8, and nothing here // interprets it as text. .{ .path = "/\xc3\xa9", .text = "file:///%C3%A9" }, .{ .path = "/\xff", .text = "file:///%FF" }, // Dot segments are part of the path as written. Resolution removes them, // but a path that has them names them, and `fromPath` is not resolution. .{ .path = "/a/../b", .text = "file:///a/../b" }, .{ .path = "/a/./b", .text = "file:///a/./b" }, // An empty segment survives too, since `/a//b` and `/a/b` are the same // file only by convention. .{ .path = "/a//b", .text = "file:///a//b" }, // POSIX leaves a path beginning with exactly two slashes // implementation-defined, so it is preserved rather than folded: the // empty authority takes two slashes and the path keeps its own. .{ .path = "//foo", .text = "file:////foo" }, }; test "POSIX paths convert to file URIs and back" { const alloc = std.testing.allocator; for (posix_cases) |case| { const u = try Uri.fromPath(alloc, case.path, .{ .platform = .posix }); defer u.deinit(); const text = try u.toText(alloc, .{}); defer alloc.free(text); try expectEqualStrings(case.text, text); const back = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(back); try expectEqualStrings(case.back orelse case.path, back); } } test "a file URI built from a POSIX path re-parses to the same components" { const alloc = std.testing.allocator; for (posix_cases) |case| { const u = try Uri.fromPath(alloc, case.path, .{ .platform = .posix }); defer u.deinit(); const text = try u.toText(alloc, .{}); defer alloc.free(text); const reparsed = try Uri.parse(alloc, text); defer reparsed.deinit(); try std.testing.expect(u.eql(reparsed)); } } // -- Windows --------------------------------------------------------------- const windows_cases = [_]Case{ // A drive letter is the first path segment, which is what puts the colon // after the three slashes. .{ .path = "C:\\", .text = "file:///C:/" }, .{ .path = "C:\\a", .text = "file:///C:/a" }, .{ .path = "C:\\a\\b", .text = "file:///C:/a/b" }, .{ .path = "C:\\Users\\me\\a b.txt", .text = "file:///C:/Users/me/a%20b.txt" }, // The case of the drive letter is the caller's, not ours. .{ .path = "c:\\a", .text = "file:///c:/a" }, // Forward slashes are accepted on input; backslashes are always written. .{ .path = "C:/a/b", .text = "file:///C:/a/b", .back = "C:\\a\\b" }, // UNC: the server is the URI's host, and the share is just the first // segment of the path. .{ .path = "\\\\server\\share\\x", .text = "file://server/share/x" }, .{ .path = "\\\\server\\share", .text = "file://server/share" }, .{ .path = "\\\\server\\", .text = "file://server/" }, .{ .path = "\\\\server", .text = "file://server/", .back = "\\\\server\\" }, // A server name that is a dotted quad is an address literal, the same as // it would be coming from the parser. .{ .path = "\\\\192.0.2.1\\share", .text = "file://192.0.2.1/share" }, // Rooted on the current drive: not fully qualified, but exactly what // `file:///a/b` reads back as. .{ .path = "\\a\\b", .text = "file:///a/b" }, .{ .path = "\\", .text = "file:///" }, }; test "Windows paths convert to file URIs and back" { const alloc = std.testing.allocator; for (windows_cases) |case| { const u = try Uri.fromPath(alloc, case.path, .{ .platform = .windows }); defer u.deinit(); const text = try u.toText(alloc, .{}); defer alloc.free(text); try expectEqualStrings(case.text, text); const back = try u.toPath(alloc, .{ .platform = .windows }); defer alloc.free(back); try expectEqualStrings(case.back orelse case.path, back); } } test "a file URI built from a Windows path re-parses to the same components" { const alloc = std.testing.allocator; for (windows_cases) |case| { const u = try Uri.fromPath(alloc, case.path, .{ .platform = .windows }); defer u.deinit(); const text = try u.toText(alloc, .{}); defer alloc.free(text); const reparsed = try Uri.parse(alloc, text); defer reparsed.deinit(); try std.testing.expect(u.eql(reparsed)); } } test "the Windows drive forms a URI can carry" { const alloc = std.testing.allocator; const cases = [_]struct { text: []const u8, path: []const u8 }{ .{ .text = "file:///C:/a", .path = "C:\\a" }, // RFC 8089 Appendix E.2: older software wrote the drive with a // vertical bar, and it still turns up. .{ .text = "file:///C|/a", .path = "C:\\a" }, .{ .text = "file:///C%7C/a", .path = "C:\\a" }, // `C:` on its own would be the current directory *on* that drive, // which is not what a URI naming the drive means, so the root // separator is written either way. .{ .text = "file:///C:", .path = "C:\\" }, .{ .text = "file:///C:/", .path = "C:\\" }, // Only the first segment is a drive; anywhere else a colon is just a // character, as in an alternate data stream. .{ .text = "file:///C:/a/D:/b", .path = "C:\\a\\D:\\b" }, .{ .text = "file:///a/b", .path = "\\a\\b" }, .{ .text = "file:///", .path = "\\" }, }; for (cases) |case| { const u = try Uri.parse(alloc, case.text); defer u.deinit(); const path = try u.toPath(alloc, .{ .platform = .windows }); defer alloc.free(path); try expectEqualStrings(case.path, path); } } // -- the forms of a local file URI ---------------------------------------- test "an empty host and localhost both mean this machine" { const alloc = std.testing.allocator; // RFC 8089 §2. The last of these is the minimal form, with no authority // at all -- legal, never produced here, and the same file. for ([_][]const u8{ "file:///a/b", "file://localhost/a/b", "file://LocalHost/a/b", "file:/a/b", }) |text| { const u = try Uri.parse(alloc, text); defer u.deinit(); const path = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(path); try expectEqualStrings("/a/b", path); } } test "a query or fragment names nothing on a filesystem and is ignored" { const alloc = std.testing.allocator; for ([_][]const u8{ "file:///a/b?q=1", "file:///a/b#top", "file:///a/b?q=1#top" }) |text| { const u = try Uri.parse(alloc, text); defer u.deinit(); const path = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(path); try expectEqualStrings("/a/b", path); } } test "a percent-encoded path comes back decoded" { const alloc = std.testing.allocator; const u = try Uri.parse(alloc, "file:///home/jeff/a%20b%23c.txt"); defer u.deinit(); const path = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(path); try expectEqualStrings("/home/jeff/a b#c.txt", path); } // -- what has no conversion ------------------------------------------------ test "a path with no file URI is rejected rather than mangled" { const alloc = std.testing.allocator; const cases = [_]struct { path: []const u8, platform: uri.file.Platform, err: anyerror, }{ // Resolving a relative path needs the working directory, which is I/O. .{ .path = "a/b", .platform = .posix, .err = error.PathNotAbsolute }, .{ .path = ".", .platform = .posix, .err = error.PathNotAbsolute }, .{ .path = "", .platform = .posix, .err = error.PathNotAbsolute }, .{ .path = "a\\b", .platform = .windows, .err = error.PathNotAbsolute }, // Relative to a drive's current directory, which is no more absolute // than a bare relative path. .{ .path = "C:a", .platform = .windows, .err = error.PathNotAbsolute }, .{ .path = "C:", .platform = .windows, .err = error.PathNotAbsolute }, // A NUL ends the path for every system call that takes one, so a URI // carrying one would name a different file than it appears to. .{ .path = "/a\x00b", .platform = .posix, .err = error.InvalidPath }, // The Win32 device namespace is not a share, and has no `file:` form. .{ .path = "\\\\?\\C:\\x", .platform = .windows, .err = error.InvalidPath }, .{ .path = "\\\\.\\PhysicalDrive0", .platform = .windows, .err = error.InvalidPath }, // A UNC path with no server names nothing. .{ .path = "\\\\\\share", .platform = .windows, .err = error.InvalidPath }, // `\\C:` would be written `file:///C:`, which everything reading it // back takes for the drive. A colon cannot appear in a Windows // filename anyway, so the ambiguity is refused rather than written. .{ .path = "\\C:", .platform = .windows, .err = error.InvalidPath }, .{ .path = "\\C:\\a", .platform = .windows, .err = error.InvalidPath }, }; for (cases) |case| { try expectError(case.err, Uri.fromPath(alloc, case.path, .{ .platform = case.platform })); } } test "a URI with no path is rejected rather than mangled" { const alloc = std.testing.allocator; const cases = [_]struct { text: []const u8, platform: uri.file.Platform = .posix, err: anyerror, }{ .{ .text = "http://x/a", .err = error.NotFileScheme }, .{ .text = "/a/b", .err = error.NotFileScheme }, .{ .text = "file:a/b", .err = error.PathNotAbsolute }, .{ .text = "file://", .err = error.PathNotAbsolute }, // POSIX has no way to name a file on another machine. .{ .text = "file://server/share/x", .err = error.NonLocalHost }, // Windows does -- but not one addressed by an IPv6 literal, which it // spells as a name under `ipv6-literal.net` instead. .{ .text = "file://[::1]/share", .platform = .windows, .err = error.NonLocalHost }, // One segment holding a separator is one file; writing it out would // name two. .{ .text = "file:///a%2Fb", .err = error.InvalidPath }, .{ .text = "file:///a%5Cb", .platform = .windows, .err = error.InvalidPath }, .{ .text = "file:///a%00b", .err = error.InvalidPath }, // A Windows path opening with two separators is a UNC prefix, which // an empty authority says this is not. .{ .text = "file:////a", .platform = .windows, .err = error.InvalidPath }, .{ .text = "file:////", .platform = .windows, .err = error.InvalidPath }, // And `\\.\` and `\\?\` are the device namespace rather than a // server, so those two hosts have no UNC path either. .{ .text = "file://./share", .platform = .windows, .err = error.InvalidPath }, .{ .text = "file://%3F/share", .platform = .windows, .err = error.InvalidPath }, }; for (cases) |case| { const u = try Uri.parse(alloc, case.text); defer u.deinit(); try expectError(case.err, u.toPath(alloc, .{ .platform = case.platform })); } } test "a backslash is a filename on POSIX and a separator on Windows" { const alloc = std.testing.allocator; // The same URI, read as each platform's path: one file called `a\b`, or // two path components. The second is why `toPath` rejects it -- a URI // whose segment holds a separator has no Windows path. const u = try Uri.parse(alloc, "file:///a%5Cb"); defer u.deinit(); const posix = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(posix); try expectEqualStrings("/a\\b", posix); try expectError(error.InvalidPath, u.toPath(alloc, .{ .platform = .windows })); } // -- the round trip -------------------------------------------------------- test "a POSIX path survives the round trip exactly" { const alloc = std.testing.allocator; // Every byte that means something to a URI parser, plus a few that mean // something to a path, in the one place a path can hold them. const paths = [_][]const u8{ "/", "/a", "/a/", "//", "///", "/a/b/c", "/a//b", "/a/./b", "/a/../b", "/a b", "/a%20b", "/a?b", "/a#b", "/a&b=c", "/a:b", "/a@b", "/a[b]c", "/a\\b", "/a|b", "/.hidden", "/\xff\xfe", "/\xc3\xa9", "/C:/x", "/~jeff/a", "/a/b/../../../../c", }; for (paths) |path| { const u = try Uri.fromPath(alloc, path, .{ .platform = .posix }); defer u.deinit(); const back = try u.toPath(alloc, .{ .platform = .posix }); defer alloc.free(back); try expectEqualStrings(path, back); // And through the text, which is the trip that actually happens: a // URI is written down somewhere and read back by something else. const text = try u.toText(alloc, .{}); defer alloc.free(text); const reparsed = try Uri.parse(alloc, text); defer reparsed.deinit(); const back_again = try reparsed.toPath(alloc, .{ .platform = .posix }); defer alloc.free(back_again); try expectEqualStrings(path, back_again); } } test "a Windows path round-trips in canonical form" { const alloc = std.testing.allocator; // Not byte-for-byte: both separators go in and only `\` comes out. What // has to hold is that converting again changes nothing. const paths = [_][]const u8{ "C:\\", "C:\\a", "C:/a", "C:\\a\\b\\", "C:\\a b\\c#d", "\\\\s\\share", "\\\\s\\a\\b", "\\\\s/a/b", "\\a\\b", "\\", "z:\\a", "C:\\a\\..\\b", }; for (paths) |path| { const u = try Uri.fromPath(alloc, path, .{ .platform = .windows }); defer u.deinit(); const once = try u.toPath(alloc, .{ .platform = .windows }); defer alloc.free(once); const again = try Uri.fromPath(alloc, once, .{ .platform = .windows }); defer again.deinit(); const twice = try again.toPath(alloc, .{ .platform = .windows }); defer alloc.free(twice); try expectEqualStrings(once, twice); try std.testing.expect(u.eql(again)); } } // -- building on top ------------------------------------------------------- test "a file URI is an ordinary Uri, and click and relativize work on it" { const alloc = std.testing.allocator; const base = try Uri.fromPath(alloc, "/home/jeff/dev/zig-uri/", .{ .platform = .posix }); defer base.deinit(); // What a relative path in a document under that directory names. const target = try base.click(alloc, "src/file.zig"); defer target.deinit(); const path = try target.toPath(alloc, .{ .platform = .posix }); defer alloc.free(path); try expectEqualStrings("/home/jeff/dev/zig-uri/src/file.zig", path); // And back the other way. const rel = try base.relativize(alloc, target, .{}); defer rel.deinit(); const rel_text = try rel.toText(alloc, .{}); defer alloc.free(rel_text); try expectEqualStrings("src/file.zig", rel_text); } test "the default platform is the one being built for" { const builtin = @import("builtin"); const expected: uri.file.Platform = if (builtin.os.tag == .windows) .windows else .posix; try expectEqual(expected, (uri.file.Options{}).platform); }