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