1---
2title: Teleported Content Requires Special Testing Approach
3impact: MEDIUM
4impactDescription: Vue Test Utils cannot find teleported content using standard wrapper.find() methods
5type: gotcha
6tags: [vue3, teleport, testing, vue-test-utils]
7---
8 
9# Teleported Content Requires Special Testing Approach
10 
11**Impact: MEDIUM** - Vue Test Utils scopes queries to the mounted component. Teleported content renders outside the component's DOM tree, so `wrapper.find()` cannot locate it. This leads to failing tests and confusion.
12 
13## Task Checklist
14 
15- [ ] Stub Teleport in unit tests to keep content in component tree
16- [ ] Use `document.body` queries for integration tests with real Teleport
17- [ ] Consider using `getComponent()` instead of DOM queries for teleported components
18 
19**Problem - Standard Testing Fails:**
20```vue
21<!-- Modal.vue -->
22<template>
23  <button @click="open = true">Open</button>
24  <Teleport to="body">
25    <div v-if="open" class="modal" data-testid="modal">
26      <input type="text" data-testid="modal-input" />
27    </div>
28  </Teleport>
29</template>
30```
31 
32```ts
33// Modal.spec.ts - BROKEN
34import { mount } from '@vue/test-utils'
35import Modal from './Modal.vue'
36 
37test('modal input exists', async () => {
38  const wrapper = mount(Modal)
39  await wrapper.find('button').trigger('click')
40 
41  // FAILS: Teleported content is not in wrapper's DOM tree
42  expect(wrapper.find('[data-testid="modal-input"]').exists()).toBe(true)
43})
44```
45 
46**Solution 1 - Stub Teleport:**
47```ts
48import { mount } from '@vue/test-utils'
49import Modal from './Modal.vue'
50 
51test('modal input exists', async () => {
52  const wrapper = mount(Modal, {
53    global: {
54      stubs: {
55        // Stub teleport to render content inline
56        Teleport: true
57      }
58    }
59  })
60 
61  await wrapper.find('button').trigger('click')
62 
63  // Works: Content renders inside wrapper
64  expect(wrapper.find('[data-testid="modal-input"]').exists()).toBe(true)
65})
66```
67 
68**Solution 2 - Query Document Body:**
69```ts
70import { mount } from '@vue/test-utils'
71import Modal from './Modal.vue'
72 
73test('modal renders to body', async () => {
74  const wrapper = mount(Modal, {
75    attachTo: document.body  // Required for Teleport to work
76  })
77 
78  await wrapper.find('button').trigger('click')
79 
80  // Query the actual DOM
81  const modal = document.querySelector('[data-testid="modal"]')
82  expect(modal).toBeTruthy()
83 
84  const input = document.querySelector('[data-testid="modal-input"]')
85  expect(input).toBeTruthy()
86 
87  // Cleanup
88  wrapper.unmount()
89})
90```
91 
92**Solution 3 - Custom Teleport Stub with Content Access:**
93```ts
94import { mount, config } from '@vue/test-utils'
95import { h, Teleport } from 'vue'
96import Modal from './Modal.vue'
97 
98// Custom stub that renders content in a testable way
99const TeleportStub = {
100  setup(props, { slots }) {
101    return () => h('div', { class: 'teleport-stub' }, slots.default?.())
102  }
103}
104 
105test('modal with custom stub', async () => {
106  const wrapper = mount(Modal, {
107    global: {
108      stubs: {
109        Teleport: TeleportStub
110      }
111    }
112  })
113 
114  await wrapper.find('button').trigger('click')
115 
116  // Content is inside .teleport-stub
117  expect(wrapper.find('.teleport-stub [data-testid="modal-input"]').exists()).toBe(true)
118})
119```
120 
121## Testing Vue Final Modal and UI Libraries
122 
123Libraries like Vue Final Modal use Teleport internally, causing test failures:
124 
125```ts
126// Problem: Vue Final Modal teleports to body
127import { VueFinalModal } from 'vue-final-modal'
128 
129test('modal content', async () => {
130  const wrapper = mount(MyComponent, {
131    global: {
132      stubs: {
133        // Stub the modal component to avoid teleport issues
134        VueFinalModal: true
135      }
136    }
137  })
138})
139```
140 
141## E2E Testing (Cypress, Playwright)
142 
143E2E tests query the real DOM, so Teleport works naturally:
144 
145```ts
146// Cypress
147it('opens modal', () => {
148  cy.visit('/page-with-modal')
149  cy.get('button').click()
150 
151  // Works: Cypress queries the real DOM
152  cy.get('[data-testid="modal"]').should('be.visible')
153})
154```
155 
156## Reference
157- [Vue Test Utils - Teleport](https://test-utils.vuejs.org/guide/advanced/teleport)
158- [Vue Test Utils - Stubs](https://test-utils.vuejs.org/guide/advanced/stubs-shallow-mount)
159