{"action":"opened","issue":{"url":"https://api.github.com/repos/js-reporters/js-reporters/issues/106","repository_url":"https://api.github.com/repos/js-reporters/js-reporters","labels_url":"https://api.github.com/repos/js-reporters/js-reporters/issues/106/labels{/name}","comments_url":"https://api.github.com/repos/js-reporters/js-reporters/issues/106/comments","events_url":"https://api.github.com/repos/js-reporters/js-reporters/issues/106/events","html_url":"https://github.com/js-reporters/js-reporters/issues/106","id":283036012,"number":106,"title":"Consider `diff` property on assertion object","user":{"login":"keithamus","id":118266,"avatar_url":"https://avatars3.githubusercontent.com/u/118266?v=4","gravatar_id":"","url":"https://api.github.com/users/keithamus","html_url":"https://github.com/keithamus","followers_url":"https://api.github.com/users/keithamus/followers","following_url":"https://api.github.com/users/keithamus/following{/other_user}","gists_url":"https://api.github.com/users/keithamus/gists{/gist_id}","starred_url":"https://api.github.com/users/keithamus/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/keithamus/subscriptions","organizations_url":"https://api.github.com/users/keithamus/orgs","repos_url":"https://api.github.com/users/keithamus/repos","events_url":"https://api.github.com/users/keithamus/events{/privacy}","received_events_url":"https://api.github.com/users/keithamus/received_events","type":"User","site_admin":true},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2017-12-18T22:03:50Z","updated_at":"2017-12-18T22:03:50Z","closed_at":null,"author_association":"NONE","body":"While it is generally well considered to have the `expected` and `actual` objects attached to the assertion object. They're useful because they allow reporters to print some kind of pretty-formatted diff to allow the developer to more easily reason about the failures in a test. I believe there should be a specced out (but optional) `diff` property also on the assertion object which can be used to make _better diffs_ for the user to read.\r\n\r\nOften times the assertion object is the best place to generate the diff, in a standardised format (perhaps Diff notation?), because it has the highest fidelity level of reasing about the two objects - much better than just passing `expected` and `actual`. There are sevaral concrete reasonings for this, I'll give a few examples:\r\n\r\nExample 1. The assertion object was generated, but serialised to JSON. before being passed to an upstream reporter. This loses out on all object information in the `expected` and `actual`. Dates become strings, Maps/Sets lose their values and classes become POJOs. All hope of getting meaningful information is lost from `expected` and `actual`. If the assertion object managed to generate a diff though, this has high fidelity usable info.\r\n\r\nExample 2. A more subtle variant of the above problem: objects are passed cross-realm, say for example the test runner runs inside of a worker. Now, without doing heaps of additional work, the test runner cannot safely reason about the types of objects that `actual` and `expected` are. Brand checks fail cross-realm (tools like `Array.isArray` fix this, shame we don't have the matching set for all types). A string diff doesn't care about this though, it is, after all, just a string.\r\n\r\nThose just really enumerate the problems with `actual` and `expected`. But below are my reasons for _why_ diff would be a much better addition in the assertion object:\r\n\r\nReason 1. The assertion object already generated a message. The likelyhood is this message has inspected and serialised the `actual` and `expected` properties in some way (for e.g. saying `expected \"foo\" to equal \"bar\"`). We can therefore assert that the assertion object has a mechanism for pretty-printing objects. It is likely that the best place to add pretty-printing with diffs, is therefore, in the same formatting library the assertion functions already consume. I know this to be the case for chai, I assume it to be right for others.\r\n\r\nReason 2. The assertion call itself knows about the intent behind the assertion more than the object can hint at. It is reasonably easy to imagine up an assertion where the `expected` and `actual` properties are like-for-like, but the assertion is failing for other means. For example `expect({foo: 1}).to.have.non.enumerable.property('foo', 1)`. The assertion here knows that the user is expecting the given object to have a _non enumerable_ property `foo` equal to `1`. The problem is, it will fail the assertion with an object that has the  `expected` property as `1` and the `actual` property as `1` - so both equal from the perspective of the reporter. An alternative for the assertion object could be to provide the property descriptors as `expected` and `actual` properties - but this could confuse things further (what if they pass that assertion but differ because the object has a getter). The only way for the assertion object to reasonably inform the user of the subtle failure is with the `message` property - or - a more explicit `diff` property which could provide a higher fidelity output than a message, but still cross the boundary to the reporter without losing fidelity.\r\n\r\n---\r\n\r\nSome additional notes: I think a Diff format would be the best representation of this property, as by default, without syntax highlighting, a developer could reasonably be expected to read it and understand it. But it also provides a standard way for reporters to consume it and display it in other ways. For example an HTML reporter could display it as a side-by-side table, using CSS to colorise parts of it, while a terminal can use ANSI escape codes to format the diff."}}
{"actor":{"display_login":"keithamus"}}