@sanity/test

@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:

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:

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.

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:

npx playwright test

Custom Fixtures

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>
}