You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

162 lines
4.7 KiB

  1. # assert-plus
  2. This library is a super small wrapper over node's assert module that has two
  3. things: (1) the ability to disable assertions with the environment variable
  4. NODE\_NDEBUG, and (2) some API wrappers for argument testing. Like
  5. `assert.string(myArg, 'myArg')`. As a simple example, most of my code looks
  6. like this:
  7. ```javascript
  8. var assert = require('assert-plus');
  9. function fooAccount(options, callback) {
  10. assert.object(options, 'options');
  11. assert.number(options.id, 'options.id');
  12. assert.bool(options.isManager, 'options.isManager');
  13. assert.string(options.name, 'options.name');
  14. assert.arrayOfString(options.email, 'options.email');
  15. assert.func(callback, 'callback');
  16. // Do stuff
  17. callback(null, {});
  18. }
  19. ```
  20. # API
  21. All methods that *aren't* part of node's core assert API are simply assumed to
  22. take an argument, and then a string 'name' that's not a message; `AssertionError`
  23. will be thrown if the assertion fails with a message like:
  24. AssertionError: foo (string) is required
  25. at test (/home/mark/work/foo/foo.js:3:9)
  26. at Object.<anonymous> (/home/mark/work/foo/foo.js:15:1)
  27. at Module._compile (module.js:446:26)
  28. at Object..js (module.js:464:10)
  29. at Module.load (module.js:353:31)
  30. at Function._load (module.js:311:12)
  31. at Array.0 (module.js:484:10)
  32. at EventEmitter._tickCallback (node.js:190:38)
  33. from:
  34. ```javascript
  35. function test(foo) {
  36. assert.string(foo, 'foo');
  37. }
  38. ```
  39. There you go. You can check that arrays are of a homogeneous type with `Arrayof$Type`:
  40. ```javascript
  41. function test(foo) {
  42. assert.arrayOfString(foo, 'foo');
  43. }
  44. ```
  45. You can assert IFF an argument is not `undefined` (i.e., an optional arg):
  46. ```javascript
  47. assert.optionalString(foo, 'foo');
  48. ```
  49. Lastly, you can opt-out of assertion checking altogether by setting the
  50. environment variable `NODE_NDEBUG=1`. This is pseudo-useful if you have
  51. lots of assertions, and don't want to pay `typeof ()` taxes to v8 in
  52. production. Be advised: The standard functions re-exported from `assert` are
  53. also disabled in assert-plus if NDEBUG is specified. Using them directly from
  54. the `assert` module avoids this behavior.
  55. The complete list of APIs is:
  56. * assert.array
  57. * assert.bool
  58. * assert.buffer
  59. * assert.func
  60. * assert.number
  61. * assert.finite
  62. * assert.object
  63. * assert.string
  64. * assert.stream
  65. * assert.date
  66. * assert.regexp
  67. * assert.uuid
  68. * assert.arrayOfArray
  69. * assert.arrayOfBool
  70. * assert.arrayOfBuffer
  71. * assert.arrayOfFunc
  72. * assert.arrayOfNumber
  73. * assert.arrayOfFinite
  74. * assert.arrayOfObject
  75. * assert.arrayOfString
  76. * assert.arrayOfStream
  77. * assert.arrayOfDate
  78. * assert.arrayOfRegexp
  79. * assert.arrayOfUuid
  80. * assert.optionalArray
  81. * assert.optionalBool
  82. * assert.optionalBuffer
  83. * assert.optionalFunc
  84. * assert.optionalNumber
  85. * assert.optionalFinite
  86. * assert.optionalObject
  87. * assert.optionalString
  88. * assert.optionalStream
  89. * assert.optionalDate
  90. * assert.optionalRegexp
  91. * assert.optionalUuid
  92. * assert.optionalArrayOfArray
  93. * assert.optionalArrayOfBool
  94. * assert.optionalArrayOfBuffer
  95. * assert.optionalArrayOfFunc
  96. * assert.optionalArrayOfNumber
  97. * assert.optionalArrayOfFinite
  98. * assert.optionalArrayOfObject
  99. * assert.optionalArrayOfString
  100. * assert.optionalArrayOfStream
  101. * assert.optionalArrayOfDate
  102. * assert.optionalArrayOfRegexp
  103. * assert.optionalArrayOfUuid
  104. * assert.AssertionError
  105. * assert.fail
  106. * assert.ok
  107. * assert.equal
  108. * assert.notEqual
  109. * assert.deepEqual
  110. * assert.notDeepEqual
  111. * assert.strictEqual
  112. * assert.notStrictEqual
  113. * assert.throws
  114. * assert.doesNotThrow
  115. * assert.ifError
  116. # Installation
  117. npm install assert-plus
  118. ## License
  119. The MIT License (MIT)
  120. Copyright (c) 2012 Mark Cavage
  121. Permission is hereby granted, free of charge, to any person obtaining a copy of
  122. this software and associated documentation files (the "Software"), to deal in
  123. the Software without restriction, including without limitation the rights to
  124. use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  125. the Software, and to permit persons to whom the Software is furnished to do so,
  126. subject to the following conditions:
  127. The above copyright notice and this permission notice shall be included in all
  128. copies or substantial portions of the Software.
  129. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  130. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  131. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  132. AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  133. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  134. OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  135. SOFTWARE.
  136. ## Bugs
  137. See <https://github.com/mcavage/node-assert-plus/issues>.