How to Manage Composition API Refs in Vue 3 When Unit Testing

Reuse state logic in Vue with composables written with the Composition API. Read more.

The Composition API for Vue opened up a very powerful and flexible way of coding Vue components. A big part of this flexibility is the ability to create composables, which are, as described by the Vue docs, “a function that leverages Vue’s Composition API to encapsulate and reuse stateful logic.”

A problem that I’ve often encountered is that the way to test the use of these composables within a component is not immediately obvious, and can lead to the creation of bad practices.

In this article, we will explore how to test the use of a composable within a Vue 3 component with Jest and Vue Test Utils—the concepts, however, are directly translatable to Vitest.

Key Concepts

Before we dive into the code, I want to establish a couple of key concepts.

We will be leveraging the use of jest.mock to mock out the whole composable when testing it, this means that we will not be directly testing the internals of the composable. This is particularly important when testing composables that either make API calls internally or are provided by a third-party library.

It’s not uncommon in certain teams to avoid this in favor of deep testing the integration of a component with all of the dependencies, but this practice can be problematic as it breaks the concept of unit testing encapsulation. The bottom line is that a unit test that tests two different components or files is crossing into the territory of an integration test.

This does not in any case mean that you should not test the composable extensively, but it should be tested separately as a unit. As a consumer of that unit, the component that uses it should trust that the component’s contract input and output (I/O) is what it expects it to be, and any and all refactoring of the I/O of the unit should be treated as a breaking change within the bigger context of the codebase. (Whew.)

In some cases, however, such as simple composables that, for example, provide only a subset of computed values, it may be OK to not mock the returns of the function. However, in general, I recommend mocking the contents of these files in the component that imports them—otherwise, we’d be creating integration tests as stated previously.

Having laid out all that, let’s jump into the example.

The Code

Let’s assume that we have a composable that obtains data from our API’s endpoint for a user. Within this composable, a few network calls are happening, and the data is being parsed out into a few different computed properties that are returned out of the function so that we can check user permissions and state. Additionally, we will have an update function that would mutate the user’s configuration.

The internals of this composable are not important. The only thing we need to know as its consumer is the contract—what properties does this composable expect, and what will it return when I call it?

useUser.js

export const useUser = (userId) => {
  [...]

  return {
    update, // a function
    user, // a ref with the User object
    isEmployee // a computed Boolean
  }
}

Whenever we call the useUser composable, we know that will have to pass a userId to it and we will receive in return the three properties declared above.

Let’s create a simplified demo component that will use our useUser composable.

UpdateUserForm.vue

<template>
<form @submit.prevent="submit">
  <input data-testid="email" name="email" v-model="user.email" />
  <input data-testid="employee-id" v-if="isEmployee" name="employeeID" v-model="user.employeeID" />
</form>
</template>

<script setup>
import { useUser } from './useUser'

const props = defineProps({
  userId: { type: Number, required: true }
})

const { update, user, isEmployee } = useUser(props.userId)

const submit = async () => {
  try {
    await update(user.id, {
      email: user.value.email,
      employeeID: user.value.employeeID
    })
  } catch (e) {
    // handle error
  }
}
</script>

There’s a few things happening here so let’s take a deep look.

1. We are creating an extremely simplified version of a form for our user where we can edit both the email and, in the case that the user is an employee, their employee ID.
2. Note that the employee ID input will be displayed only in the case that the computed isEmploye is true—we will have to test for this.
3. When the user is submitted, it will call our submit method.
4. We import our useUser composable and call it with the userId received by the prop userId—we will want to test this. We extract the three returnable properties out of it by leveraging destructing.
5. Within our submit function we call the update function with the user’s ID as the first parameter and a second parameter we update the properties of the user email and employeeID with the updated values.
6. We are assuming for simplicity that it’s OK to mutate the user object returned to us by the composable. In some cases this may not be true, but we will use this as an example later on to clarify a point.

Now that we have our component, we can start writing our tests.

Testing the UpdateUserForm Component

The first thing we’ll want to test is that our useUser composable is getting called with the correct value. We don’t want to be in a situation where it’s not correctly receiving the user id as a property. For this we will have to already set up our mock, so let’s go through the code together.

UpdateUserForm.spec.js

import UpdateUserForm from './UpdateUserForm.vue'
import { useUser } from './useUser'
import { shallowMount } from 'vue@test-utils'
import { ref } from 'vue'

jest.mock('./useUser')

describe('UpdateUserForm', () => {
  const update = jest.fn()
  const user = ref({})
  const isEmployee = ref(false)
  
  beforeEach(() => {
    jest.clearAllMocks()

    user.value = { email: 'test@test.com', employeeID: null }
    isEmployee.value = false

    useUser.mockReturnValue({
      update,
      user,
      isEmployee
    })
  })

  it('passes the userId prop to the useUser composable', () => {
    const userId = 123
    shallowMount({
      props: { userId }
    })

    expect(useUser).toHaveBeenCalledWith(123)
  })
})

There’s a lot happening here, so let’s go step by step.

1. We are using jest.mock to mock out the whole /useUser file. We will control the return of the useUser function in line 16.
2. In a beforeEach call, we clearAllMocks on jest because we will be using jest.fn to keep track of the update function. We also use jest’s mockReturnValue to mock the return of the useUser composable. This means that we have to provide the returns for the composable here.
3. The first return update is declared above as a jest.fn, we declare it above as a const so that we can easily access this in all of our tests without having to reestablish the mockReturnValue in each test that we check for it. This may seem like overkill, but the re-mocking of the return value in every test can quickly bloat the document.
4. We are also declaring in lines 10 and 11 ref values for our user value and a ref for the isEmployee computed, later on inside the beforeEach block we reset the values of both of these values.

A couple of question may arise at this point, the first one being why are we using a ref to mock out a computed value?

The answer is for simplicity. You could absolutely set the isEmployee constant to a computed as so.

const isEmployee = computed(() => false)

However, this will make it a little challenging when writing tests as you will be able to easily change the return value of this property on the fly to check for different states of your component without having to re-mock the composable. This will make more sense when we write tests for it.

The second question that may arise is: why are we declaring the refs outside of the scope of all of our tests and then reseting them in the top most beforeEach block?

As you write more and more tests that use these values, you will be faced with two challenges. Either you have to make the choice of re-mocking the return values of the composable on every test or describe block to fit what you are trying to test, which can be overwhelming and error-prone, or keep them in a scope where they are accessible to all your tests.

For cleanliness, I recommend doing all of this in the highest level describe block of your test as shown here.

The second part of this is that we are choosing to reset the values of these refs beforeEach test because these refs will retain the value that the last test left them on as they are scoped outside of the tests themselves. We will use the top level beforeEach as a setup point for our whole test suite, so it makes sense to set the default values there. This is why the user ref is initially created with an empty object as a value, because this value is soon replaced.

Let’s move on and write a test that covers the v-if of our employee ID input.

UpdateUserForm.spec.js

import UpdateUserForm from './UpdateUserForm.vue'
import { useUser } from './useUser'
import { shallowMount } from 'vue@test-utils'
import { ref } from 'vue'

jest.mock('./useUser')

describe('UpdateUserForm', () => {
  const update = jest.fn().mockResolvedValue(true)
  const user = ref({})
  const isEmployee = ref(false)
  
  beforeEach(() => {
    jest.clearAllMocks()

    user.value = { email: 'test@test.com', employeeID: null }
    isEmployee.value = false

    useUser.mockReturnValue({
      update,
      user,
      isEmployee
    })
  })

  it('passes the userId prop to the useUser composable', () => {
    const userId = 123
    shallowMount({
      props: { userId }
    })

    expect(useUser).toHaveBeenCalledWith(123)
  })

  // NEW BLOCK
  describe('When the user is an employee', () => {
    beforeEach(() => {
      isEmployee.value = true
    })

    it('displays the employee ID input field when the user is an employee', () => {
      const wrapper = shallowMount({
        props: { userId: 123 }
      })

      expect(wrapper.find('[data-testid="employee-id"]').exists()).toBe(true)
    })
  })

  // NEW BLOCK
  describe('When the user is not an employee', () => {
    beforeEach(() => {
      isEmployee.value = false
    })

    it('displays the employee ID input field when the user is an employee', () => {
      const wrapper = shallowMount({
        props: { userId: 123 }
      })

      expect(wrapper.find('[data-testid="employee-id"]').exists()).toBe(false)
    })
  })
})

Let’s once again take a deep look.

1. We have opted for creating two describe blocks that accurately describe the state of the application that we want to test for. One of them will contain the tests for when our component is handling an employee, and one for when they are not. Notice that we added beforeEach blocks on each of them to clearly set up for the tests. In each of them we set the value of the isEmployee ref to either true or false as needed. We can rest assured that this value change will only affect these tests as we have established a reset for this earlier in the top level beforeEach block.
2. We then added a test for each of the scenarios.

At face value, this may seem like a lot of boilerplate and structure for such simple tests, and it is—but the reality is that in a production environment you will likely have quite a few more tests and complex scenarios. Having a good order and structure for your tests is always a good practice!

Let’s move on with the final portion of the tests, checking the ability of the user to submit the information.

UpdateUserForm.spec.js

import UpdateUserForm from './UpdateUserForm.vue'
import { useUser } from './useUser'
import { shallowMount, flushPromises } from 'vue@test-utils'
import { ref } from 'vue'

jest.mock('./useUser')

describe('UpdateUserForm', () => {
  const update = jest.fn()
  const user = ref({})
  const isEmployee = ref(false)
  
  beforeEach(() => {
    jest.clearAllMocks()

    user.value = { email: 'test@test.com', employeeID: null }
    isEmployee.value = false

    useUser.mockReturnValue({
      update,
      user,
      isEmployee
    })
  })

  it('passes the userId prop to the useUser composable', () => {
    const userId = 123
    shallowMount({
      props: { userId }
    })

    expect(useUser).toHaveBeenCalledWith(123)
  })

  describe('When the user is an employee', () => {
    beforeEach(() => {
      isEmployee.value = true
    })

    it('displays the employee ID input field when the user is an employee', () => {
      const wrapper = shallowMount({
        props: { userId: 123 }
      })

      expect(wrapper.find('[data-testid="employee-id"]').exists()).toBe(true)
    })

    // NEW
    it('calls the update function when the user submits the form', () => {
      const userId = 123
      const wrapper = shallowMount({
        props: { userId }
      })

      wrapper.find('[data-testid="email"]').setValue('email@test.com')
      wrapper.find('form').trigger('submit')
      
      await flushPromises()      

      expect(update).toHaveBeenCalledWith(userId, {
        email: 'email@test.com',
        employeeID: null
      })
    })
  })

  describe('When the user is not an employee', () => {
    beforeEach(() => {
      isEmployee.value = false
    })

    it('displays the employee ID input field when the user is an employee', () => {
      const wrapper = shallowMount({
        props: { userId: 123 }
      })

      expect(wrapper.find('[data-testid="employee-id"]').exists()).toBe(false)
    })
  })
})

In line 48, we added a new test to cover the submission of the form when the user is not an employee.

1. We find the email input and set its value to a new email and proceed to submit the form.
2. We need to await flushPromises as we have declared that the update function is going to return a Promise and is being awaited.
3. Finally we check that the update function (that was returned by the composable) is being called with the correct values.

An important thing to mention that may not be immediately obvious is that the user ref is being modified by the component whenever we update the value of one of the inputs, as the v-model bindings of each of the inputs is actually pointing to the user object.

I mentioned earlier that this may not be the case in your particular component, and this is not particularly a practice that I endorse, as mutating return values that are coming from a black box such as a composable leads frequently to problems and spaghetti code. However, I wanted to illustrate the importance of the ref management we made on the first beforeEach block.

If we had skipped the setting of the default values on this block, we would be in a situation where the tests following this one would be operating with the email we are setting on this test. This would be perhaps easy to pinpoint in a component as simple as this one, but, as your application grows in complexity, these kind of errors become extremely hard to pin down as they produce false positives in your tests.

Wrapping Up

Ref management and the way that we structure our unit tests needs to be a careful consideration with as much attention to detail and care as the actual component composition itself. As applications grow and become exponentially more complex, having good clean practices and management of your reactive values will save you many headaches.