docs: update docs (fix #873)

[cesalberca]

With version 1.0.0-beta.20 the default export has been removed. This PR updates all the documentation that imports the default export and changes it accordingly.

I also took the liberty of replacing the bracket notation documentation to set global configuration to object notation. The reasoning is the following:

1. Object notation is easier to understand for begginners.
2. Object notation easily extensible. If I want to add two properties I can do as follows:

config.mocks = {
  foo: {
    bar: () => true
  },
  baz: {
    qux: () => true
  }
}

While with bracket notation I would have to something like this:

config.mocks['foo'] = bar = () => true
config.mocks['baz'] = qux = () => true

3. Using Object notation does not error in TypeScript while bracket notation does:

You would have to cast to any to make use of it:

This will make TypeScript users have a seamless experience.

Another thing to have into consideration is the change made to the methods config option.

The previous documentation states that global config methods should be declared as follows:

config.methods['errors'] = () => {
  any: () => false
}

However, this is equivalent to this:

config.methods = {
  errors()  {
    any: () => false
  }
}

Which I think it should be like this:

config.methods = {
  errors: {
    any: () => false
  }
}

Note that when using arrow functions, if we want an implicit return of an object we have to wrap it around parentheses:

const foo = () => ({ bar: 42 })

Which is the correct version then? I assumed errors must be an object, but I could be wrong.

[eddyerburgh]

Thanks for the PR, I'll read through it now. However, I'm confused about why you think Vue Test Utils removed default export in beta.20. The dist file has exported the same object for the last three months—https://github.com/vuejs/vue-test-utils/blame/dev/packages/test-utils/dist/vue-test-utils.js#L5563

[eddyerburgh]

Also I disagree about changing from bracket notation in the config. The examples now overwrite the previous object, whereas bracket notation would only overwrite a property if it existed.

[cesalberca]

I created a new project using Vue CLI 3.0 (with vue-test-utils 1.0.0-beta.21) and this error appears:

It's weird since in another project of mine I don't have any errors importing VueTestUtils, and in that project I have 1.0.0-beta.19. I tried downgrading in this project (https://github.com/cesalberca/i18n-typescript-tests-bug) to that version but I still have that error.

Regarding the notation: given that they are global mocks, shouldn't they be overwritten only once?

[eddyerburgh]

Ah that's an issue with the types, are you able to fix it in this PR?

Regarding the notation: given that they are global mocks, shouldn't they be overwritten only once?

Not necessarily. For example, stubs contains default stubs for Transition, TranstionGroup, and RouterLink, so overriding would remove those stubs.

[cesalberca]

Alright, I changed one compiler option: allowSyntheticDefaultImports to true which solves the default import issue (https://www.typescriptlang.org/docs/handbook/compiler-options.html). I reverted the object notation changes on the docs. I also changed the typings file so TypeScript users can use bracket notation on mocks and on provide. See tests for more info.

The only thing left to do, is determine if the docs are wrong about setting methods on the config (https://vue-test-utils.vuejs.org/api/config.html#methods).

[cesalberca]

Oups, my bad, I didn't push all the changes together and it seems you merged the changes

[eddyerburgh]

Ah, sorry I thought it was finished! Can you open a new PR?

[eddyerburgh]

The example in methods is confusing. You can add a simpler example if you like :)

[cesalberca]

Done, I create this PR: #875. Let's continue the conversation there 👍