npm package: @sanity/test
Description: Sanity Testing Package
Author: Sanity.io
Latest version: 0.0.1-alpha.1

# `@sanity/test`

## Required Env Variables

The tests expects to find the below env variables. Either define it in your shell, or add it to the `.env.local` file in the repository root.

- `SANITY_E2E_SESSION_TOKEN`: Before you get started with writing and running tests, you need to get hold of a token - either using your own Sanity user token (`sanity debug --secrets` will give you the CLI token provided you are logged in `sanity login`), or by creating a project API token using https://sanity.io/manage.
- `SANITY_E2E_PROJECT_ID`: Project ID of the studio
- `SANITY_E2E_DATASET`: Dataset name of the studio

## Setup

#### 1. Initialize Playwright

Run Playwright Init Command: Start by initializing Playwright in your project. This sets up the necessary configuration and dependencies. Run the following command in your project directory:

```bash
npx playwright init
```

This command will create a default configuration file and install Playwright as a dependency in your project.

#### 2. Configure Playwright

Paste the provided code into your `playwright.config.ts` file:

```ts
import {defineConfig} from '@playwright/test'
import {createPlaywrightConfig} from '@sanity/test'

const CI = process.env.CI // Assuming CI is set in your environment

const playwrightConfig = createPlaywrightConfig({
  projectId: process.env.SANITY_E2E_PROJECT_ID!,
  token: process.env.SANITY_E2E_SESSION_TOKEN!,
  playwrightOptions(config) {
    return {
      ...config,
      webServer: {
        ...config.webServer,
        command: CI ? 'yarn e2e:start' : 'yarn e2e:dev',
      },
    }
  },
})

export default defineConfig(playwrightConfig)
```

#### 3. Implement Global Setup

Add a Global Setup File: The global setup file is used for setting up global preconditions for your tests. The `@sanity/test` package adds default function that authenticates the user to the studio.

```ts
import {globalSetup} from '@sanity/test'

export default globalSetup
```

_Note: the default file for global setup is at `'./test/e2e/globalSetup'` path. This can be changed in the `playwright.config.ts`_

#### 5. Write and Run Tests

Start Writing Tests: There are multiple ways to write Playwright tests:

Using Playwright Codegen: Run `sanity-test codegen` to open an interactive browser session and generate test scripts based on your interactions with the browser. Note: the env variables are required for codegen to work

Using the VSCode Extension: If you prefer, you can use the Playwright extension for Visual Studio Code to write and manage your tests.

Manually Writing Tests: Write test scripts manually in your test files, using the Playwright API.

Run the Tests: Once your tests are written, you can run them using the Playwright CLI. A common command to run tests is:

```bash
npx playwright test
```

## Custom Fixtures

````ts
interface SanityFixtures {
  /**
   * This provides a Sanity client that can be used to interact with Sanity.
   *
   * @example
   * ```ts
   * function getRemoteValue() {
   *  return sanityClient
   *    .getDocument(`drafts.${documentId}`)
   *    .then((doc) => (doc ? doc.simple : null))
   * }
   *```
   */
  sanityClient: SanityClient
  /**
   * This fixture is used to create a new document in the dataset.
   * It will create a new document with a unique name and return the document.
   * It also navigates to the document given the path
   *
   * @example
   * ```ts
   * const documentId = await createDraftDocument('/test/content/input-ci;textsTest')
   * ```
   */
  createDraftDocument: (navigationPath: string) => Promise<string>
}
````