docs: docs for options lack clarity

[benmccann]

Describe the bug

https://vitest.dev/api/#test does not show if any options can be used with the test function

The only place options are shown as being used is https://vitest.dev/api/#describe-only which says the options may be a number, but it gives no description of what the number represents. It also says the options are the third argument and I wonder if this is correct since the migration guide suggests that you need to migrate from it being the third argument to it being the second argument (https://vitest.dev/guide/migration#test-options-as-a-third-argument) for the test function and it would be surprising if test and describe.only took arguments in different orders

Reproduction

https://vitest.dev/api/

System Info

vite 3

Used Package Manager

pnpm

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[benmccann]

Something that might be worth mentioning in the migration guide for Vitest 3 is that Vitest 2 seems to have an infinite default timeout whereas Vitest 3 has a 5 second default timeout. I had to set the timeout option a bunch of places to get longer running tests passing with Vitest 3

[sheremet-va]

The only place options are shown as being used is https://vitest.dev/api/#describe-only

To be fair, the first section of the page has this with examples:

Most options support both dot-syntax and object-syntax allowing you to use whatever style you prefer.

The assumption is that users understand the difference between test.skip and test(name, { skip }) by looking at examples and can apply this knowledge for every sensible ("most") option on the page

I guess, we can also mention double syntax everywhere? Seems a bit of an overkill

[sheremet-va]

Something that might be worth mentioning in the migration guide for Vitest 3 is that Vitest 2 seems to have an infinite default timeout whereas Vitest 3 has a 5 second default timeout. I had to set the timeout option a bunch of places to get longer running tests passing with Vitest 3

Vitest always had a 5 seconds timeout

[benmccann]

Ah, I didn't see that there was more than one example until reading your reply here as I didn't notice that you had to tab to the second example. I don't think you need to repeat it everywhere, but I couldn't find it at all. It might help to show the first example and then say "or you can also do..." and then show the second example so that the second one is showing by default. Or show the options example first because there's already plenty of docs for things like test.skip already that are easier to find

Not sure about the timeout issue, but we had lots of tests going way past the 5 second timeout. Whatever the issue was it seems to be working with vitest 3, so not sure it's worth much time debugging it, but we did have to reconfigure the timeouts now that they're getting applied: sveltejs/kit#13330

[sheremet-va]

Not sure about the timeout issue, but we had lots of tests going way past the 5 second timeout. Whatever the issue was it seems to be working with vitest 3

Ah, I see. Synchronous functions were bugged and never timeout out, you are right, this was one of the fixes in Vitest 3