Fix docs on todo tests (#15233)

docs/guides/test/todo-tests.md

@@ -44,10 +44,17 @@ test.todo("unimplemented feature", () => {
 
 ---
 
-If an implementation is provided, it will be executed and _expected to fail_ by test runner! If a todo test passes, the `bun test` run will return a non-zero exit code to signal the failure.
+If an implementation is provided, it will not be run unless the `--todo` flag is passed. If the `--todo` flag is passed, the test will be executed and _expected to fail_ by test runner! If a todo test passes, the `bun test` run will return a non-zero exit code to signal the failure.
 
 ```sh
-$ bun test
+$ bun test --todo
+my.test.ts:
+✗ unimplemented feature
+  ^ this test is marked as todo but passes. Remove `.todo` or check that test is correct.
+
+ 0 pass
+ 1 fail
+ 1 expect() calls
 $ echo $?
 1 # this is the exit code of the previous command
 ```

docs/test/writing.md

@@ -97,7 +97,7 @@ test.skip("wat", () => {
 
 ## `test.todo`
 
-Mark a test as a todo with `test.todo`. These tests _will_ be run, and the test runner will expect them to fail. If they pass, you will be prompted to mark it as a regular test.
+Mark a test as a todo with `test.todo`. These tests will not be run.
 
 ```ts
 import { expect, test } from "bun:test";
@@ -107,12 +107,22 @@ test.todo("fix this", () => {
 });
 ```
 
-To exclusively run tests marked as _todo_, use `bun test --todo`.
+To run todo tests and find any which are passing, use `bun test --todo`.
 
 ```sh
 $ bun test --todo
+my.test.ts:
+✗ unimplemented feature
+  ^ this test is marked as todo but passes. Remove `.todo` or check that test is correct.
+
+ 0 pass
+ 1 fail
+ 1 expect() calls
 ```
 
+With this flag, failing todo tests will not cause an error, but todo tests which pass will be marked as failing so you can remove the todo mark or
+fix the test.
+
 ## `test.only`
 
 To run a particular test or suite of tests use `test.only()` or `describe.only()`. Once declared, running `bun test --only` will only execute tests/suites that have been marked with `.only()`. Running `bun test` without the `--only` option with `test.only()` declared will result in all tests in the given suite being executed _up to_ the test with `.only()`. `describe.only()` functions the same in both execution scenarios.

packages/bun-types/test.d.ts

@@ -387,9 +387,9 @@ declare module "bun:test" {
     /**
      * Marks this test as to be written or to be fixed.
      *
-     * When a test function is passed, it will be marked as `todo` in the test results
-     * as long the test does not pass. When the test passes, the test will be marked as
-     * `fail` in the results; you will have to remove the `.todo` or check that your test
+     * These tests will not be executed unless the `--todo` flag is passed. With the flag,
+     * if the test passes, the test will be marked as `fail` in the results; you will have to
+     * remove the `.todo` or check that your test
      * is implemented correctly.
      *
      * @param label the label for the test