chore(e2e): update docs and make missing env more clear (#5421)

* chore(e2e): update docs and make missing env more clear

* chore(e2e): fix README.md

.env.example

@@ -7,7 +7,7 @@
 # You can generate your own token by heading over to the tokens-section of
 # https://www.sanity.io/manage/, or by using your CLI user token (`sanity debug --secrets`)
 SANITY_E2E_SESSION_TOKEN=
-SANITY_E2E_PROJECT_ID=
+SANITY_E2E_PROJECT_ID=kin4wkua
 SANITY_E2E_DATASET=
 
 # Whether or not to run the end to end tests in headless mode. Defaults to true, but sometimes

playwright.config.ts

@@ -1,32 +1,15 @@
 import {defineConfig} from '@playwright/test'
 import {createPlaywrightConfig} from '@sanity/test'
 import {loadEnvFiles} from './scripts/utils/loadEnvFiles'
+import {readBoolEnv, readEnv} from './test/e2e/helpers/envVars'
 
 loadEnvFiles()
 
-/**
- * Read an environment variable, parsing the response as a boolean, using loose
- * constraints (`true`, `1`, `yes` are all considered true, everything else is false)
- *
- * @param flag - The environment variable to read, eg `SOME_FLAG`
- * @param defaultValue - The default value to use if it is not set
- * @returns A boolean value
- * @internal
- */
-function readBoolEnv(flag: string, defaultValue: boolean) {
-  const value = process.env[flag]
-  if (value === undefined) {
-    return defaultValue
-  }
-
-  return value === 'true' || value === '1' || value === 'yes'
-}
-
 const CI = readBoolEnv('CI', false)
 
 const playwrightConfig = createPlaywrightConfig({
-  projectId: process.env.SANITY_E2E_PROJECT_ID!,
-  token: process.env.SANITY_E2E_SESSION_TOKEN!,
+  projectId: readEnv('SANITY_E2E_PROJECT_ID'),
+  token: readEnv('SANITY_E2E_SESSION_TOKEN'),
   playwrightOptions(config) {
     return {
       ...config,

scripts/utils/loadEnvFiles.ts

@@ -1,4 +1,4 @@
-/* eslint-disable no-process-env, no-sync */
+/* eslint-disable no-process-env */
 import fs from 'fs'
 import path from 'path'
 import dotenv from 'dotenv'
@@ -8,7 +8,7 @@ import dotenv from 'dotenv'
  *
  * @returns Array of environment file paths loaded.
  */
-export function loadEnvFiles() {
+export function loadEnvFiles(): string[] {
   const mode = process.env.NODE_ENV || 'development'
   const envFiles = ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]
   const loaded = []

test/e2e/README.md

@@ -10,43 +10,41 @@ The tests expects to find the below env variables. Either define it in your shel
 
 ## Running tests
 
-Before you can run the tests, you need to start the Test Studio:
-
-```
-npm run dev
-```
-
-When the Test Studio is running, you can run all tests or only specific tests. Here are some helpful commands:
+To run E2E tests run the following commands from the root of the project
 
 - Run all the tests
 
-  ```
-  npx playwright test
+  ```sh
+  yarn test:e2e
   ```
 
-- Run all tests in specific directory
+- Run all tests in specific directory, it runs relative to the `test/e2e/tests`
 
-  ```
-  npx playwright test tests/default-layout
+  ```sh
+  yarn test:e2e tests/default-layout
   ```
 
 - Run files that have my-spec or my-spec-2 in the file name
 
-  ```
-  npx playwright test my-spec my-spec-2
+  ```sh
+  yarn test:e2e my-spec my-spec-2
   ```
 
 - For help, run
+  ```sh
+  yarn test:e2e --help
   ```
-  npx playwright test --help
-  ```
+
+Other useful helper commands
+
+- "e2e:dev": Starts the E2E studio using `sanity dev`
+- "e2e:build": Runs `sanity build` on E2E studio
+- "e2e:codegen": Runs [playwright codegen](https://playwright.dev/docs/codegen). **Note: Requires the studio to be running. Run `yarn e2e:dev` in another terminal first**
+- "e2e:start": Runs `sanity build` on E2E studio
+- "e2e:preview": Runs builds and runs`sanity start` on E2E studio
 
 For more useful commands, see the [Playwright Command Line](https://playwright.dev/docs/test-cli) documentation.
 
 ### Running tests from your code editor
 
 You can run your tests in your editor with the help of some useful editor plugins/extensions. For example, you can download `Playwright Test for VSCode` from Microsoft to show and run your tests in VSCode.
-
-## Writing tests
-
-### File names

test/e2e/helpers/envVars.ts

@@ -0,0 +1,37 @@
+type KnownEnvVar =
+  | 'SANITY_E2E_SESSION_TOKEN'
+  | 'SANITY_E2E_PROJECT_ID'
+  | 'SANITY_E2E_DATASET'
+  | 'CI'
+
+/**
+ * Read an environment variable, parsing the response as a boolean, using loose
+ * constraints (`true`, `1`, `yes` are all considered true, everything else is false)
+ *
+ * @param flag - The environment variable to read, eg `SOME_FLAG`
+ * @param defaultValue - The default value to use if it is not set
+ * @returns A boolean value
+ * @internal
+ */
+export function readBoolEnv(flag: KnownEnvVar, defaultValue: boolean): boolean {
+  const value = findEnv(flag)
+  if (value === undefined) {
+    return defaultValue
+  }
+
+  return value === 'true' || value === '1' || value === 'yes'
+}
+
+export function readEnv(name: KnownEnvVar): string {
+  const val = findEnv(name)
+  if (val === undefined) {
+    throw new Error(
+      `Missing required environment variable "${name}". Make sure to copy \`.env.example\` to \`.env.local\``,
+    )
+  }
+  return val
+}
+
+export function findEnv(name: KnownEnvVar): string | undefined {
+  return process.env[name]
+}