From 44a49f0bc1157cc27a521792e61c72136c03893a Mon Sep 17 00:00:00 2001
From: Adam DeHaven <2229946+adamdehaven@users.noreply.github.com>
Date: Thu, 1 Aug 2024 09:58:33 -0400
Subject: [PATCH] docs: setup host property and usage example (#28331)

---
 docs/1.getting-started/11.testing.md | 52 ++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 11 deletions(-)

diff --git a/docs/1.getting-started/11.testing.md b/docs/1.getting-started/11.testing.md
index 9ae5b6264c..dffad43826 100644
--- a/docs/1.getting-started/11.testing.md
+++ b/docs/1.getting-started/11.testing.md
@@ -414,16 +414,16 @@ If you prefer to use `@vue/test-utils` on its own for unit testing in Nuxt, and
 
    ::code-group
    ```bash [yarn]
-   yarn add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue 
+   yarn add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue
    ```
    ```bash [npm]
-   npm i --save-dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue 
+   npm i --save-dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue
    ```
    ```bash [pnpm]
-   pnpm add -D vitest @vue/test-utils happy-dom @vitejs/plugin-vue 
+   pnpm add -D vitest @vue/test-utils happy-dom @vitejs/plugin-vue
    ```
    ```bash [bun]
-   bun add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue 
+   bun add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue
    ```
    ::
 
@@ -432,7 +432,7 @@ If you prefer to use `@vue/test-utils` on its own for unit testing in Nuxt, and
    ```ts twoslash
    import { defineConfig } from 'vitest/config'
    import vue from '@vitejs/plugin-vue'
- 
+
    export default defineConfig({
      plugins: [vue()],
      test: {
@@ -465,9 +465,9 @@ If you prefer to use `@vue/test-utils` on its own for unit testing in Nuxt, and
    ```ts twoslash
    import { describe, it, expect } from 'vitest'
    import { mount } from '@vue/test-utils'
- 
+
    import HelloWorld from './HelloWorld.vue'
- 
+
    describe('HelloWorld', () => {
      it('component renders Hello world properly', () => {
        const wrapper = mount(HelloWorld)
@@ -544,17 +544,22 @@ Please use the options below for the `setup` method.
 
 #### Features
 
+- `build`: Whether to run a separate build step.
+  - Type: `boolean`
+  - Default: `true` (`false` if `browser` or `server` is disabled, or if a `host` is provided)
+
 - `server`: Whether to launch a server to respond to requests in the test suite.
   - Type: `boolean`
-  - Default: `true`
+  - Default: `true` (`false` if a `host` is provided)
 
 - `port`: If provided, set the launched test server port to the value.
   - Type: `number | undefined`
   - Default: `undefined`
 
-- `build`: Whether to run a separate build step.
-  - Type: `boolean`
-  - Default: `true` (`false` if `browser` or `server` is disabled)
+- `host`: If provided, a URL to use as the test target instead of building and running a new server. Useful for running "real" end-to-end tests against a deployed version of your application, or against an already running local server (which may provide a significant reduction in test execution timings). See the [target host end-to-end example below](#target-host-end-to-end-example).
+  - Type: `string`
+  - Default: `undefined`
+
 - `browser`: Under the hood, Nuxt test utils uses [`playwright`](https://playwright.dev) to carry out browser testing. If this option is set, a browser will be launched and can be controlled in the subsequent test suite.
   - Type: `boolean`
   - Default: `false`
@@ -566,6 +571,31 @@ Please use the options below for the `setup` method.
   - Type: `'vitest' | 'jest' | 'cucumber'`
   - Default: `'vitest'`
 
+##### Target `host` end-to-end example
+
+A common use-case for end-to-end testing is running the tests against a deployed application running in the same environment typically used for Production.
+
+For local development or automated deploy pipelines, testing against a separate local server can be more efficient and is typically faster than allowing the test framework to rebuild between tests.
+
+To utilize a separate target host for end-to-end tests, simply provide the `host` property of the `setup` function with the desired URL.
+
+```ts twoslash
+import { setup, createPage } from '@nuxt/test-utils/e2e'
+import { describe, it, expect } from 'vitest'
+
+describe('login page', async () => {
+  await setup({
+    host: 'http://localhost:8787',
+  })
+
+  it('displays the email and password fields', async () => {
+    const page = await createPage('/login')
+    expect(await page.getByTestId('email').isVisible()).toBe(true)
+    expect(await page.getByTestId('password').isVisible()).toBe(true)
+  })
+})
+```
+
 ### APIs
 
 #### `$fetch(url)`