From e41bbb33bc4b1d4bab6cd799bfdaaf8fc98fdc83 Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Tue, 16 Jul 2024 16:08:37 +0100 Subject: [PATCH] Docs: Improve browser runner docs Move "Test results explained" and failure example higher up on the page. Mention "devtools". Change failure example to include two passings to be more realistic. Change failure example to have 3 passing assertions. Previously: > - test name (1,2,3) > 1. a > 2. [fail] b > 3. c Now: > - test name (1,3,4) > 1. a > 2. [fail] b > 3. c > 4. d The "1,2,3" count was imho non-obvious in meaning. While the meaning is explained in prose, with 4 assertions it is much more intuitive to identify that there is 1 failure, 3 passing, and 4 in total. --- docs/browser.md | 36 ++++++++++++++++++-------------- docs/resources/example-fail.html | 11 +++++++++- 2 files changed, 30 insertions(+), 17 deletions(-) diff --git a/docs/browser.md b/docs/browser.md index 414b1d2c5..94bfcc884 100644 --- a/docs/browser.md +++ b/docs/browser.md @@ -146,39 +146,43 @@ The header of the report displays: [Check for globals](./api/config/noglobals.md) detects if a test creates or removes global variable is. QUnit keeps a list of properties found on the `window` object. If properties were added or removed, the test fails. -[No try-catch](./api/config/notrycatch.md) instructs QUnit to run your tests without a try-catch block. In this mode, if your test throws an error it will interrupt QUnit, which may ease debugging. +[No try-catch](./api/config/notrycatch.md) instructs QUnit to run your tests without a try-catch block. In this mode, if your test throws an error it will interrupt QUnit, which may ease debugging with browser devtools. You can extend the toolbar via [QUnit.config.urlConfig](./api/config/urlConfig.md). -### Filter +### Test results explained -Enter a search phrase to re-run only tests that match the phrase. It performs a case-insensitive substring match by default, on both the module name and test name. You can use regular expressions, and/or invert the match to exclude tests instead. +Each result is displayed in a numbered list. -Find examples and learn more at [QUnit.config.filter](./api/config/filter.md). +> **MyApp: example** (3) _Rerun_ -### Module selector +After the name of the module and test, in parentheses, is the total number of assertions. -To quickly re-run one or more modules of tests, select them from the module selector and press "Apply". +The "Rerun" link at the end will reload the page and quickly run the test again in isolation, skipping all other tests. -You can use the input field to quickly find a module, even if you have many modules. The input field performs [fuzzy matching](https://github.com/farzher/fuzzysort), so don't worry about getting it exactly right! `baor game` and `boar dame` finds "board game". This is similar to how "Quick Open" works in modern text editors. +Click on the test name to expand the entry, which reveals the message of each assertion. -When selecting a parent module, which contains [nested modules](./api/QUnit/module.md), the nested modules and their tests will also be run. +For failed assertions: +* The parenthetical reports the "failed, passed, and total" number of assertions. +* The expanded view displays the expected and actual asserted value, with a diff to highlight the difference between the two values. +* The source where the failing assertion is performed. The stack trace indicates the test file path and line number. +* The source where the test is defined. -### Test results + -Each result is displayed in a numbered list. +### Filter -> **MyApp: example** (3) _Rerun_ +Enter a search phrase to re-run only tests that match the phrase. It performs a case-insensitive substring match by default, on both the module name and test name. You can use regular expressions, and/or invert the match to exclude tests instead. -After the name of the module and test, in parentheses, is the total number of assertions. +Find examples and learn more at [QUnit.config.filter](./api/config/filter.md). -The "Rerun" link at the end will run that test on its own, skipping all other tests. +### Module selector -Click anywhere on result to expand the entry, which reveals the message of each assertion. +To quickly re-run one or more modules of tests, select them from the module selector and press "Apply". -For failed assertions, the parenthetical reports the failed, passed, and total number of assertions. The expanded view also displays the expected and actual asserted value, with a diff to highlight the difference between the two values. +You can use the input field to quickly find a module, even if you have many modules. The input field performs [fuzzy matching](https://github.com/farzher/fuzzysort), so don't worry about getting it exactly right! For example, typing `bor game` or `abGame` will find `awesome board games`. This is similar to how "Quick Open" works in modern text editors. - +When selecting a parent module, which contains [nested modules](./api/QUnit/module.md), the nested modules and their tests will also be run. ### Theme API diff --git a/docs/resources/example-fail.html b/docs/resources/example-fail.html index 512cd2682..88e5d7004 100644 --- a/docs/resources/example-fail.html +++ b/docs/resources/example-fail.html @@ -8,10 +8,19 @@