Skip to content

docs: stronger suggestion for userland assert #4535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

docs: stronger suggestion for userland assert #4535

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ed29a58
docs: stronger suggestion for userland assert
geek Jan 5, 2016
07d5d48
Update assert.markdown
geek Jan 5, 2016
e6da014
Used wording from @cjihrig
geek Jan 5, 2016
581a3b1
With feedback from @jasnell
geek Jan 6, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions doc/api/assert.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,10 @@
Stability: 3 - Locked

The `assert` module provides a simple set of assertion tests that can be used
to test invariants and implement unit tests. While the `assert` module is
generally intended for internal use by Node.js itself, it can be used by user
code calling `require('assert')`.
to test invariants and implement unit tests. It is recommended that users of
Node.js choose a third party assertion library from [npm][] instead of relying
on `assert`. That being said, `assert` can be used by user code calling
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mikeal This statement should not be this strong. There is no commonly npm package in existence for asserting _invariants_ in source. At least, not that I know of, can you point to one?

I suggest we make clear that assert is NOT for unit tests, and not point people to non-existent modules for the use-case that assert is a good tool for (invariants).

The assert module provides a simple set of assertion tests that can be used
to test invariants. While the assert module is generally intended for internal use by Node.js itself, it can be used by user code calling require('assert'). For the purposes of unit testing, it is recommended that users of Node.js choose a third party test library from [npm][] instead of relying on assert.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I see, searching for assert on npmjs.org gets you pages of results, none of which are useful to replace assert for invariants, and none of which are a unit test framework (which is probably what the reader wanted).

The usage of assert we want to warn people away from is using it as a unit testing library, such as mocha, tap, and nunit, and none of those are even in the first page of search results when using npmjs.org search.

Of course, I can't find a search term (other than "mocha") that yields mocha in the first page. :-( This is likely because npmjs.org search is unranked, so not so helpful, googling for node test framework works better.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sam-github I'm a bit confused by your comments and feel that I must be misunderstanding something, so perhaps you could help me understand by rephrasing?

This statement should not be this strong. There is no commonly npm package in existence for asserting _invariants_ in source. At least, not that I know of, can you point to one?
...
OK, I see, searching for assert on npmjs.org gets you pages of results, none of which are useful to replace assert for invariants

Isn't assert, for example, pretty much the same thing? That's the first result I get when I search assert.

FWIW, there's also invariant which is dead simple (basically just like assert()).

and none of which are a unit test framework (which is probably what the reader wanted).

The usage of assert we want to warn people away from is using it as a unit testing library, such as mocha, tap, and nunit,

Do people somehow confuse the assert module as being a testing framework or library? Or do you mean it shouldn't be used for assertions in userland tests period? I think it's fairly commonly used for assertions within a framework like Mocha.

`require('assert')`.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nit... I'd like to avoid starting sentences with a lower-cased module name, especially two sentences in a row... Perhaps reword the las two sentences to:

The module is intended for internal use by Node.js, but can be used in application 
code via `require('assert')`. However, `assert` is not a testing framework, and is not 
intended to be used as a general purpose assertion library.

The API for the `assert` module is [Locked][]. This means that there will be no
additions or changes to any of the methods implemented and exposed by
Expand Down Expand Up @@ -357,6 +358,7 @@ Custom error validation:
);

[Locked]: documentation.html#documentation_stability_index
[npm]: https://www.npmjs.com/search?q=assertion+library
[`assert.deepEqual`]: #assert_assert_deepequal_actual_expected_message
[`assert.deepStrictEqual`]: #assert_assert_deepstrictequal_actual_expected_message
[`assert.throws()`]: #assert_assert_throws_block_error_message
Expand Down