vitest-dev / vscode

VS Code extension for Vitest
https://vitest.dev/vscode
MIT License
736 stars 83 forks source link

Update README #338

Open sheremet-va opened 4 months ago

sheremet-va commented 4 months ago

Clear and concise description of the problem

Our current README doesn't provide enough information on how to work with the extension.

Suggested solution

Add several new sections:

I would also like to rewrite the introduction section:

It should look something like this:

# Vitest for VS Code

<!-- short description about what this is -->
<!-- table of content -->
<!-- small promo image showing a test file -->

## Requirements

<!-- list of requirements -->

## Feature 1
## Feature 2
...

All screenshots need to use the same project that should be pushed to the repository so we can reshoot it if needed. All screenshots need to have the same VS Code theme. Ideally, screenshots should have a border with a shadow (like on Mac OS) - this is just my preference 😄

Alternative

No response

Additional context

No response

Validations

MilanKovacic commented 4 months ago

In my opinion, since consumers of the extension are developers, there isn't a need to go into so much detail to create new sections for simple things like running a test, or things developers are already familiar with (such as managing breakpoints). Consumers should also not be bothered with the internals of how the vitest extension itself works (when/why it runs vitest in collect mode, starting vitest processes, etc).

I believe the current format can be extended to further explain certain things such as test filters, better way to display the configuration. I agree with the GIF update, and the removal of logo.

sheremet-va commented 4 months ago

In my opinion, since consumers of the extension are developers, there isn't a need to go into so much detail to create new sections for simple things like running a test, or things developers are already familiar with

There a lot of developers who don't have enough knowledge to even install Vitest. Explaining how breakpoints work or how to navigate through the interface will go a long way in helping junior developers work with the extension efficiently. There are a lot of nuances to how tests are displayed (tree view, file view, "test results" tab, switching between different test runs and so on)

Consumers should also not be bothered with the internals of how the vitest extension itself works

This should help developers understand why the extension doesn't work for them. For example, this explains why the extension doesn't work if you don't have a config file at all (which, granted, we should support in the future) or why you might see several test profiles when clicking on "Continues Run" or trying to filter tests. This should also help contributors understand how the extension works on a higher level before diving in the code.