epic: documentation

Vue has awesome docs, but the VTU docs are underwhelming. Let’s change that.

• too much “how to configure with XYZ test runner”
• not enough “this is how to use VTU”
• not enough “this is how to test and why it’s best practice to do …”
• not enough “this is how NOT use to VTU and why”

I’m thinking three major sections. The docs refresh is basically as big a project as building the library itself, and just as important. It really needs someone who has great attention to detail and a passion for education/communication. If someone is excited about this, speak up!

Docs are here: https://github.com/lmiller1990/vue-testing-framework/tree/master/packages/docs

1. Intro

• intro to the lib, what it’s for
• a simple guide where we build and test a component, so users can get their feet wet
• this needs to have a lot of thought put into it, we should spend a good amount of time thinking about the example component and tests we want to write. It sets the theme and expectations for the entire docs.
• make sure we cover nextTick, it’s a core principle. no need to go too deep on how/why, but emphasis when you need to call it and why
• probably should include a link to a vue-cli project with VTU ready to go? I don’t config should be a central theme for the docs - Vue doesn’t touch on it much, either

2. Guides for common use cases

• this is where we really teach people how to use VTU
• testing Vuetify (or another third party lib)
• testing components with Vue Router and Vuex
• how to deal with components that have large DOM trees, complex children that do API calls you don’t want in tests. Touch on stubbing/shallowMount/using your test runner’s features where possible over VTU

3. API reference

• this is pretty easy, just list all all the methods available and a simple example. Link to the previous guides where relevant

[lmiller1990]

Closing this in favor of tracking docs here: https://github.com/vuejs/vue-test-utils-next-docs

[afontcu]

I’m up for it! I’ll start tweaking the docs repo, trying to match the official docs.

So I was thinking of this “Cookbook” section, from simple to not-so-simple examples, where we can set the right mindset when testing common scenarios. It could be community-driven, so we could ask for additional examples. I guess it matches your 2. Guide for common use cases section.

Also, a FAQ section could help – not that people read them often, but it might come in handy to easily link to them in issues and discord. Faster than typing the same answers over and over again 😇