feat(types): add typescript declarations #15

ktsn · 2017-07-17T02:45:52Z

This PR adds TypeScript declarations of vue-test-utils.
I wrote these declarations by reading the current docs and implementation but not sure that the declaration is correct. So please let me know if somethings are wrong 😉

It would be easier to confirm by seeing test files under types/test. They include actual usage of vue-test-utils API in TypeScript.

@HerringtonDarkholme It would be appreciated if you can review this PR 🙂

Directory structure

types/
- index.d.ts All declarations of vue-test-utils are in this file. This should be published in npm.
- tsconfig.json TS compiler options are defined in this file
- test/ includes test files for typings

Allow annotating type for `mount`/`shallow`

One of challenge when using vue-test-utils would be how to declare wrapper.vm to an actual component type. For example, if we simply declare it as Vue, we cannot test component properties/methods since they are not declared in Vue.

@Component
class SomeComponent extends Vue {
  foo = 'bar'
}

const wrapper = mount(SomeComponent)
assert(wrapper.vm.foo === 'bar') // This throws a compile error

To solve this, I declared mount/shallow type that can be receive a component type via generics.

@Component
class SomeComponent extends Vue {
  foo = 'bar'
}

const wrapper = mount<SomeComponent>(SomeComponent)
assert(wrapper.vm.foo === 'bar') // This passes compiler type checking

const anyWrapper = mount<any>(SomeComponent) // We can use `any` type if we don't have appropriate type
assert(wrapper.vm.someOtherProperty === 'baz')

// Wrapper#find and Wrapper#findAll can receive a type parameter as well
const found = wrapper.find<SomeComponent>(SomeComponent)
const list = wrapper.findAll<SomeComponent>(SomeComponent)

Added npm script to test typings

I've added npm run test:types to run the typings test. It also be included in npm run test.

ktsn · 2017-07-17T03:23:37Z

Rethinking about WrapperArray#at, I guess it would be better that WrapperArray itself has a type parameter since its items always are the same type.

…self

HerringtonDarkholme · 2017-07-17T02:55:56Z

types/index.d.ts

+ readonly element: HTMLElement
+ readonly options: WrapperOptions
+
+ find<R extends Vue> (selector: Selector): Wrapper<R>


We can separate find to more overloadings. Thus for VClass and CompoentOption there is no need to manually cat.

Thanks for pointing this out.
By the way, I realized a type parameter could not be inferred from other type parameter so we have to manually set a component type if we use component constructors. Does this impossible until microsoft/TypeScript#14400 is solved, right?

// find<R extends Vue, Ctor extends VueClass<R> = VueClass<R>> (selector: Ctor): Wrapper<R> // `find`'s type parameters will be `<Vue, typeof ClassComponent>` const found = wrapper.find(ClassComponent)

Exactly. VueJS really needs it.

HerringtonDarkholme · 2017-07-17T03:15:17Z

types/index.d.ts

+ attachedToDocument: boolean
+}
+
+interface MountOptions<V extends Vue> extends ComponentOptions<V> {


I wonder the status of vuejs/vue#5887.

That PR will break this declaration. But 5887 does not seem to have activities...

@ktsn @yyx990803 What's your opinion?

I can change 5887 to have a compatible version by changing ComponentOptions, though. @DanielRosenwasser

I think vuejs/vue#5887 will not be merged soon since we need to have some migration time for the new declaration. So we can use the current declaration for now.

HerringtonDarkholme · 2017-07-17T03:16:26Z

types/index.d.ts

+interface MountOptions<V extends Vue> extends ComponentOptions<V> {
+ attachToDocument?: boolean
+ clone?: boolean
+ context?: VNodeData


This is only used by FunctionalComponent, can we make two separate options for different usage?

I thought about that but I ended up to choose type declaration simplicity. Also I have no idea to declare if a constructor of functional component is passed to mount/shallow 🤔

HerringtonDarkholme · 2017-07-17T03:22:14Z

types/index.d.ts

+ * If it is an array of string, the specified children are replaced by blank components
+ */
+type Stubs = {
+ [key: string]: Component | string | boolean


[key: string]: Component | string | true

https://github.com/vuejs/vue-test-utils/blob/master/src/lib/stub-components.js#L28-L31

HerringtonDarkholme · 2017-07-17T03:27:43Z

types/index.d.ts

+ localVue?: typeof Vue
+ intercept?: object
+ slots?: Slots
+ stub?: Stubs


I wonder why this API is called stub rather than stubs, since it can stub multiple components? @eddyerburgh

I think you're right, stubs is more appropriate 👍

@ktsn I've renamed stub to stubs in 0ff0f63

Updated 👍

HerringtonDarkholme · 2017-07-17T03:38:39Z

types/index.d.ts

+ clone?: boolean
+ context?: VNodeData
+ localVue?: typeof Vue
+ intercept?: object


@eddyerburgh I wonder why intercept is by default global.

https://github.com/vuejs/vue-test-utils/blob/master/docs/en/api/mount.md

vue-test-utils/src/lib/create-instance.js

Line 40 in a2137fa

if (options.intercept) {

I know this option is used to be global. But since it is changed its, it seems better to modify localVue by default. Since one mount returns one wrapper, it feels more natural that intercept only modify the wrapper.

If users want to modify Vue's prototype globally, we can, if strongly desired, provide another global API like mount. But fairly users can just Vue.install by themselves.

It doesn't add them globally, it's just a poorly named function. I'll refactor to make that clear

I've refactored in 086f8ae

snaptopixel · 2017-07-19T15:27:24Z

@ktsn and @HerringtonDarkholme are heros, just sayin'

feat(types): add typescript declarations

80c68ff

fix(types): move type parameter of WrapperArray#at to WrapperArray it…

1ab7d70

…self

HerringtonDarkholme reviewed Jul 17, 2017

View reviewed changes

ktsn added 4 commits July 17, 2017 14:34

fix(types): stub should not accept false value

a0e9e63

fix(types): change find/findAll type to infer vm type from an argument

49381d2

fix(types): remove type parameters of mount/shallow with options object

8279cf0

fix(types): rename stub to stubs in mount/shallow options

1d0a6fd

HerringtonDarkholme approved these changes Jul 17, 2017

View reviewed changes

eddyerburgh approved these changes Jul 17, 2017

View reviewed changes

eddyerburgh merged commit 86c8a7e into vuejs:master Jul 17, 2017

ktsn deleted the add-types branch July 17, 2017 08:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(types): add typescript declarations #15

feat(types): add typescript declarations #15

ktsn commented Jul 17, 2017 •

edited

Loading

ktsn commented Jul 17, 2017

HerringtonDarkholme Jul 17, 2017

ktsn Jul 17, 2017

HerringtonDarkholme Jul 17, 2017

HerringtonDarkholme Jul 17, 2017

ktsn Jul 17, 2017

HerringtonDarkholme Jul 17, 2017

ktsn Jul 17, 2017

HerringtonDarkholme Jul 17, 2017

HerringtonDarkholme Jul 17, 2017

eddyerburgh Jul 17, 2017

eddyerburgh Jul 17, 2017

ktsn Jul 17, 2017

HerringtonDarkholme Jul 17, 2017 •

edited

Loading

eddyerburgh Jul 17, 2017

eddyerburgh Jul 17, 2017

snaptopixel commented Jul 19, 2017

feat(types): add typescript declarations #15

feat(types): add typescript declarations #15

Conversation

ktsn commented Jul 17, 2017 • edited Loading

Directory structure

Allow annotating type for mount/shallow

Added npm script to test typings

ktsn commented Jul 17, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HerringtonDarkholme Jul 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snaptopixel commented Jul 19, 2017

ktsn commented Jul 17, 2017 •

edited

Loading

Allow annotating type for `mount`/`shallow`

HerringtonDarkholme Jul 17, 2017 •

edited

Loading