Do not use normalized URLs by default. Add normalize flag to ZodURL. Closes #4906

Author: colinhacks

.cursor/rules/testing-guidelines.mdc

@@ -0,0 +1,111 @@
+---
+description: Testing guidelines for the Zod codebase - when to use play.ts vs test suite, TypeScript requirements, and testing patterns
+globs: *.test.ts,*.test.tsx,play.ts
+---
+
+# Zod Testing Guidelines
+
+## Always Use TypeScript
+- **All tests must be written in TypeScript** - never use JavaScript
+- Test files should use `.test.ts` extension
+- Import types properly: `import type { ... }`
+
+## When to Use play.ts vs Test Suite
+
+### Use [play.ts](mdc:play.ts) for:
+- Quick experimentation and prototyping
+- Manual testing of new features during development
+- Debugging specific behaviors
+- One-off validation of edge cases
+- Temporary verification before writing formal tests
+
+### Use Test Suite for:
+- **All permanent test cases** - features must have proper tests
+- Regression testing
+- API validation
+- Edge case coverage
+- Performance benchmarks
+
+## Test Organization
+
+### Test File Structure
+Tests are located in:
+- `packages/zod/src/v4/classic/tests/` - V4 classic API tests
+- `packages/zod/src/v4/core/tests/` - V4 core tests  
+- `packages/zod/src/v3/tests/` - V3 compatibility tests
+
+### Test File Naming
+- Use descriptive names: `string.test.ts`, `object.test.ts`, `url-validation.test.ts`
+- Group related functionality in the same test file
+- Follow existing patterns in [packages/zod/src/v4/classic/tests/string.test.ts](mdc:packages/zod/src/v4/classic/tests/string.test.ts)
+
+## Test Writing Patterns
+
+### Framework Usage
+- Use **Vitest** as the test framework
+- Import: `import { expect, test } from "vitest";`
+- Import Zod: `import * as z from "zod/v4";`
+
+### Test Structure
+```typescript
+test("descriptive test name", () => {
+  const schema = z.string().url();
+  
+  // Test valid cases
+  expect(schema.parse("https://example.com")).toBe("https://example.com");
+  
+  // Test invalid cases
+  expect(() => schema.parse("invalid")).toThrow();
+});
+```
+
+### Testing Preferences
+- **Keep test suites concise** - use as few test cases as needed to cover functionality
+- **Don't skip tests** due to type issues - fix the types instead
+- **Don't oversimplify tests** - maintain adequate coverage
+- Test both success and failure cases
+- Use descriptive test names that explain the behavior being tested
+
+### URL Testing Example
+When testing URL validation (as seen in recent work):
+```typescript
+test("url preserves original input", () => {
+  const url = z.string().url();
+  const input = "https://example.com?key=value";
+  expect(url.parse(input)).toBe(input);
+});
+
+test("url normalize flag", () => {
+  const normalizeUrl = z.url({ normalize: true });
+  expect(normalizeUrl.parse("https://example.com?key=value"))
+    .toBe("https://example.com/?key=value");
+});
+```
+
+## Running Tests
+
+### Run Specific Tests
+```bash
+pnpm vitest run src/v4/classic/tests/string.test.ts -t "url"
+```
+
+### Run All Tests
+```bash
+pnpm test
+```
+
+### Build Before Testing
+Always rebuild when testing core changes:
+```bash
+pnpm build && pnpm test
+```
+
+## Test Development Workflow
+
+1. **Start with [play.ts](mdc:play.ts)** for initial exploration
+2. **Write proper tests** once behavior is confirmed
+3. **Test edge cases** and error conditions
+4. **Verify backward compatibility**
+5. **Run full test suite** before committing
+
+Remember: Features without tests are incomplete. Every new feature or bug fix should include corresponding test coverage.

packages/docs/content/api.mdx

@@ -357,6 +357,13 @@ schema.parse("http://example.com"); // ❌
   ```
 </Callout>
 
+To normalize URLs, use the `normalize` flag. This will overwrite the input value with the [normalized URL](https://chatgpt.com/share/6881547f-bebc-800f-9093-f5981e277c2c) returned by `new URL()`.
+
+```ts
+new URL("HTTP://ExAmPle.com:80/./a/../b?X=1#f oo").href
+// => "http://example.com/b?X=1#f%20oo"
+```
+
 ### ISO datetimes
 
 As you may have noticed, Zod string includes a few date/time related validations. These validations are regular expression based, so they are not as strict as a full date/time library. However, they are very convenient for validating user input.

packages/zod/src/v4/classic/tests/recursive-types.test.ts

@@ -325,13 +325,6 @@ test("object utilities with recursive types", () => {
     RequiredNode,
     RequiredMaskedNode,
   ]);
-
-  // Verify they can be used without causing circularity issues
-  // expect(PickedNode._zod.def.shape.id).toBeDefined();
-  // expect("children" in OmittedNode._zod.def.shape).toBe(false);
-  // expect(MergedNode._zod.def.shape.metadata).toBeDefined();
-  // expect(PartialNode._zod.def.shape.id).toBeDefined();
-  // expect(RequiredNode._zod.def.shape.id).toBeDefined();
 });
 
 test("recursion compatibility", () => {

packages/zod/src/v4/classic/tests/string.test.ts

@@ -318,6 +318,83 @@ test("url validations", () => {
   expect(() => url.parse("https://")).toThrow();
 });
 
+test("url preserves original input", () => {
+  const url = z.string().url();
+
+  // Test the specific case from the user report
+  const input = "https://example.com?key=NUXOmHqWNVTapJkJJHw8BfD155AuqhH_qju_5fNmQ4ZHV7u8";
+  const output = url.parse(input);
+  expect(output).toBe(input); // Should preserve the original input exactly
+
+  // Test other cases where URL constructor would normalize
+  expect(url.parse("https://example.com?foo=bar")).toBe("https://example.com?foo=bar");
+  expect(url.parse("http://example.com?test=123")).toBe("http://example.com?test=123");
+  expect(url.parse("https://sub.example.com?param=value&other=data")).toBe(
+    "https://sub.example.com?param=value&other=data"
+  );
+
+  // Test cases with trailing slashes are preserved
+  expect(url.parse("https://example.com/")).toBe("https://example.com/");
+  expect(url.parse("https://example.com/path/")).toBe("https://example.com/path/");
+
+  // Test cases with paths and query parameters
+  expect(url.parse("https://example.com/path?query=param")).toBe("https://example.com/path?query=param");
+});
+
+test("url trims whitespace", () => {
+  const url = z.string().url();
+
+  // Test trimming whitespace from URLs
+  expect(url.parse("  https://example.com  ")).toBe("https://example.com");
+  expect(url.parse("  https://example.com/path?query=param  ")).toBe("https://example.com/path?query=param");
+  expect(url.parse("\t\nhttps://example.com\t\n")).toBe("https://example.com");
+  expect(url.parse("   https://example.com?key=value   ")).toBe("https://example.com?key=value");
+
+  // Test that URLs without extra whitespace are unchanged
+  expect(url.parse("https://example.com")).toBe("https://example.com");
+  expect(url.parse("https://example.com/path")).toBe("https://example.com/path");
+});
+
+test("url normalize flag", () => {
+  const normalizeUrl = z.url({ normalize: true });
+  const preserveUrl = z.url(); // normalize: false/undefined by default
+
+  // Test that normalize flag causes URL normalization
+  expect(normalizeUrl.parse("https://example.com?key=value")).toBe("https://example.com/?key=value");
+  expect(normalizeUrl.parse("http://example.com?test=123")).toBe("http://example.com/?test=123");
+
+  // Test with already normalized URLs
+  expect(normalizeUrl.parse("https://example.com/")).toBe("https://example.com/");
+  expect(normalizeUrl.parse("https://example.com/path?query=param")).toBe("https://example.com/path?query=param");
+
+  // Test complex URLs with normalization
+  expect(normalizeUrl.parse("https://example.com/../?key=value")).toBe("https://example.com/?key=value");
+  expect(normalizeUrl.parse("https://example.com/./path?key=value")).toBe("https://example.com/path?key=value");
+
+  // Compare with non-normalize behavior
+  expect(preserveUrl.parse("https://example.com?key=value")).toBe("https://example.com?key=value");
+  expect(preserveUrl.parse("http://example.com?test=123")).toBe("http://example.com?test=123");
+
+  // Test trimming with normalize
+  expect(normalizeUrl.parse("  https://example.com?key=value  ")).toBe("https://example.com/?key=value");
+  expect(preserveUrl.parse("  https://example.com?key=value  ")).toBe("https://example.com?key=value");
+});
+
+test("url normalize with hostname and protocol constraints", () => {
+  const constrainedNormalizeUrl = z.url({
+    normalize: true,
+    protocol: /^https$/,
+    hostname: /^example\.com$/,
+  });
+
+  // Test that normalization works with constraints
+  expect(constrainedNormalizeUrl.parse("https://example.com?key=value")).toBe("https://example.com/?key=value");
+
+  // Test that constraints are still enforced
+  expect(() => constrainedNormalizeUrl.parse("http://example.com?key=value")).toThrow();
+  expect(() => constrainedNormalizeUrl.parse("https://other.com?key=value")).toThrow();
+});
+
 test("httpurl", () => {
   const httpUrl = z.url({
     protocol: /^https?$/,

packages/zod/src/v4/core/schemas.ts

@@ -417,6 +417,7 @@ export const $ZodEmail: core.$constructor<$ZodEmail> = /*@__PURE__*/ core.$const
 export interface $ZodURLDef extends $ZodStringFormatDef<"url"> {
   hostname?: RegExp | undefined;
   protocol?: RegExp | undefined;
+  normalize?: boolean | undefined;
 }
 export interface $ZodURLInternals extends $ZodStringFormatInternals<"url"> {
   def: $ZodURLDef;
@@ -430,10 +431,10 @@ export const $ZodURL: core.$constructor<$ZodURL> = /*@__PURE__*/ core.$construct
   $ZodStringFormat.init(inst, def);
   inst._zod.check = (payload) => {
     try {
-      const orig = payload.value;
+      // Trim whitespace from input
+      const trimmed = payload.value.trim();
       // @ts-ignore
-      const url = new URL(orig);
-      const href = url.href;
+      const url = new URL(trimmed);
 
       if (def.hostname) {
         def.hostname.lastIndex = 0;
@@ -465,11 +466,13 @@ export const $ZodURL: core.$constructor<$ZodURL> = /*@__PURE__*/ core.$construct
         }
       }
 
-      // payload.value = url.href;
-      if (!orig.endsWith("/") && href.endsWith("/")) {
-        payload.value = href.slice(0, -1);
+      // Set the output value based on normalize flag
+      if (def.normalize) {
+        // Use normalized URL
+        payload.value = url.href;
       } else {
-        payload.value = href;
+        // Preserve the original input (trimmed)
+        payload.value = trimmed;
       }
 
       return;