Add test config, README, and setup files (#2352)

Author: jordanarldt

.gitignore

@@ -8,9 +8,11 @@ dist
 .catalyst
 .env
 .env*.local
+.env*.test
 test-results/
 playwright-report/
 playwright/.cache/
+.tests
 bigcommerce.graphql
 bigcommerce-graphql.d.ts
 .DS_Store

core/.env.test.example

@@ -0,0 +1,36 @@
+# This file should hold any environment variables specific to test execution.
+# Any overlapping variables in here will overwrite variables from the other .env files.
+# For example, if BIGCOMMERCE_CHANNEL_ID=1 in .env.local, but BIGCOMMERCE_CHANNEL_ID=5 in this file, the test environment will use BIGCOMMERCE_CHANNEL_ID=5
+
+# Access token client ID and client secret are required for JWT login tests. If not provided, tests that require these will be skipped.
+BIGCOMMERCE_CLIENT_ID=
+BIGCOMMERCE_CLIENT_SECRET=
+
+# Base URL for all tests. This should always be set. It is recommended to run tests against a production build.
+# If not set or undefined, it will default to 'http://localhost:3000'
+PLAYWRIGHT_TEST_BASE_URL=http://localhost:3000
+
+# If true, playwright will automatically start the Catalyst NextJS server before running tests.
+PLAYWRIGHT_START_WEBSERVER=false
+PLAYWRIGHT_START_WEBSERVER_COMMAND=pnpm start
+
+# If true, no tests will execute that require modifying/deleting any data on your store.
+# This is particularly useful if you want to run the tests against a live store and avoid test data being visible to any customers.
+# If this is false, you should only run tests against a staging store where test data is okay.
+TESTS_READ_ONLY=false
+
+# Locale to use during test execution
+TESTS_LOCALE=en
+
+# The fallback locale to use in the occurence of missing translation keys in the selected TESTS_LOCALE
+# This should match the default locale you have set for your storefront
+TESTS_FALLBACK_LOCALE=en
+
+# An existing customer account to use for all tests - use this if you don't want tests to create a new customer account.
+# If TESTS_READ_ONLY is `true`, then any test requiring a customer will be skipped if these values are not set.
+TEST_CUSTOMER_ID=1
+TEST_CUSTOMER_EMAIL=example@test.com
+TEST_CUSTOMER_PASSWORD=Password1
+
+# The default product ID to use for tests. This needs to be a product without variants (simple)
+DEFAULT_PRODUCT_ID=111

core/.eslintrc.cjs

@@ -62,10 +62,31 @@ const config = {
       },
     ],
   },
+  overrides: [
+    {
+      files: ['**/*.spec.ts', '**/*.test.ts'],
+      rules: {
+        '@typescript-eslint/no-restricted-imports': [
+          'error',
+          {
+            paths: [
+              {
+                name: 'next-intl/server',
+                importNames: ['getTranslations', 'getFormatter'],
+                message:
+                  'Please import `getTranslations` from `~/tests/lib/i18n` and `getFormatter` from `~/tests/lib/formatter` instead.',
+              },
+            ],
+          },
+        ],
+      },
+    },
+  ],
   ignorePatterns: [
     'client/generated/**/*.ts',
     'playwright-report/**',
     'test-results/**',
+    '.tests/**',
     '**/google_analytics4.js',
   ],
 };

core/.gitignore

@@ -10,6 +10,7 @@
 /test-results/
 /playwright-report/
 /playwright/.cache/
+/.tests
 
 # next.js
 /.next/

core/package.json

@@ -31,6 +31,7 @@
     "@radix-ui/react-toggle": "^1.1.3",
     "@radix-ui/react-toggle-group": "^1.1.3",
     "@radix-ui/react-tooltip": "^1.2.0",
+    "@t3-oss/env-core": "^0.13.6",
     "@upstash/redis": "^1.34.7",
     "@vercel/analytics": "^1.5.0",
     "@vercel/kv": "^3.0.0",
@@ -64,7 +65,7 @@
     "sonner": "^1.7.4",
     "tailwindcss-radix": "^4.0.2",
     "uuid": "^11.1.0",
-    "zod": "^3.24.2"
+    "zod": "^3.25.48"
   },
   "devDependencies": {
     "@0no-co/graphqlsp": "^1.12.16",

core/playwright.config.ts

@@ -1,24 +1,29 @@
 import { defineConfig, devices } from '@playwright/test';
-import { config } from 'dotenv';
 
-config();
+import { testEnv } from '~/tests/environment';
 
 export default defineConfig({
   testDir: './tests',
+  outputDir: './.tests/test-results',
+  workers: 1, // TODO: Implement parallel workers in the future
   expect: {
     toHaveScreenshot: {
       maxDiffPixelRatio: 0.02,
     },
   },
-  reporter: [['list'], ['html']],
+  reporter: [
+    ['list', { outputFolder: './.tests/reports/list' }],
+    ['html', { outputFolder: './.tests/reports/html' }],
+  ],
   use: {
-    baseURL: process.env.PLAYWRIGHT_TEST_BASE_URL,
+    locale: testEnv.TESTS_LOCALE,
+    baseURL: testEnv.PLAYWRIGHT_TEST_BASE_URL,
     screenshot: 'only-on-failure',
     video: 'retain-on-failure',
     trace: 'retain-on-failure',
     extraHTTPHeaders: {
-      'x-vercel-protection-bypass': process.env.VERCEL_PROTECTION_BYPASS || '',
-      'x-vercel-set-bypass-cookie': process.env.CI ? 'true' : 'false',
+      'x-vercel-protection-bypass': testEnv.VERCEL_PROTECTION_BYPASS,
+      'x-vercel-set-bypass-cookie': testEnv.CI.toString(),
     },
   },
   projects: [

core/tests/README.md

@@ -0,0 +1,49 @@
+# Testing your Catalyst storefront
+
+This document provides an overview of how to run tests for your Catalyst storefront. This includes the requirements, environment setup, folder structure, and best practices. This README assumes that you already have a Catalyst storefront set up and all of the dependencies installed.
+
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Environment setup](#environment-setup)
+- [Running tests](#running-tests)
+
+## Prerequisites
+- Ensure that you have already installed and set up Playwright. (See the [Playwright documentation](https://playwright.dev/docs/intro) for more information.)
+- **Recommended**: Install the Playwright VSCode extension for easier test management and execution.
+
+## Environment setup
+
+To run tests, you first need to make sure you have the necessary environment setup. You should have already installed the required dependencies and configured your Catalyst environment in `.env.local`.
+
+To begin, copy `.env.test.example` to `.env.test`. The Catalyst test environment merges `.env.local` with `.env.test.local`, so any test-related environment variables should **only** be in `.env.test.local`. This allows you to keep your test configuration separate from your development configuration.
+
+**NOTE:** Any environment variables defined in `.env.test.local` will override those in `.env.local`.
+
+## Running tests
+
+When running tests locally, ensure that you have an active build for your Catalyst storefront by running `pnpm build`. This will ensure that the latest changes are included in the tests. Alternatively, you can use `pnpm dev` to run the development server, but this is not recommended.
+
+When running tests against a live deployment, ensure that you have set the `PLAYWRIGHT_TEST_BASE_URL` environment variable to the URL of your live deployment storefront, and ensure that `TESTS_READ_ONLY` is set accordingly for your needs.
+
+**NOTE:** The examples use `pnpm`, but you can also use `npx` if you prefer. Additionally, you can leverage the Playwright VSCode extension to run your tests.
+
+### CLI commands
+To run all of the tests, use the following command:
+
+```bash
+pnpm playwright test
+```
+
+To run a specific test file, you can specify the path to the test file:
+
+```bash
+pnpm playwright test auth/logout.spec.ts
+```
+
+To run a specific test within a file, you can use the `-g` flag followed by the name of the test:
+
+```bash
+pnpm playwright test auth/logout.spec.ts -g "Logout works as expected"
+```
+
+For more information on the available CLI commands, refer to the [Playwright CLI documentation](https://playwright.dev/docs/test-cli).

core/tests/environment.ts

@@ -0,0 +1,34 @@
+import { createEnv } from '@t3-oss/env-core';
+import { config as dotenvConfig } from 'dotenv';
+import { z } from 'zod/v4';
+
+import { defaultLocale, locales } from '~/i18n/locales';
+
+dotenvConfig({ path: ['.env', '.env.local', '.env.test'], override: true });
+
+const localeSchema = z.string().refine((val: string) => locales.includes(val), {
+  error: `TESTS_LOCALE must be one of: ${locales.join(', ')}`,
+});
+
+export const testEnv = createEnv({
+  server: {
+    BIGCOMMERCE_ADMIN_API_HOST: z.string().optional().default('api.bigcommerce.com'),
+    BIGCOMMERCE_ACCESS_TOKEN: z.string().optional(),
+    BIGCOMMERCE_ACCESS_TOKEN_CLIENT_ID: z.string().optional(),
+    BIGCOMMERCE_ACCESS_TOKEN_CLIENT_SECRET: z.string().optional(),
+    BIGCOMMERCE_CHANNEL_ID: z.coerce.number().optional(),
+    BIGCOMMERCE_STORE_HASH: z.string().optional(),
+    PLAYWRIGHT_TEST_BASE_URL: z.string().optional().default('http://localhost:3000'),
+    VERCEL_PROTECTION_BYPASS: z.string().optional().default(''),
+    CI: z.stringbool().optional().default(false),
+    TESTS_READ_ONLY: z.stringbool().optional().default(false),
+    TESTS_LOCALE: localeSchema.default(defaultLocale),
+    TESTS_FALLBACK_LOCALE: localeSchema.default(defaultLocale),
+    TEST_CUSTOMER_ID: z.coerce.number().optional(),
+    TEST_CUSTOMER_EMAIL: z.string().optional(),
+    TEST_CUSTOMER_PASSWORD: z.string().optional(),
+    DEFAULT_PRODUCT_ID: z.coerce.number().optional(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});

core/tests/tags.ts

@@ -0,0 +1,4 @@
+export const TAGS = {
+  // @writes-data is used to mark tests that modify data on the storefront without directly using the API.
+  writesData: '@writes-data',
+};