Snapshot report descriptions
- Dominant language
- JavaScript
- Stars
- 20.8k
- Forks
- 1.5k
- PR merge metrics
- No merged PRs in 30d
Description
## 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:
```js
test('Some example test name', t => {
const source = '
t.snapshot(source, 'Testing hello world');
})
```
The above example will output the following in a markdown file:
```md
# 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
'
```
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:
```markdown
# 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)
'
> Testing something else (snapshot 2)
'
> 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.
```js
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:
```markdown
# 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'
```
Contributor guide
Research direction
The issue identifies t.snapshot() and generated snapshot reports as the relevant entry points, but no source files or tests are named. Start by tracing how snapshot labels reach the report output and determine how descriptions would be stored and rendered. Done would require an agreed API and report behavior, including multiline or Markdown descriptions, with coverage for the resulting output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100