Add time doc

2 files changed, 70 insertions, 3 deletions

diff --git a/docs/nav.ts b/docs/nav.ts
index 12333e6da..2832a53cf 100644
--- a/docs/nav.ts
+++ b/docs/nav.ts
@@ -180,6 +180,9 @@ export default {
     page("cli/test", "`bun test`", {
       description: "Bun's test runner uses Jest-compatible syntax but runs 100x faster.",
     }),
+    page("test/hot", "Watch mode", {
+      description: "Reload your tests automatically on change.",
+    }),
     page("test/writing", "Writing tests", {
       description:
         "Write your tests using Jest-like expect matchers, plus setup/teardown hooks, snapshot testing, and more",
@@ -190,12 +193,12 @@ export default {
     page("test/snapshots", "Snapshots", {
       description: "Add lifecycle hooks to your tests that run before/after each test or test run",
     }),
+    page("test/time", "Time", {
+      description: "Control the date & time in your tests for more reliable and deterministic tests",
+    }),
     page("test/dom", "DOM testing", {
       description: "Write headless tests for UI and React/Vue/Svelte/Lit components with happy-dom",
     }),
-    page("test/hot", "Watch mode", {
-      description: "Reload your tests automatically on change.",
-    }),
 
     divider("Package runner"),
     page("cli/bunx", "`bunx`", {
diff --git a/docs/test/time.md b/docs/test/time.md
new file mode 100644
index 000000000..94e954020
--- /dev/null
+++ b/docs/test/time.md
@@ -0,0 +1,64 @@
+`bun:test` lets you change what time it is in your tests. This was introduced in Bun v0.6.13.
+
+This works with any of the following:
+
+- `Date.now`
+- `new Date()`
+- `new Intl.DateTimeFormat().format()`
+
+Timers are not impacted yet, but may be in a future release of Bun.
+
+## `setSystemTime`
+
+To change the system time, use `setSystemTime`:
+
+```ts
+import { setSystemTime, beforeAll } from "bun:test";
+
+beforeAll(() => {
+  setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+});
+
+test("it is 2020", () => {
+  expect(new Date().getFullYear()).toBe(2020);
+});
+```
+
+### Reset the system time
+
+To reset the system time, pass no arguments to `setSystemTime`:
+
+```ts
+import { setSystemTime, beforeAll } from "bun:test";
+
+test("it was 2020, for a moment.", () => {
+  setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+  expect(new Date().getFullYear()).toBe(2020);
+  setSystemTime();
+  expect(new Date().getFullYear()).toBeGreaterThan(2020);
+});
+```
+
+## Set the time zone
+
+To change the time zone, either pass the `$TZ` environment variable to your test runner, or set `process.env.TZ` at runtime:
+
+```ts
+import { test, expect } from "bun:test";
+
+test("Welcome to California!", () => {
+  process.env.TZ = "America/Los_Angeles";
+  expect(new Date().getTimezoneOffset()).toBe(420);
+  expect(new Intl.DateTimeFormat().resolvedOptions().timeZone).toBe(
+    "America/Los_Angeles",
+  );
+});
+
+test("Welcome to New York!", () => {
+  process.env.TZ = "America/New_York";
+  expect(new Date().getTimezoneOffset()).toBe(300);
+  expect(new Intl.DateTimeFormat().resolvedOptions().timeZone).toBe(
+    "America/New_York",
+  );
+});
+```