Docs and types for v0.8.0 (oven-sh#4199)

* Improve test documentation * Update nodejs compat docs with tty * Add debugger guide * Document Bun.inspect.custom, improve bun test nav * Address reviews * Update Bun.file types * Add Nuxt guide * Add tty types
BrettBlox · Aug 22, 2023 · 3a45f2c · 3a45f2c
1 parent 9eeb7bd
commit 3a45f2c
Show file tree

Hide file tree

Showing 10 changed files with 487 additions and 37 deletions.
diff --git a/docs/api/utils.md b/docs/api/utils.md
@@ -428,6 +428,21 @@ const str = Bun.inspect(arr);
 // => "Uint8Array(3) [ 1, 2, 3 ]"
 ```
 
+## `Bun.inspect.custom`
+
+This is the symbol that Bun uses to implement `Bun.inspect`. You can override this to customize how your objects are printed. It is identical to `util.inspect.custom` in Node.js.
+
+```ts
+class Foo {
+  [Bun.inspect.custom]() {
+    return "foo";
+  }
+}
+
+const foo = new Foo();
+console.log(foo); // => "foo"
+```
+
 ## `Bun.nanoseconds()`
 
 Returns the number of nanoseconds since the current `bun` process started, as a `number`. Useful for high-precision timing and benchmarking.

diff --git a/docs/cli/test.md b/docs/cli/test.md
@@ -30,14 +30,50 @@ The runner recursively searches the working directory for files that match the f
 - `*.spec.{js|jsx|ts|tsx}`
 - `*_spec.{js|jsx|ts|tsx}`
 
-You can filter the set of tests to run by passing additional positional arguments to `bun test`. Any file in the directory with an _absolute path_ that contains one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported.
+You can filter the set of _test files_ to run by passing additional positional arguments to `bun test`. Any test file with a path that matches one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported.
 
 ```bash
 $ bun test <filter> <filter> ...
 ```
 
+To filter by _test name_, use the `-t`/`--test-name-pattern` flag.
+
+```sh
+# run all tests or test suites with "addition" in the name
+$ bun test --test-name-pattern addition
+```
+
 The test runner runs all tests in a single process. It loads all `--preload` scripts (see [Lifecycle](/docs/test/lifecycle) for details), then runs all tests. If a test fails, the test runner will exit with a non-zero exit code.
 
+## Timeouts
+
+Use the `--timeout` flag to specify a _per-test_ timeout in milliseconds. If a test times out, it will be marked as failed. The default value is `5000`.
+
+```bash
+# default value is 5000
+$ bun test --timeout 20
+```
+
+## Rerun tests
+
+Use the `--rerun-each` flag to run each test multiple times. This is useful for detecting flaky or non-deterministic test failures.
+
+```sh
+$ bun test --rerun-each 100
+```
+
+## Bail out with `--bail`
+
+Use the `--bail` flag to abort the test run early after a pre-determined number of test failures. By default Bun will run all tests and report all failures, but sometimes in CI environments it's preferable to terminate earlier to reduce CPU usage.
+
+```sh
+# bail after 1 failure
+$ bun test --bail
+
+# bail after 10 failure
+$ bun test --bail 10
+```
+
 ## Watch mode
 
 Similar to `bun run`, you can pass the `--watch` flag to `bun test` to watch for changes and re-run tests.

diff --git a/docs/guides/ecosystem/nuxt.md b/docs/guides/ecosystem/nuxt.md
@@ -0,0 +1,65 @@
+---
+name: Build an app with Nuxt and Bun
+---
+
+Bun supports [Nuxt](https://nuxt.com) out of the box. Initialize a Nuxt app with official `nuxi` CLI.
+
+```sh
+$ bunx nuxi init my-nuxt-app
+Nuxi 3.6.5
+✨ Nuxt project is created with v3 template. Next steps:
+ › cd my-nuxt-app
+ › Install dependencies with npm install or yarn install or pnpm install
+ › Start development server with npm run dev or yarn dev or pnpm run dev
+```
+
+---
+
+Then move into the project directory and install dependencies.
+
+```sh
+$ cd my-app
+$ bun install
+bun install v0.8.0
+ + @nuxt/[email protected]
+ + @types/[email protected]
+ + [email protected]
+Nuxi 3.6.5
+✔ Types generated in .nuxt
+
+ 776 packages installed [1.72s]
+```
+
+---
+
+To start the dev server, run `bun run dev` from the project root. This will execute the `nuxt dev` command (as defined in the `"dev"` script in `package.json`).
+
+{% callout %}
+The `nuxt` CLI uses Node.js by default; passing the `--bun` flag forces the dev server to use the Bun runtime instead.
+{% /callout %}
+
+```
+$ bun --bun run dev
+ $ nuxt dev
+Nuxi 3.6.5
+Nuxt 3.6.5 with Nitro 2.5.2
+  > Local:    http://localhost:3000/
+  > Network:  http://192.168.0.21:3000/
+  > Network:  http://[fd8a:d31d:481c:4883:1c64:3d90:9f83:d8a2]:3000/
+
+✔ Nuxt DevTools is enabled v0.8.0 (experimental)
+ℹ Vite client warmed up in 547ms
+✔ Nitro built in 244 ms
+```
+
+---
+
+Once the dev server spins up, open [http://localhost:3000](http://localhost:3000) to see the app. The app will render Nuxt's built-in `WelcomePage` template component.
+
+To start developing your app, replace `<WelcomePage />` in `app.vue` with your own UI.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/2c683ecc-3298-4bb0-b8c0-cf4cfaea1daa" caption="Demo Nuxt app running on localhost" /%}
+
+---
+
+Refer to the [Nuxt website](https://nuxt.com/docs) for complete documentation.
diff --git a/docs/guides/runtime/web-debugger.md b/docs/guides/runtime/web-debugger.md
@@ -0,0 +1,82 @@
+---
+name: Debugging Bun with the web debugger
+---
+
+Bun speaks the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-vscode/types/jsc.d.ts). To enable debugging when running code with Bun, use the `--inspect` flag. For demonstration purposes, consider the following simple web server.
+
+```ts#server.ts
+Bun.serve({
+  fetch(req){
+    console.log(req.url);
+    return new Response("Hello, world!");
+  }
+})
+```
+
+---
+
+Let's run this file with the `--inspect` flag.
+
+This automatically starts a WebSocket server on an available port that can be used to introspect the running Bun process. Various debugging tools can connect to this server to provide an interactive debugging experience.
+
+Bun hosts a web-based debugger at [debug.bun.sh](https://debug.bun.sh). It is a modified version of WebKit's [Web Inspector Interface](https://webkit.org/web-inspector/web-inspector-interface/), which will look familiar to Safari users.
+
+```sh
+$ bun --inspect server.ts
+------------------ Bun Inspector ------------------
+Listening at:
+  ws://localhost:6499/0tqxs9exrgrm
+
+Inspect in browser:
+  https://debug.bun.sh/#localhost:6499/0tqxs9exrgrm
+------------------ Bun Inspector ------------------
+```
+
+---
+
+Open the provided `debug.bun.sh` URL in your browser to start a debugging session. From this interface, you'll be able to view the source code of the running file, view and set breakpoints, and execute code with the built-in console.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/e6a976a8-80cc-4394-8925-539025cc025d" alt="Screenshot of Bun debugger, Console tab" /%}
+
+---
+
+Let's set a breakpoint. Navigate to the Sources tab; you should see the code from earlier. Click on the line number `3` to set a breakpoint on our `console.log(req.url)` statement.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/3b69c7e9-25ff-4f9d-acc4-caa736862935" alt="screenshot of Bun debugger" /%}
+
+---
+
+Then visit [`http://localhost:3000`](http://localhost:3000) in your web browser. This will send an HTTP request to our `localhost` web server. It will seem like the page isn't loading. Why? Because the program has paused execution at the breakpoint we set earlier.
+
+Note how the UI has changed.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/8b565e58-5445-4061-9bc4-f41090dfe769" alt="screenshot of Bun debugger" /%}
+
+---
+
+At this point there's a lot we can do to introspect the current execution environment. We can use the console at the bottom to run arbitrary code in the context of the program, with full access to the variables in scope at our breakpoint.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/f4312b76-48ba-4a7d-b3b6-6205968ac681" /%}
+
+---
+
+On the right side of the Sources pane, we can see all local variables currently in scope, and drill down to see their properties and methods. Here, we're inspecting the `req` variable.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/63d7f843-5180-489c-aa94-87c486e68646" /%}
+
+---
+
+In the upper left of the Sources pane, we can control the execution of the program.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/41b76deb-7371-4461-9d5d-81b5a6d2f7a4" /%}
+
+---
+
+Here's a cheat sheet explaining the functions of the control flow buttons.
+
+- _Continue script execution_ — continue running the program until the next breakpoint or exception.
+- _Step over_ — The program will continue to the next line.
+- _Step into_ — If the current statement contains a function call, the debugger will "step into" the called function.
+- _Step out_ — If the current statement is a function call, the debugger will finish executing the call, then "step out" of the function to the location where it was called.
+
+{% image src="https://github-production-user-asset-6210df.s3.amazonaws.com/3084745/261510346-6a94441c-75d3-413a-99a7-efa62365f83d.png" /%}
diff --git a/docs/nav.ts b/docs/nav.ts
@@ -188,13 +188,13 @@ 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",
     }),
+    page("test/hot", "Watch mode", {
+      description: "Reload your tests automatically on change.",
+    }),
     page("test/lifecycle", "Lifecycle hooks", {
       description: "Add lifecycle hooks to your tests that run before/after each test or test run",
     }),

diff --git a/docs/runtime/nodejs-apis.md b/docs/runtime/nodejs-apis.md
@@ -138,7 +138,7 @@ This page is updated regularly to reflect compatibility status of the latest ver
 
 ### [`node:tty`](https://nodejs.org/api/tty.html)
 
-🟡 Missing `tty.ReadStream` and `tty.WriteStream`.
+🟢 Fully implemented.
 
 ### [`node:url`](https://nodejs.org/api/url.html)
 

diff --git a/docs/test/coverage.md b/docs/test/coverage.md
@@ -1,12 +1,11 @@
-`bun:test` supports seeing which lines of code are covered by tests. To use this feature, pass `--coverage` to the CLI:
+Bun's test runner now supports built-in _code coverage reporting_. This makes it easy to see how much of the codebase is covered by tests, and find areas that are not currently well-tested.
 
-```sh
-bun test --coverage
-```
+## Enabling coverage
 
-It will print out a coverage report to the console:
+`bun:test` supports seeing which lines of code are covered by tests. To use this feature, pass `--coverage` to the CLI. It will print out a coverage report to the console:
 
 ```js
+$ bun test --coverage
 -------------|---------|---------|-------------------
 File         | % Funcs | % Lines | Uncovered Line #s
 -------------|---------|---------|-------------------
@@ -26,32 +25,45 @@ All files    |   38.89 |   42.11 |
 -------------|---------|---------|-------------------
 ```
 
-If coverage is below a threshold, `bun:test` will exit with a non-zero exit code to indicate the failure.
+To always enable coverage reporting by default, add the following line to your `bunfig.toml`:
 
-### Configuring coverage
+```toml
+[test]
 
-`bunfig.toml` supports configuring coverage:
+# always enable coverage
+coverage = true
+```
+
+By default coverage reports will _include_ test files and _exclude_ sourcemaps. This is usually what you want, but it can be configured otherwise in `bunfig.toml`.
 
 ```toml
 [test]
+coverageSkipTestFiles = true       # default false
+```
 
-# Always enable coverage
-coverage = true
+### Coverage thresholds
 
-# Anything less than 90% coverage will fail the test
-# coverageThreshold = 0.9
-coverageThreshold = { line = 0.9, function = 0.9 }
+{% callout %}
+**Note** — Support for coverage reporting was added in Bun v0.7.3.
+{% /callout %}
 
+It is possible to specify a coverage threshold in `bunfig.toml`. If your test suite does not meet or exceed this threshold, `bun test` will exit with a non-zero exit code to indicate the failure.
 
-# Don't include .test.* files in coverage reports
-coverageSkipTestFiles = true
+```toml
+[test]
 
-# Disable sourcemap support in coverage reports
-# By default, coverage reports will automatically use Bun's internal sourcemap.
-# You probably don't want to configure this
-# coverageIgnoreSourcemaps = false
+# to require 90% line-level and function-level coverage
+coverageThreshold = 0.9
+
+# to set different thresholds for lines and functions
+coverageThreshold = { line = 0.9, function = 0.9 }
 ```
 
-`coverageThreshold` can be either a number or an object with `line` and `function` keys. When a number, it is treated as both the line and function threshold.
+### Sourcemaps
 
-Coverage support was added in Bun v0.7.3.
+Internally, Bun transpiles all files by default, so Bun automatically generates an internal [source map](https://web.dev/source-maps/) that maps lines of your original source code onto Bun's internal representation. If for any reason you want to disable this, set `test.coverageIgnoreSourcemaps` to `false`; this will rarely be desirable outside of advanced use cases.
+
+```toml
+[test]
+coverageIgnoreSourcemaps = true   # default false
+```
diff --git a/packages/bun-types/globals.d.ts b/packages/bun-types/globals.d.ts
@@ -602,9 +602,9 @@ interface Process {
   getgroups: () => number[];
   // setgroups?: (groups: ReadonlyArray<string | number>) => void;
   dlopen(module: { exports: any }, filename: string, flags?: number): void;
-  stdin: import("stream").Duplex & { isTTY: boolean };
-  stdout: import("stream").Writable & { isTTY: boolean };
-  stderr: import("stream").Writable & { isTTY: boolean };
+  stdin: import("tty").ReadStream;
+  stdout: import("tty").WriteStream;
+  stderr: import("tty").WriteStream;
 
   /**
    *
@@ -739,11 +739,10 @@ interface BlobInterface {
 
 type BlobPart = string | Blob | BufferSource;
 interface BlobPropertyBag {
-  /** Set a default "type" */
-  type?: string;
-
+  /** Set a default "type". Not yet implemented. */
+  // type?: string;
   /** Not implemented in Bun yet. */
-  endings?: "transparent" | "native";
+  // endings?: "transparent" | "native";
 }
 
 /**