Do you want to work on this issue?
You can request for a bounty in order to promote it!
Snapshot report descriptions #3071
panoply posted onGitHub
Description
Firstly, thank you for creating and maintaining this brilliant tool. I leverage AVA's snapshot feature for comparing responses generated from parsers/lexers and it would be nice if I could feed descriptions of the snapshot test into reports to help better understand what is going in and what I am testing etc.
Currently and AFAIK ava provides this functionality as "labels" when passing a string to the 2nd parameter in the .snapshot()
method which will write to the quoted >
output, eg:
test('Some example test name', t => {
const source = '<div>Hello World</div>';
t.snapshot(source, 'Testing hello world');
})
The above example will output the following in a markdown file:
# Snapshot report for `tests/eg.test.mjs`
The actual snapshot is saved in `eg.mjs.snap`.
Generated by [AVA](https://avajs.dev).
## Some example test name
> Testing hello world
'<div>Hello World</div>'
While this suffices for a lot of cases, it does not allow for me (and maybe others) to have clear understanding on the purpose of the test and it becomes exceptionally difficult when reviewing snap reports. The current label and test title (even when multi-line) are not enough. Below is an example to better visualize what I mean.
Notice the generate snapshot reports include a description following the test title:
# Snapshot report for `tests/eg.test.mjs`
The actual snapshot is saved in `eg.mjs.snap`.
Generated by [AVA](https://avajs.dev).
## Some example test name
An example of where the description should be output.
> Testing hello world (snapshot 1)
'<div>Hello World</div>'
> Testing something else (snapshot 2)
'<div>etc etc etc</div>'
> Testing some else (snapshot 3)
'xxx xxx xxx xxx'
In the above, a description of the test is applied to the report. Passing markdown descriptions would be ideal but simple multiline strings would also suffice too.
Why you can't use AVA for this
There is no way to apply this (AFAIK) in reports.
And maybe how you think AVA could handle this
Personally, I haven't looked at the overall implementation approach one might employ to support such a capability and I am unsure of how ava is handling this aspect internally. Ideally and given the feature request pertains to snapshot assertions, exposing a description
or describe
to the t.snapshot
method seems elegant and non-intrusive (ie: t.snapshot.describe()
). IIRC I once read an issue where someone proposed something similar to be applied on the label parameter but that feels a tad extraneous.
To better demonstrate, see the below example:
_In this I am assuming the following type:
t.snapshot.describe(...description: string[])
and also passing some markdown, grain of salt that aspect.
test('Some example test name', t => {
// ...
t.snapshot.describe(
'The snapshot report description can be provided here.',
'The `describe` method similar to `t.log` could accept spread argument and',
'maybe some low level **markdown** could be accepted if it does not interfere',
'with the existing logic, for example:',
'- List item 1',
'- List item 2'
'etc etc',
)
t.snapshot(source, 'The snapshot label');
})
The resulting report would be:
# Snapshot report for `tests/eg.test.mjs`
The actual snapshot is saved in `eg.mjs.snap`.
Generated by [AVA](https://avajs.dev).
## Some example test name
The snapshot report description can be provided here. The `describe` method similar to `t.log` could accept spread argument and maybe some low level **markdown** could be accepted if it does not interfere with the existing logic, for example:
- List item 1
- List item 2
etc etc
> The snapshot label
'xxx xxx xxx xxx'