Skip to content

Commit

Permalink
Docs: Improve browser runner docs
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
Krinkle committed Jul 16, 2024
1 parent 580d94f commit e41bbb3
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 17 deletions.
36 changes: 20 additions & 16 deletions docs/browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<iframe loading="lazy" title="Example failure" src="/resources/example-fail.html" style="height: 600px;"></iframe>

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.

<iframe loading="lazy" title="Example failure" src="/resources/example-fail.html" style="height: 500px;"></iframe>
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

Expand Down
11 changes: 10 additions & 1 deletion docs/resources/example-fail.html
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,19 @@
<div id="qunit-fixture"></div>
<script src="https://code.jquery.com/qunit/qunit-2.21.0.js"></script>
<script>
QUnit.test('example', function (assert) {
QUnit.test('apple', function (assert) {
assert.equal('this is expected', 'this is expected', 'example');
assert.true(true);
});
QUnit.test('banana', function (assert) {
assert.true(true, 'foo');
assert.equal('this is actual', 'this is expected', 'bar');
assert.true(true, 'baz');
assert.true(true, 'quux');
});
QUnit.test('citron', function (assert) {
assert.equal('this is expected', 'this is expected', 'example');
assert.true(true);
});
</script>
</body>
Expand Down

0 comments on commit e41bbb3

Please sign in to comment.