// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT /** * The test suite for the JavaScript binding, written once and run twice: by * `uri.test.js` under node (`zig build test-web`), and by `browser-test.html` * inside a real browser (`nix build .#checks..browser`). What is under * test is the boundary — that arguments and results cross it intact, that * failures arrive as `UriError`, that nothing is leaked, and that the pieces * `uri.js` implements itself behave the way their Zig counterparts do. The * parser proper is already covered by the Zig tests. * * `init` must have run before `suite` is called; the runner sees to that. */ import { Uri, UriError, charSets, defaultPort, hasUnicode, memoryBytes, normalize, percentDecode, percentEncode, resolve, toIri, toUri, idnaToAscii, idnaToUnicode, usesNetloc, } from "./uri.js"; /** * Register every test. `test` and `assert` are node's, or the small * work-alikes `browser-test.html` provides. */ export function suite({ test, assert }) { /** `assert.throws` does not hand back the error, and these tests want its code. */ function caught(fn) { try { fn(); } catch (error) { return error; } assert.fail("expected a throw"); } const unicode = hasUnicode(); // -- parsing --------------------------------------------------------------- test("parses a full reference", () => { const u = Uri.parse("https://user:secret@example.com:8443/a/b?q=1&flag#top"); assert.equal(u.scheme, "https"); assert.equal(u.username, "user"); assert.equal(u.password, "secret"); assert.equal(u.host, "example.com"); assert.equal(u.hostKind, "name"); assert.equal(u.port, 8443); assert.equal(u.rooted, true); assert.deepEqual(u.path, ["a", "b"]); assert.deepEqual(u.query, [ { key: "q", value: "1" }, { key: "flag", value: null }, ]); assert.equal(u.fragment, "top"); }); test("components arrive decoded", () => { const u = Uri.parse("http://x/a%2Fb/%41?k%3D=v%26"); assert.deepEqual(u.path, ["a/b", "A"]); assert.deepEqual(u.query, [{ key: "k=", value: "v&" }]); // ...and are escaped again on the way out, canonically. assert.equal(u.toString(), "http://x/a%2Fb/A?k%3D=v%26"); }); test("address literals keep their kind", () => { assert.equal(Uri.parse("http://192.0.2.16/").hostKind, "ipv4"); const six = Uri.parse("http://[2001:db8::1]:80/"); assert.equal(six.hostKind, "ipv6"); assert.equal(six.host, "2001:db8::1", "brackets are not part of the host"); assert.equal(six.toString(), "http://[2001:db8::1]:80/"); }); test("a relative reference has no scheme", () => { const u = Uri.parse("../c/d?x#y"); assert.equal(u.scheme, null); assert.equal(u.host, null); assert.equal(u.hostKind, null); assert.equal(u.rooted, false); assert.deepEqual(u.path, ["..", "c", "d"]); }); test("instances are frozen", () => { const u = Uri.parse("http://x/a"); assert.throws(() => { u.scheme = "ftp"; }, TypeError); assert.throws(() => u.path.push("b"), TypeError); }); // -- failures -------------------------------------------------------------- test("a parse failure is a UriError carrying the Zig error name", () => { const error = caught(() => Uri.parse("http://[::1")); assert.ok(error instanceof UriError); assert.equal(error.code, "UnterminatedIPv6Literal"); }); test("failures name the component that went wrong", () => { assert.equal(caught(() => Uri.parse("http://x:99999/")).code, "InvalidPort"); assert.equal(caught(() => Uri.parse("1http://x/")).code, "InvalidScheme"); assert.equal( caught(() => percentDecode("%zz", { strictPercent: true })).code, "InvalidPercentEncoding", ); }); test("a lenient percent decode keeps a stray % as itself", () => { assert.equal(percentDecode("100%"), "100%"); assert.equal(percentDecode("a%20b"), "a b"); }); // -- text out -------------------------------------------------------------- test("the password is withheld unless asked for", () => { const u = Uri.parse("https://user:secret@example.com/"); assert.equal(u.toString(), "https://user:@example.com/"); assert.equal(u.toString({ withPassword: true }), "https://user:secret@example.com/"); }); test("IRI form keeps the characters RFC 3987 permits", () => { const u = Uri.parse("http://x/caf%C3%A9"); assert.equal(u.toString(), "http://x/caf%C3%A9"); assert.equal(u.toString({ form: "iri" }), "http://x/café"); }); test("an unknown text form is a TypeError, not a UriError", () => { assert.throws(() => Uri.parse("http://x/").toString({ form: "urn" }), TypeError); }); test("authority", () => { assert.equal(Uri.parse("https://user@example.com:8443/a").authority(), "user@example.com:8443"); assert.equal(Uri.parse("mailto:me@example.com").authority(), ""); }); // -- resolution ------------------------------------------------------------ test("resolve follows RFC 3986 section 5", () => { const base = Uri.parse("http://a/b/c/d;p?q"); const cases = [ ["g", "http://a/b/c/g"], ["./g", "http://a/b/c/g"], ["/g", "http://a/g"], ["//g", "http://g"], ["?y", "http://a/b/c/d;p?y"], ["#s", "http://a/b/c/d;p?q#s"], ["../..", "http://a/"], ["../../g", "http://a/g"], ["http://x/y", "http://x/y"], ]; for (const [href, want] of cases) { assert.equal(base.resolve(href).toString(), want, href); assert.equal(resolve("http://a/b/c/d;p?q", href), want, `${href} (free function)`); } }); test("resolving keeps the base's password", () => { const base = Uri.parse("https://user:secret@example.com/a/"); assert.equal( base.resolve("b").toString({ withPassword: true }), "https://user:secret@example.com/a/b", ); }); // -- normalization --------------------------------------------------------- test("normalize lowercases and resolves dot segments", () => { assert.equal(normalize("HTTP://EXAMPLE.com/a/./b/../c"), "http://example.com/a/c"); }); test("the scheme-based rules are opt-in", () => { assert.equal(normalize("http://x:80"), "http://x:80"); assert.equal( normalize("http://x:80", { dropDefaultPort: true, rootEmptyPath: true }), "http://x/", ); }); test("turning a rule off leaves that part alone", () => { assert.equal(normalize("HTTP://X/a/../b", { scheme: false }), "HTTP://x/b"); assert.equal(normalize("HTTP://X/a/../b", { path: false }), "http://x/a/../b"); }); test("normalize on a Uri agrees with the free function", () => { const text = "HTTP://EXAMPLE.com:80/a/./b/.."; const options = { dropDefaultPort: true }; assert.equal(Uri.parse(text).normalize(options).toString(), normalize(text, options)); }); // -- derivation ------------------------------------------------------------ test("with changes only the named components", () => { const u = Uri.parse("https://example.com:8443/a/b?q=1#top"); assert.equal(u.with({ scheme: "http" }).toString(), "http://example.com:8443/a/b?q=1#top"); assert.equal(u.with({ port: null }).toString(), "https://example.com/a/b?q=1#top"); assert.equal(u.with({ fragment: null }).toString(), "https://example.com:8443/a/b?q=1"); assert.equal(u.with({}).toString(), u.toString()); assert.throws(() => u.with({ nonsense: 1 }), TypeError); }); test("with can move the host between kinds", () => { const u = Uri.parse("http://example.com/"); assert.equal(u.with({ host: "2001:db8::1", hostKind: "ipv6" }).toString(), "http://[2001:db8::1]/"); }); test("child replaces a trailing empty segment rather than appending to it", () => { assert.equal(Uri.parse("http://x/a/").child("b").toString(), "http://x/a/b"); assert.equal(Uri.parse("http://x/a").child("b").toString(), "http://x/a/b"); assert.equal(Uri.parse("http://x/a").child("b", "c").toString(), "http://x/a/b/c"); const u = Uri.parse("http://x/a"); assert.equal(u.child(), u); }); test("sibling replaces the last segment", () => { assert.equal(Uri.parse("http://x/a/b").sibling("c").toString(), "http://x/a/c"); assert.equal(Uri.parse("http://x/").sibling("c").toString(), "http://x/c"); }); test("segments needing escapes get them", () => { assert.equal(Uri.parse("http://x/").child("a b/c").toString(), "http://x/a%20b%2Fc"); }); // -- query ----------------------------------------------------------------- test("query lookup distinguishes a bare key from an empty value", () => { const u = Uri.parse("http://x/?a=1&flag&a=2&empty="); assert.deepEqual(u.get("a"), ["1", "2"]); assert.deepEqual(u.first("a"), { key: "a", value: "1" }); assert.deepEqual(u.last("a"), { key: "a", value: "2" }); assert.deepEqual(u.first("flag"), { key: "flag", value: null }); assert.deepEqual(u.first("empty"), { key: "empty", value: "" }); assert.equal(u.has("flag"), true); assert.equal(u.has("nope"), false); assert.equal(u.first("nope"), null); }); test("add appends, set overwrites in place and drops duplicates", () => { const u = Uri.parse("http://x/?a=1&b=2&a=3"); assert.equal(u.add("a", "4").toString(), "http://x/?a=1&b=2&a=3&a=4"); assert.equal(u.set("a", "9").toString(), "http://x/?a=9&b=2"); assert.equal(u.set("c", "1").toString(), "http://x/?a=1&b=2&a=3&c=1"); assert.equal(u.add("bare").toString(), "http://x/?a=1&b=2&a=3&bare"); }); test("remove and removeWhere", () => { const u = Uri.parse("http://x/?a=1&b=2&a=3&a"); assert.equal(u.remove("a").toString(), "http://x/?b=2"); assert.equal(u.removeWhere("a", { value: "1" }).toString(), "http://x/?b=2&a=3&a"); assert.equal(u.removeWhere("a", { value: null }).toString(), "http://x/?a=1&b=2&a=3"); assert.equal(u.removeWhere("a", { limit: 1 }).toString(), "http://x/?b=2&a=3&a"); }); // -- inspection ------------------------------------------------------------ test("scheme facts come from the library's own table", () => { assert.equal(defaultPort("https"), 443); assert.equal(defaultPort("nosuchscheme"), null); assert.equal(usesNetloc("http"), true); assert.equal(usesNetloc("mailto"), false); const u = Uri.parse("https://example.com/"); assert.equal(u.isAbsolute(), true); assert.equal(u.defaultPort(), 443); assert.equal(u.port, null, "the written port stays absent"); assert.equal(u.effectivePort(), 443); assert.equal(Uri.parse("/a/b").isAbsolute(), false); }); test("equals compares component by component", () => { assert.equal(Uri.parse("http://x/a").equals(Uri.parse("http://x/a")), true); assert.equal(Uri.parse("http://x/a").equals(Uri.parse("http://x/a/")), false); assert.equal(Uri.parse("http://x/%41").equals(Uri.parse("http://x/A")), true); assert.equal(Uri.parse("http://x/a").equals("http://x/a"), false); }); // -- percent --------------------------------------------------------------- test("percentEncode honours the named character set", () => { assert.equal(percentEncode("a b/c"), "a%20b%2Fc"); assert.equal(percentEncode("a=b&c", { set: "query-value" }), "a=b%26c"); assert.equal(percentEncode("café"), "caf%C3%A9"); assert.equal(percentEncode("café", { form: "iri" }), "café"); assert.throws(() => percentEncode("x", { set: "nope" }), TypeError); assert.ok(charSets.includes("segment")); }); // -- JSON ------------------------------------------------------------------ test("a Uri survives a JSON round trip", () => { const u = Uri.parse("https://user:secret@[2001:db8::1]:8443/a/b?q=1&flag#top"); const back = Uri.fromJSON(JSON.parse(JSON.stringify(u))); assert.equal(back.equals(u), true); assert.equal(back.toString({ withPassword: true }), u.toString({ withPassword: true })); }); test("a Uri can be built from plain components", () => { const u = new Uri({ scheme: "https", host: "example.com", rooted: true, path: ["a", "b"], query: [{ key: "q", value: "1" }], fragment: "top", }); assert.equal(u.toString(), "https://example.com/a/b?q=1#top"); assert.equal(new Uri().toString(), ""); }); test("bad components are rejected before they reach wasm", () => { assert.throws(() => new Uri({ scheme: 5 }), TypeError); assert.throws(() => new Uri({ port: 70000 }), TypeError); assert.throws(() => new Uri({ port: 1.5 }), TypeError); assert.throws(() => new Uri({ host: "x", hostKind: "dns" }), TypeError); assert.throws(() => new Uri({ path: [1] }), TypeError); }); // -- Unicode --------------------------------------------------------------- test("IDNA and IRI conversion", { skip: !unicode && "built without -Dunicode" }, () => { assert.equal(idnaToAscii("münchen.de"), "xn--mnchen-3ya.de"); assert.equal(idnaToUnicode("xn--mnchen-3ya.de"), "münchen.de"); assert.equal(toUri("http://münchen.de/straße"), "http://xn--mnchen-3ya.de/stra%C3%9Fe"); assert.equal( toIri("http://xn--mnchen-3ya.de/stra%C3%9Fe", { form: "iri" }), "http://münchen.de/straße", ); const u = Uri.parse("http://münchen.de/"); assert.equal(u.toUri().host, "xn--mnchen-3ya.de"); assert.equal(u.toUri().toIri().host, "münchen.de"); assert.equal(caught(() => idnaToAscii("a..b")).code, "EmptyLabel"); }); test("without Unicode the IDNA calls say so", { skip: unicode && "built with -Dunicode" }, () => { assert.equal(caught(() => idnaToAscii("münchen.de")).code, "UnicodeUnavailable"); assert.equal(caught(() => toUri("http://münchen.de/")).code, "UnicodeUnavailable"); }); // -- the boundary itself --------------------------------------------------- test("non-ASCII text crosses intact", () => { const u = Uri.parse("http://x/%E6%97%A5%E6%9C%AC?q=%F0%9F%8E%89"); assert.deepEqual(u.path, ["日本"]); assert.deepEqual(u.get("q"), ["🎉"]); assert.equal(u.toString(), "http://x/%E6%97%A5%E6%9C%AC?q=%F0%9F%8E%89"); }); test("empty arguments are not a null pointer bug", () => { assert.equal(percentDecode(""), ""); assert.equal(percentEncode(""), ""); assert.equal(Uri.parse("").toString(), ""); assert.equal(resolve("http://x/a", ""), "http://x/a"); }); test("thousands of calls do not grow linear memory without bound", () => { // Every call allocates its arguments and its result; if either were leaked, // the allocator would have to keep reaching for more pages. const long = "x".repeat(4096); const round = () => Uri.parse(`http://example.com/a/${long}?q=${long}`).resolve("../b").toString(); for (let i = 0; i < 50; i += 1) round(); const before = memoryBytes(); for (let i = 0; i < 2000; i += 1) round(); assert.equal(memoryBytes(), before); }); }