Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README #338

Open
4 tasks done
sheremet-va opened this issue Apr 13, 2024 · 2 comments
Open
4 tasks done

Update README #338

sheremet-va opened this issue Apr 13, 2024 · 2 comments
Labels
documentation Improvements or additions to documentation

Comments

@sheremet-va
Copy link
Member

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:

  • How to run a test
  • How to enable/disable continuous mode and its benefits
  • How to run code with coverage. Mention that coverage is disabled unless you specifically press the coverage button
  • How to debug a test. Mention that if debugging multiple tests, they will not be running in parallel
    • How to use breakpoints/debugger statement
  • How to work with test filters (like @open)
  • Explain how the extension finds test files (scans for configs and starts new Vitest process for every config)
  • Explain how the extension collects tests (it runs Vitest in collect mode, so it can take a while if your tests have a lot of imports)
  • Available configuration with description and examples (maybe in a table form?)

I would also like to rewrite the introduction section:

  • Remove the current GIF since it uses the previous extension.
  • Remove the VSCode + Vitest logo as it takes a lot of space for nothing

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

@sheremet-va sheremet-va added the documentation Improvements or additions to documentation label Apr 13, 2024
@MilanKovacic
Copy link
Collaborator

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
Copy link
Member Author

sheremet-va commented Apr 13, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants