rspec/rules/S3415/javascript/rule.adoc

== Why is this an issue?

Assertions are statements that check whether certain conditions are true. They are used to validate that the actual results of a code snippet match the expected outcomes. By using assertions, developers can ensure that their code behaves as intended and identify potential bugs or issues early in the development process.

The convention for passing assertion arguments is to pass the expected value as the first argument and the actual value as the second argument. This convention is based on the idea that the expected value is what the code is supposed to produce, and the actual value is what the code actually produces. By passing the expected value first, it is easier to understand the intent of the assertion and to quickly identify any errors that may be present. Additionally, many testing frameworks and libraries expect assertion arguments to be passed in this order, so following the convention can help ensure that your code works correctly with these tools.

This rule raises an issue when the "expected" argument of an assertion function is a hard-coded value and the "actual" argument is not.

[source,javascript,diff-id=1,diff-type=noncompliant]
----
const assert = require('chai').assert;
const expect = require('chai').expect;
const should = require('chai').should();

it("inverts arguments", function() {
    assert.equal(42, aNumber); // Noncompliant: actual value is passed as first argument and expected as second argument
    expect(42).to.equal(aNumber); // Noncompliant: actual value is passed as first argument and expected as second argument
    should.fail(42, aNumber);  // Noncompliant: actual value is passed as first argument and expected as second argument
});
----

Swap the order of the assertion arguments so that the expected value is passed as the first argument and the actual value is passed as the second argument.

[source,javascript,diff-id=1,diff-type=compliant]
----
const assert = require('chai').assert;
const expect = require('chai').expect;
const should = require('chai').should();

it("inverts arguments", function() {
    assert.equal(aNumber, 42);
    expect(aNumber).to.equal(42);
    should.fail(aNumber, 42); 
});
----

== Resources
=== Documentation

* https://nodejs.org/api/assert.html[Node.js API - Assert]
* https://www.chaijs.com/api/assert[Chai.js - Assert]
* https://www.chaijs.com/api/bdd[Chai.js - `expect` and `should`]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

If a Chai function gets actual and expected values as arguments:

* Swap these 2 arguments so they are in the correct order: actual value, expected value.
If expect(actual).someMethod(expected) is used:

* Swap this argument with the one given to "expect".


=== Highlighting

If a Chai function gets actual and expected values as arguments:

* Primary: second argument to swap
* Secondary: first argument to swap
** message: 'Other argument to swap.'

If expect(actual).someMethod(expected) is used:

* Primary: The argument of the assertion function (ex: "equal")
* Secondary: The argument given to "expect"
** no message


'''
== Comments And Links
(visible only on this page)

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]