vitest-dev / vitest-dev/vitest

docs: Document `Assertion<T>` methods from `chai`

Open
#9,709 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement: pending triage
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
Image

TS Playground repro

Validations

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.