Repository navigation
Description
Help me set up Endform so this repository's Playwright tests run on GitHub Actions against the Vercel preview of every pull request.
Endform is a drop-in replacement for the Playwright test runner: npx endform@latest test replaces playwright test and runs every test on its own machine. The tests stay as they are; setup adds a few settings to playwright.config.ts.
Guide me through the setup, make the changes you can, and ask me when you need information or an action from me. Ask when something is unclear instead of guessing, and tell me what you changed at each step.
- Find the Playwright project:
- If this repository already has one, use it and leave its tests as they are.
- If not, add
@playwright/testas a dev dependency, createplaywright.config.tswithtestDirset to./tests,forbidOnly: !!process.env.CI, and a single chromium project, and addtest-results/andplaywright-report/to.gitignore. Leave outworkersandreportersettings; Endform handles those. Then ask which three or four pages or flows matter most, and write one small test for each with stable locators such as roles and labels. Then check they pass withnpx endform@latest test --organization-id YthnM7vx. - In both cases, do not install browsers; Endform provides them. Run Endform from the directory that contains
playwright.config.ts, and in CI set the job's working directory there.
- Merge these settings into
playwright.config.tsand keep everything else:export default defineConfig({ fullyParallel: true, retries: 2, use: { baseURL: process.env.BASE_URL || "<the URL the suite uses today>", trace: "retain-on-failure", }, });
fullyParallel: truelets Endform run every test in parallel. Endform only readsfullyParallelper project, sotest.describe.configure({ mode: "serial" })andtest.describe.serialdo not keep tests together. If tests in a file sharebeforeAllstate or worker fixtures, move those files to a project withfullyParallel: falseand exclude them from the other projects withtestIgnore. Each file in that project then runs on one machine, in order. A retry reruns only the failed tests, so setup that one test leaves for the next belongs inbeforeAllor a fixture.- Endform retries only as often as
retriesallows. Keep the value if the config already sets one. - If the config starts a dev server through
webServer, leavewebServerandbaseURLas they are, unless the tests will run against Vercel previews. Otherwise readbaseURLfromBASE_URL, falling back to the URL the suite uses today, and if none is in the repo, ask whether to add awebServerthat starts the local dev server or to use a deployed URL such as staging or a Vercel preview. trace: "retain-on-failure"gives failed tests a trace in the Endform dashboard.
- Some suites need an Endform config for one of these reasons. Endform transfers imported files and the environment variables tests reference automatically, so do not add one up front. Add the narrowest setting that fixes an observed failure.
npx endform@latest test --debug --organization-id YthnM7vxshows which files and environment variables are sent to the runners:- a test reads files without importing them:
additionalFiles(globs). - a test needs environment variables it does not reference through
process.env:environmentVariables(regexes). - the tests target a localhost server that is not started through
webServer:proxyNetworkHosts: ["<loopback>"], which sends that traffic through the local machine. - tests fail or time out under load because the target cannot handle many tests at once, such as a local server, a staging database, or a payment sandbox:
concurrentTestLimits, for example[{ scope: "within-suite-run", limit: 40 }], or withlabel: "tag:@checkout"to limit only the tests that hit the bottleneck. - To add a setting, use the repository's existing Endform config, in this directory or a parent up to the repository root.
- Convert a legacy
endform.jsoncorendform.jsonwithnpx endform@latest migrate-configfirst, since a newendform.config.tsnext to it silently replaces it. - If there is none, add
endformas a dev dependency, createendform.config.tsnext toplaywright.config.tsusingdefineEndformConfigfrom"endform", and read https://endform.dev/docs/_llms-txt/run-and-configure-endform.txt for its options.
- a test reads files without importing them:
- The tests run against the Vercel preview, so
baseURLmust readprocess.env.BASE_URL, even whenwebServerstarts a dev server. Then startwebServeronly whenBASE_URLis not set, so local runs keep working. - Add the
endformdev/actions/run-with-vercel-deploymentaction withset-url-env-var: BASE_URLbeforenpx endform@latest test, as shown in the Vercel section of https://endform.dev/docs/_llms-txt/github-actions-ci-and-vercel.txt. Endform reports on the Vercel check only when the workflow uses this action.- If a workflow already runs
playwright test, directly or through a package script such aspnpm test:e2e, add the action before it and replace that command withnpx endform@latest test, leaving the package script as it is. Keep the other steps, and drop what Endform replaces: browser installs and caches,--shardmatrix jobs, and the job that merges their blob reports. Otherwise add a workflow as the docs show. - The workflow must run on pull requests, since previews exist only for them.
- Take the Vercel project name from
.vercel/project.json, or ask for it. - The action authenticates only through the Endform GitHub App with OIDC: add
id-token: writeto the workflow's permissions and keepcontents: read, since listing any permission removes the ones not listed. Do not add an API key.
- If a workflow already runs
- Make sure the Endform GitHub App and Vercel are connected with
npx endform@latest connect github --organization-id YthnM7vxandnpx endform@latest connect vercel --organization-id YthnM7vx. Each says so when the integration is already connected. Otherwise it prints a URL where the install is finished in the browser and tells you which command to run next, so show the URL and follow its output until it is connected. These commands need a login: if one says you are not logged in, runnpx endform@latest login, show the URL it prints, follow its output until the login completes, then run the command again. - If the tests read other environment variables, such as app credentials, list them and ask for them to be added as GitHub Actions secrets. Reference them in the workflow, never write their values.
- Do not commit or push. When you are done, tell me what is working, list the changed files and ask me to commit and push them so CI runs Endform. Explain anything I still need to do. If the workflow has not run yet, say that setup is ready but still needs verification.
Do not add API keys or secrets to the repository.
These steps cover the whole setup, so do not read the docs up front. Only if a command fails in a way these steps do not explain, read https://endform.dev/docs/llms.txt.
Activity