VTL for Vue 3: The routes option does not work correctly

[lbavendanos]

Describe the bug
When using the routes option of the render function, it throws up some warnings that have to do with the _history property and the asynchronic handling that vue router 4 has. This causes you to not be able to use the routes option correctly.

To Reproduce

import { render, screen } from '@testing-library/vue'
import '@testing-library/jest-dom'
import { defineComponent } from 'vue'
import { RouteRecordRaw } from 'vue-router'

test('Component with route', () => {
  const ComponentA = defineComponent({
    name: 'ComponentA',
    props: {
      to: {
        type: Object,
        required: true
      }
    },
    template: `<router-link :to="to" role="button">Learn More</router-link>`
  })

  const ComponentB = defineComponent({
    name: 'ComponentB'
  })

  const routeRecordRaw: RouteRecordRaw = {
    path: '/',
    name: 'componentB',
    component: ComponentB
  }

  const to = { name: routeRecordRaw.name }

  render(ComponentA, {
    props: { to },
    routes: [routeRecordRaw]
  })

  const button = screen.getByRole('button')

  expect(button).toBeInTheDocument()
  expect(button?.getAttribute('href')).toBe(routeRecordRaw.path)
})

This throws the following warning

console.warn node_modules/vue-router/dist/vue-router.cjs.js:75
    [Vue Router warn]: Unexpected error when starting the router: TypeError: Cannot read property '_history' of null

The warning is known. This is explained in the vue-test-utils v2 documentation
https://vue-test-utils.vuejs.org/v2/guide/vue-router.html#with-a-real-router

So to solve it apply what is indicated in documentation

import { render, screen } from '@testing-library/vue'
import '@testing-library/jest-dom'
import { defineComponent } from 'vue'
import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router'

test('Component with route', async () => {
  const ComponentA = defineComponent({
    name: 'ComponentA',
    props: {
      to: {
        type: Object,
        required: true
      }
    },
    template: `<router-link :to="to" role="button">Learn More</router-link>`
  })

  const ComponentB = defineComponent({
    name: 'ComponentB'
  })

  const routeRecordRaw: RouteRecordRaw = {
    path: '/',
    name: 'componentB',
    component: ComponentB
  }

  const router = createRouter({
    history: createWebHistory(process.env.BASE_URL),
    routes: [routeRecordRaw]
  })

  router.push('/')
  await router.isReady()

  const to = { name: routeRecordRaw.name }

  render(ComponentA, {
    props: { to },
    global: {
      plugins: [router]
    }
  })

  const button = screen.getByRole('button')

  expect(button).toBeInTheDocument()
  expect(button?.getAttribute('href')).toBe(routeRecordRaw.path)
})

Expected behavior
Be able to correctly use the routes option provided by the render function

Related information:

• @testing-library/vue version: ^6.3.1
• Vue version: ^3.0.0
• node version: 14.4.0
• npm version: 6.14.9

[afontcu]

Hi, thanks for the report!

We're already setting up a router with createWebHistory. Looks like we could simply add

routerPlugin.push('/')
await routerPlugin.isReady()

after this line and your first test would pass, but that would make render async, which is undesirable.

A potential solution is to expose router.isReady, so users could wait for it and then, in the test:

const {isRouterReady} = render(ComponentA, {
  props: {to},
  routes: [routeRecordRaw],
})

await isRouterReady() // isRouterReady is just routerPlugin.isReady

Gave it a go with your test and it works, but it's not… well, user-focused, and people need to be aware of it. I wonder why no combination of async waiting (using waitFor) works…

I'm gonna ping @lmiller1990 as he has already put in some work to integrate VTU and vue router, so he might come up with a better solution :)

[lmiller1990]

This is pretty much what I've been doing so far - await router.isReady().

I am not sure of a more ergonomic way of handling this 🤔 docs? Or can we do this internally somewhere?

[afontcu]

Or can we do this internally somewhere?

This was my first approach, but this would make render async, and I'd like to avoid that. Is there any workaround here? I don't think so 🤔

Maybe adding a isRouterReady key isn't that bad, given that we have types and autocompletion and it will be limited to tests involving a router.

[lmiller1990]

If we don't want render to be async then we will not be able to do this for the user. I suppose we just expose a method and document it well.

Maybe we should just expose the entire router - that seems useful. Eg:

const {router} = render(ComponentA, {
  props: {to},
  routes: [routeRecordRaw],
})
await router.isReady()

Although this may not fit with the VTL philosophy. I think this idea (expose some kind of router key) is probably the way to go.

[afontcu]

Gave it a go. I'm not 100% sold on the idea of exposing the whole router, mostly because, as you mentioned, is something one should not expect from Testing Lib. However we still need to wait for router to be ready… so I see two valid alternatives:

1. Expose a isRouterReady helper (VTL for Vue 3: The routes option does not work correctly #195 (comment)).

2. Detect if people is passing a routes option, and then make render async. People would then need to await render(). It might a bit too magic from a user perspective, though.

Thoughts?

[lmiller1990]

I think the first one is probably the lesser of the two evils. I have not written many router tests with VTL yet, though, so I am not sure how this actually works out in practice.

Either way, we are leaking implementation details into the test, but I can't see any way around this. I wonder if any of the other integrations have this problem (I don't think React Router is async, but surely some other plugin is? Are we really the first ones to experience this problem?)

[afontcu]

I wonder if any of the other integrations have this problem (I don't think React Router is async, but surely some other plugin is?

Yeah, I'll take a look, but I think VTL is a bit special here because we offer built-in support for external libraries (Vuex, Router), and others don't. That being said, I'll take a look at other implementations and see what they came up with

[ITenthusiasm]

I see router.isReady primarily being a concern here. But is it safe to assume that refers only to the initialization? If so, users would still have the problem of performing awaits while clicking links according to the beta docs. And we're just getting started there. There's also the possibility that maybe certain interactions with the store cause URL updates.

In that case, neither the render solution nor the isRouterReady solution would be sufficient in entirety. (To me, it's a little weird to imply "handling routers is synchronous" in one place and say in another "eh, it's async actually".)

I'm trying to think more about this, but I'm not sure there's a clear workaround. It may just be that people have to be told to await X before continuing when handling router interactions because Vue's Router is async. But that's undesirable for obvious reasons.

[ITenthusiasm]

Would it make sense to have a guide where people could create mocks with the different testing frameworks they're using? Or for VTU to export a mock sync router? I'm not sure how strange that would be. And I'm guessing there's a chance some people may want to verify URL changes still. 🤔

[lmiller1990]

Yes, everything about router is now async so this likely will be a problem in a few different respects. I have not written many tests w/ Vue 3 + new Router + testing lib to get a full idea yet.

There is a new project for mocking the router: https://github.com/posva/vue-router-mock but I don't know this will be ideal all situations, and I am also not sure it fits the testing library philosophy.

[afontcu]

Yeah… with Vue 3, all route handling in tests will be async because router is async. So here in VTL we'll need to use waitFor or findByXXXX. I guess we will need to add more examples and docs, but that's how it's gonna be (it is not that bad, to be honest).

That being said, we remain with this issue: how do we wait for the initial router render?

[afontcu]

I wonder if asyncWrapper could help us somehow

[ITenthusiasm]

Yeah. In terms of the options presented earlier, I think I'd probably prefer the conditionally async render. Although it feels a bit weird, it reduces boilerplate (slightly) and potentially reduces the number of things the user can forget. Either way, the user is going to have to await something and be told why that await is necessary unlike in other libraries (at least with those two options). Maybe a warning reminding people to use await when the history error occurs could be helpful too.

As for asyncWrapper, I don't have any familiarity with that one. If it simplifies things that'd be cool. Do you know exactly how it operates over in RTL land?