Skip to content
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

Jump to bottom

feat: Add the assert.fail([message]) interface #1117

Merged
merged 1 commit into from Jan 12, 2018
Merged

feat: Add the assert.fail([message]) interface #1117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
15 changes: 15 additions & 0 deletions lib/chai/interface/assert.js
View file
Open in desktop
Expand Up @@ -41,10 +41,18 @@ module.exports = function (chai, util) {
};

/**
* ### .fail([message])
* ### .fail(actual, expected, [message], [operator])
Copy link
Contributor

Choose a reason for hiding this comment

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

@chaijs/chai Anyone know how the website generation script handles listing multiple function signatures in this way? Or the proper way to do this with jsdoc in general? I struggled with this problem quite a bit in chaijs/check-error#18, and ended up including a single function signature at the top (with optional parameters) but documenting the alternate signatures in the jsdoc body. Not sure what the best approach is.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

There is a possible solution for handling multiple function signature used in the assert.throws documentation. But I'm not sure this is the proper way of doing though: as a user, this is only by looking at the example section I was able to understand the various signatures for that method.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

FWIW, I passed the source code through dox (which I assume to be the jsdoc parser used for the website). Here is the relevant part of the output:

"description": {
  "full": "<h3>.fail([message])</h3>\n<h3>.fail(actual, expected, [message], [operator])</h3>\n<p>Throw a failure.</p>",
  "summary": "<h3>.fail([message])</h3>\n<h3>.fail(actual, expected, [message], [operator])</h3>",
  "body": "<p>Throw a failure.</p>"
},

As you can see, it produces two <h3> elements--once for each signature. Which seems quite reasonnable. Maybe we could ping someone at the chai-doc team to check if this is an issue?

Copy link
Contributor

Choose a reason for hiding this comment

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

Yup, chai-docs is using dox. That behavior looks promising. @astorije might know for sure.

*
* Throw a failure. Node.js `assert` module-compatible.
*
* assert.fail();
* assert.fail("custom error message");
* assert.fail(1, 2);
* assert.fail(1, 2, "custom error message");
* assert.fail(1, 2, "custom error message", ">");
* assert.fail(1, 2, undefined, ">");
*
* @name fail
* @param {Mixed} actual
* @param {Mixed} expected
Expand All @@ -55,6 +63,13 @@ module.exports = function (chai, util) {
*/

assert.fail = function (actual, expected, message, operator) {
if (arguments.length < 2) {
// Comply with Node's fail([message]) interface

message = actual;
actual = undefined;
}

message = message || 'assert.fail()';
throw new chai.AssertionError(message, {
actual: actual
Expand Down
13 changes: 13 additions & 0 deletions lib/chai/interface/expect.js
View file
Open in desktop
Expand Up @@ -10,10 +10,18 @@ module.exports = function (chai, util) {
};

/**
* ### .fail([message])
* ### .fail(actual, expected, [message], [operator])
Copy link
Contributor

Choose a reason for hiding this comment

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

Same question here regarding function signatures.

*
* Throw a failure.
*
* expect.fail();
* expect.fail("custom error message");
* expect.fail(1, 2);
* expect.fail(1, 2, "custom error message");
* expect.fail(1, 2, "custom error message", ">");
* expect.fail(1, 2, undefined, ">");
*
* @name fail
* @param {Mixed} actual
* @param {Mixed} expected
Expand All @@ -24,6 +32,11 @@ module.exports = function (chai, util) {
*/

chai.expect.fail = function (actual, expected, message, operator) {
if (arguments.length < 2) {
message = actual;
actual = undefined;
}

message = message || 'expect.fail()';
throw new chai.AssertionError(message, {
actual: actual
Expand Down
14 changes: 14 additions & 0 deletions lib/chai/interface/should.js
View file
Open in desktop
Expand Up @@ -42,10 +42,19 @@ module.exports = function (chai, util) {
var should = {};

/**
* ### .fail([message])
* ### .fail(actual, expected, [message], [operator])
Copy link
Contributor

Choose a reason for hiding this comment

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

Same question here regarding function signatures.

*
* Throw a failure.
*
* should.fail();
* should.fail("custom error message");
* should.fail(1, 2);
* should.fail(1, 2, "custom error message");
* should.fail(1, 2, "custom error message", ">");
* should.fail(1, 2, undefined, ">");
*
*
* @name fail
* @param {Mixed} actual
* @param {Mixed} expected
Expand All @@ -56,6 +65,11 @@ module.exports = function (chai, util) {
*/

should.fail = function (actual, expected, message, operator) {
if (arguments.length < 2) {
message = actual;
actual = undefined;
}

message = message || 'should.fail()';
throw new chai.AssertionError(message, {
actual: actual
Expand Down
22 changes: 18 additions & 4 deletions test/assert.js
View file
Open in desktop
Expand Up @@ -14,10 +14,24 @@ describe('assert', function () {
}, "expected foo to equal `bar`");
});

it('fail', function () {
chai.expect(function () {
assert.fail(0, 1, 'this has failed');
}).to.throw(chai.AssertionError, /this has failed/);
describe("fail", function() {
it('should accept a message as the 3rd argument', function () {
err(function() {
assert.fail(0, 1, 'this has failed');
}, /this has failed/);
});

it('should accept a message as the only argument', function () {
err(function() {
assert.fail('this has failed');
}, /this has failed/);
});

it('should produce a default message when called without any arguments', function () {
err(function() {
assert.fail();
}, /assert\.fail()/);
});
});

it('isTrue', function () {
Expand Down
22 changes: 18 additions & 4 deletions test/expect.js
View file
Open in desktop
Expand Up @@ -236,10 +236,24 @@ describe('expect', function () {
, 'of', 'same', 'but', 'does' ].forEach(test);
});

it('fail', function () {
err(function() {
expect.fail(0, 1, 'this has failed');
}, /this has failed/);
describe("fail", function() {
it('should accept a message as the 3rd argument', function () {
err(function() {
expect.fail(0, 1, 'this has failed');
}, /this has failed/);
});

it('should accept a message as the only argument', function () {
err(function() {
expect.fail('this has failed');
}, /this has failed/);
});

it('should produce a default message when called without any arguments', function () {
err(function() {
expect.fail();
}, /expect\.fail()/);
});
});

it('true', function(){
Expand Down
22 changes: 18 additions & 4 deletions test/should.js
View file
Open in desktop
Expand Up @@ -233,10 +233,24 @@ describe('should', function() {
, 'of', 'same', 'but', 'does' ].forEach(test);
});

it('fail', function () {
err(function() {
should.fail(0, 1, 'this has failed');
}, 'this has failed');
describe("fail", function() {
it('should accept a message as the 3rd argument', function () {
err(function() {
should.fail(0, 1, 'this has failed');
}, /this has failed/);
});

it('should accept a message as the only argument', function () {
err(function() {
should.fail('this has failed');
}, /this has failed/);
});

it('should produce a default message when called without any arguments', function () {
err(function() {
should.fail();
}, /should\.fail()/);
});
});

it('root exist', function () {
Expand Down