vitest-dev / vitest-dev/vitest
docs: Document `Assertion<T>` methods from `chai`
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 17.1k
- Forks
- 2k
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 94
Description
Clear and concise description of the problem
For some reason, all of the expect() methods from chai are undocumented inside IDEs, despite those from Jest having fairly polished docs themselves inside JestAssertion.
This is notable since expects are one of the 2 ways to check things inside tests (along assert, and having half of your API be significantly less polished than the other is less than ideal.
Admittedly, this would effectively require writing an entire separate interface for chai's assertions similar to JestAssertion, but given we actively copy the doc comments from Jest, I don't see why doing the same for chai is an issue.
Suggested solution
Add descriptive doc comments to fill in the documetation hole and make the experience polished regardless of which package's API you choose to interface with.
These could primarily be taken from chai's website, with edits to ensure a consistent format and style with those from Jest (if needed).
.not should be among those that get special treatment, given it is used by both Jest and Chai (and should ideally have examples for both).
Alternative
Don't document it, forcing downstream consumers to have worse DX.
Yes, consumers that really care can use TypeScript declaration merging to plaster doc comments on, but that's effectively writing documentation comments for an external package. Providing it in-house would result in greater benefit for relatively little cost.
Additional context
Validations
- Follow our Code of Conduct
- Read the Contributing Guidelines.
- Read the docs.
- Check that there isn't already an issue that request the same feature to avoid creating a duplicate.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the TypeScript definitions for Assertion and comparing their existing comments with JestAssertion. Use Chai's website and the linked TypeScript Playground reproduction to identify the undocumented methods, including .not. Done means the Chai assertion API has consistent IDE-visible documentation and examples where appropriate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation, testing
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100