From 806c4868f85f61e7b7ce3f406071b3cb6f72734c Mon Sep 17 00:00:00 2001 From: Donald Merand Date: Fri, 2 Oct 2026 15:27:16 -0400 Subject: [PATCH] Clarify contributor and agent guidance from PR feedback --- .agents/automated-tasks/performance.md | 4 +- .agents/automated-tasks/security.md | 2 +- AGENTS.md | 51 +++++++++++++++----------- docs/README.md | 4 +- docs/cli-kit/command-guidelines.md | 4 ++ docs/cli/conventions.md | 20 +++++++++- docs/cli/cross-os-compatibility.md | 6 ++- docs/cli/debugging.md | 2 + docs/cli/error_handling.md | 6 ++- docs/cli/get-started.md | 4 +- docs/cli/performance.md | 8 ++++ docs/cli/testing-strategy.md | 38 +++++++++++++------ 12 files changed, 105 insertions(+), 44 deletions(-) diff --git a/.agents/automated-tasks/performance.md b/.agents/automated-tasks/performance.md index 012449b1306..6a159cf332f 100644 --- a/.agents/automated-tasks/performance.md +++ b/.agents/automated-tasks/performance.md @@ -12,7 +12,7 @@ Every branch you create MUST start with `performance-` (e.g. `performance-memoiz - Do exactly ONE thing per PR. - Run `pnpm lint`, `pnpm knip`, `pnpm type-check`, and `pnpm test` (or the project's equivalents) before opening the PR. - Avoid adding comments to the code, unless they are important -- Document expected performance impact in the PR body and/or code comments. +- Document expected performance impact and reproducible measurements in PR evidence, not code comments. - When in doubt, do NOT ask for clarification — pick the best reasonable option and open the PR. 🚫 **Never do:** @@ -106,7 +106,7 @@ Every branch you create MUST start with `performance-` (e.g. `performance-memoiz - Add comments explaining WHY the optimization is correct and safe. - Preserve existing functionality exactly. - Consider edge cases. - - Add benchmark/perf metrics in comments where useful. + - Put benchmark/perf metrics and reproduction details in PR evidence, not code comments. - Do NOT add a changeset file. - Do NOT add any extra markdown files. diff --git a/.agents/automated-tasks/security.md b/.agents/automated-tasks/security.md index 727bbdfabc1..a5bf496b9e7 100644 --- a/.agents/automated-tasks/security.md +++ b/.agents/automated-tasks/security.md @@ -125,7 +125,7 @@ Every branch you create MUST start with `security-` (e.g. `security-sanitize-inp - Replace a weak hash or `Math.random()` with a secure primitive - Add an authorization check to an endpoint or command - Replace string concatenation with a parameterized query / safe builder -- Resolve and normalize a path before using it (defeats `..` traversal) +- Verify restricted paths stay within the allowed root using established helpers and the operation's ancestor/symlink policy; normalization alone does not prove containment - Remove a hardcoded secret and load it from env/config - Add a size or length cap to prevent DoS - Tighten an overly permissive default (CORS, file mode, scope) diff --git a/AGENTS.md b/AGENTS.md index 809b20882d9..d96adc53912 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,10 @@ # Agent Instructions -As a Principal Developer, the highest ranking engineer at our company, you are tasked with creating clear, readable code in TypeScript. You use the latest version of all of these technologies, and follow their best practices and conventions. +Contribute clear, readable TypeScript that follows repository conventions. Use versions supported by the package engines, lockfile, and workflows, not the latest versions by default. Match your planning to the complexity of the task. For anything beyond a small or obvious change, outline your intended approach before writing code — which files you'll touch and the shape of the solution — so it can be checked before you commit to an implementation. Keep this to a few sentences or bullets. For trivial changes, skip straight to the implementation. -You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning; but you always admit when you don't know the answer. +Give accurate, factual answers. State uncertainty and material trade-offs; do not guess. Remember the following important mindset when providing code, in the following order: - Adherence to conventions and patterns in the rest of the codebase @@ -21,7 +21,7 @@ Adhere to the following guidelines in your code: - Fully implement all requested functionality - Leave no TODOs, FIXMEs, placeholders or missing pieces. - Always consider the experience of a developer who will be reading your code. -- Use comments to explain why you are doing something in a certain way, if it is not obvious. If unsure, leave a comment. +- Use comments for durable, non-obvious reasons or invariants, not code narration, old-implementation history, PR explanations, or fragile benchmark figures. Preserve public JSDoc. - Employ descriptive, human-readable variable and function/const names. - Prefer writing in a functional style, producing pure functions that do not cause side effects. - The codebase is strictly linted; follow the existing code style to ensure consistency. @@ -40,7 +40,7 @@ Adhere to the following guidelines in your code: - Write a concise description, explaining the problem and the high-level approach. Include implementation details only when they help reviewers understand a decision or tradeoff. Avoid repeating what is clear from the diff. Example for the WHAT section: "Refresh expired credentials before retrying the requests, so users can continue without signing in again". - Remove empty sections and hidden comments. - Do not mark checklist items as completed (except the changelog one if added). -- In "How to test your changes?" only include CLI commands to test locally, do not add commands to run tests or other checks. +- In "How to manually test your changes?", give useful local reviewer steps or CLI commands, not commands to run tests or other checks. This does not require live-state-changing commands. ## Changesets @@ -56,29 +56,36 @@ If the change is not ready to be public, do not add a changeset. ## Further reading +Read the guides that apply to your task. + ### CLI -- [docs/README.md](docs/README.md) -- [docs/cli/architecture.md](docs/cli/architecture.md) -- [docs/cli/conventions.md](docs/cli/conventions.md) -- [docs/cli/cross-os-compatibility.md](docs/cli/cross-os-compatibility.md) -- [docs/cli/debugging.md](docs/cli/debugging.md) -- [docs/cli/eslint-rules.md](docs/cli/eslint-rules.md) -- [docs/cli/faq.md](docs/cli/faq.md) -- [docs/cli/get-started.md](docs/cli/get-started.md) -- [docs/cli/naming-conventions.md](docs/cli/naming-conventions.md) -- [docs/cli/performance.md](docs/cli/performance.md) -- [docs/cli/testing-strategy.md](docs/cli/testing-strategy.md) -- [docs/cli/troubleshooting.md](docs/cli/troubleshooting.md) +- [Docs index](docs/README.md): find related guides and the reasons behind past decisions. +- [Architecture](docs/cli/architecture.md): choose the right package for new or moved code. +- [Conventions](docs/cli/conventions.md): follow shared patterns for modules, state, resource cleanup, and file IO. +- [Cross-OS compatibility](docs/cli/cross-os-compatibility.md): avoid OS-specific failures when working with paths, processes, and dependencies. +- [Debugging](docs/cli/debugging.md): investigate failures with the debugger and check diagnostics for credential leaks. +- [ESLint rules](docs/cli/eslint-rules.md): understand local lint rules for command flags and environment variables. +- [FAQ](docs/cli/faq.md): understand the choice of TOML for configuration files. +- [Get started](docs/cli/get-started.md): set up the repository and run the CLI against a local project. +- [Naming conventions](docs/cli/naming-conventions.md): use reserved command names, flags, and short forms consistently. +- [Performance](docs/cli/performance.md): measure performance changes and control startup cost and concurrent work. +- [Testing strategy](docs/cli/testing-strategy.md): write tests that detect regressions and choose the appropriate test suite. +- [Troubleshooting](docs/cli/troubleshooting.md): resolve known Vitest mocking problems. +- [Contributing](CONTRIBUTING.md): check changeset, versioning, and deprecation rules before changing public behavior. +- [JSON output contracts](docs/cli/json-output.md): check result and error contracts before changing `--json` output. +- [CLI pre-submit CI](.agents/skills/cli-pre-submit-ci/SKILL.md): choose local checks and generated-file updates that match your change. ### CLI kit -- [docs/cli-kit/command-guidelines.md](docs/cli-kit/command-guidelines.md) -- [docs/cli-kit/errors.md](docs/cli-kit/errors.md) -- [packages/cli/README.md](packages/cli/README.md) +- [Command guidelines](docs/cli-kit/command-guidelines.md): design commands and flags with consistent structure, defaults, and dependencies. +- [Error handling](docs/cli/error_handling.md): choose error types, report failures, and retry only known recoverable conditions. +- [Command reference](packages/cli/README.md): check documented command usage, flags, and examples. ### UI kit -- [docs/cli-kit/ui-kit/contributing.md](docs/cli-kit/ui-kit/contributing.md) -- [docs/cli-kit/ui-kit/guidelines.md](docs/cli-kit/ui-kit/guidelines.md) -- [docs/cli-kit/ui-kit/readme.md](docs/cli-kit/ui-kit/readme.md) +- [Contributing to UI Kit](docs/cli-kit/ui-kit/contributing.md): follow component design and testing patterns when changing UI Kit. +- [Content guidelines](docs/cli-kit/ui-kit/guidelines.md): keep prompts, progress messages, and error text consistent. +- [Using UI Kit](docs/cli-kit/ui-kit/readme.md): use existing prompt and output APIs for consistent terminal UI. + +Follow the check requirements of the active automation task. diff --git a/docs/README.md b/docs/README.md index 5cc37bf77e5..c196bacfece 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,11 +2,11 @@ # Contributors documentation -This page contains resources for people interested in contributing to this repository or developing a [plugin](./plugins.md). +This page contains resources for people interested in contributing to this repository or developing a [plugin](./cli/conventions.md#2---plugins-eg-shopifyapp). ## CLI -The Shopify CLI is a tool for merchants, partners, and developers to interact with the platform from their terminals. Its technical design allows adding features horizontally through [**plugins**](#plugins) that build on [**cli-kit**](#cli-kit). [@shopify/theme](https://www.npmjs.com/package/@shopify/theme), [@shopify/app](https://www.npmjs.com/package/@shopify/app), [@shopify/cli-hydrogen](https://www.npmjs.com/package/@shopify/cli-hydrogen) are examples of plugins to develop themes, apps, and hydrogen storefronts, respectively. +The Shopify CLI is a tool for merchants, partners, and developers to interact with the platform from their terminals. Its technical design allows adding features horizontally through [**plugins**](./cli/conventions.md#2---plugins-eg-shopifyapp) that build on [**cli-kit**](#cli-kit). [@shopify/theme](https://www.npmjs.com/package/@shopify/theme), [@shopify/app](https://www.npmjs.com/package/@shopify/app), [@shopify/cli-hydrogen](https://www.npmjs.com/package/@shopify/cli-hydrogen) are examples of plugins to develop themes, apps, and hydrogen storefronts, respectively. The list below contains valuable resources for people interested in contributing to the CLI project in this repository. diff --git a/docs/cli-kit/command-guidelines.md b/docs/cli-kit/command-guidelines.md index 5973e6f9811..54b6884b92e 100644 --- a/docs/cli-kit/command-guidelines.md +++ b/docs/cli-kit/command-guidelines.md @@ -34,6 +34,10 @@ Flags should be semantically meaningful. When in doubt, optimize for clarity, no | :------------- | :------------- | :------------- | :------------- | | ❌ | Don't: | rsync --owner | Because it’s unnecessarily terse, it’s ambiguous whether this flag means “preserve the current owner” or “assign ownership”.| +For changed dependent or defaulted flags, test omitted, explicit, default, valid, and invalid combinations through actual command parsing. A default value does not prove explicit presence; choose dependency declarations according to the intended behavior, not an “always `dependsOn`” rule. + +Command result, error, and output changes follow the existing [JSON contracts](../cli/json-output.md) and [error handling](../cli/error_handling.md). + ## Aliases / shortcuts for flags As a general rule, don't create shortcuts for flags. Create single-letter short-form flag aliases only if the flag is frequently or repetitively used in day-to-day interactive development work. diff --git a/docs/cli/conventions.md b/docs/cli/conventions.md index fd17816ff49..5f2f668393a 100644 --- a/docs/cli/conventions.md +++ b/docs/cli/conventions.md @@ -19,6 +19,8 @@ import { joinPath } from "node:path" ``` +Prefer imports from the actual owner over forwarding-only internal wrappers. Preserve deliberate public package entrypoints and index modules that orchestrate behavior; this is not an index-file ban or a package-wide migration. + ### 1.2 - Modules free of side effects Modules must not perform any side effect when they are imported. For example, doing an IO operation at the root of the module: @@ -47,6 +49,8 @@ Instead, you can: - **Store the state in the system.** It leads to IO operations, which impact the performance, but because the state is often little, it's preferred over an unreliable experience. - **Load and pass the state down:** Load the state upfront, for example, an in-memory representation of the project the CLI is interacting with, and pass it down through function arguments. +For necessary caches or remembered state, define applicable identity, project, store, and environment inputs, lifetime, invalidation, mutation, and unusable-state fallback. Derive auth-sensitive identity from the session or token authorizing the request, not an unrelated global account getter. Do not persist raw credentials in keys; token rotation can cost a cache miss. Test the actual cached path, changed context, and existing mutation/fallback branches. An optional auth lookup can return absence and use normal valid authentication; do not suppress unrelated errors. + ### 1.4 - Functions that don't mutate the input arguments When designing the implementation of a function, refrain from mutating objects that the function receives as arguments. Function callers might design their business logic to assume that the arguments they pass to other functions are not mutated. If they do, the integration might not behave as expected, manifesting as bugs on the user side. @@ -64,6 +68,20 @@ but considering the size of the state, the CLI deals with, and optimizations Jav it shouldn't be an issue. +### 1.5 - Resource lifetime + +When starting or changing watchers, servers, listeners, child processes, async tasks, or temporary resources, name the owner of completion, rejection, and cleanup on success, failure, cancellation, and repeated invocation. Observe started promise failures promptly. `Promise.race` observes its inputs but does not dispose losing resources; timeout settlement is not cleanup. Wait for owned processes and descendants to stop before deleting their files. Preserve scoped [filesystem](../../packages/cli-kit/src/public/node/fs.ts) and [process](../../packages/cli-kit/src/public/node/system.ts) helpers, deliberate background owners, and [UI cancellation/cleanup](../cli-kit/ui-kit/contributing.md#handling-user-input). + +### 1.6 - Input and artifact IO + +Reject locally invalid inputs or flag combinations before authentication, network access, or persistent writes where local validation is available. Validate the representation the parser, executor, or writer consumes. For restricted filesystem access, normalization alone is not containment: use established helpers and the allowed-root, ancestor, and symlink policy. Preserve legitimate paths. + +Artifact producers and consumers must agree on format, encoded byte bounds, and applicable encoding. Validate before replacing a valid artifact. Tie confirmation, file, size, and upload to the same serialized bytes. On later failure, clean only owned resources or provide safe recovery. Preserve the original error and pre-existing user content. + +### 1.7 - Optional observability + +Optional diagnostics or telemetry must not hide successful results, prevent credential persistence, prompt or authenticate unexpectedly, or mutate project files. Keep passive reads bounded, catches narrow, and background ownership explicit. Required security validation, audit, billing, or product-contract work is not automatically optional. + ## 2 - Plugins (e.g `@shopify/app`) ### 2.1 - Model-command-service (MCS) @@ -106,7 +124,7 @@ app/ ##### Definition and responsibilities Services represent **reusable units of business logic.** -They export a default function representing the service and might contain additional internal combined functions to form the service. +They export a named function representing the service and might contain additional internal combined functions to form the service. Each command must have a service representing it, and we might have additional services that don't map to commands. Note that services are decoupled from commands, diff --git a/docs/cli/cross-os-compatibility.md b/docs/cli/cross-os-compatibility.md index 9d2643a2799..370c3e277ef 100644 --- a/docs/cli/cross-os-compatibility.md +++ b/docs/cli/cross-os-compatibility.md @@ -18,6 +18,8 @@ When implementing business logic that interacts with the OS, for example doing I ### Manual testing +Use the Node and PNPM versions required by the repository. See [setup requirements](get-started.md#requirements). + Please don't assume that a successful working workflow in the OS in which it was developed will yield success in other OSs. **We strongly recommend manually testing the workflow in other OSs**. #### Linux @@ -25,9 +27,9 @@ Please don't assume that a successful working workflow in the OS in which it was After installing Ubuntu 22 then run: - `sudo apt-get update && sudo apt-get -y upgrade` -- `curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -` +- `curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -` - `sudo apt-get install -y git nodejs` -- `curl -fsSL https://get.pnpm.io/install.sh | sh -` +- `curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=10.11.1 sh -` You can clone the CLI repository: diff --git a/docs/cli/debugging.md b/docs/cli/debugging.md index 397a3a78cf7..edddace11b6 100644 --- a/docs/cli/debugging.md +++ b/docs/cli/debugging.md @@ -1,5 +1,7 @@ ## Debugging +New diagnostics and support artifacts must not expose credentials. Redact before truncation, including parse-failure paths. Inspect relevant stderr, events, files, and artifacts, not only stdout; keep useful nonsecret facts. Existing redaction does not prove that content has no paths or code if that is the disclosure promise. Escalate privacy/compatibility choices instead of silently removing stable legacy fields. See [JSON contracts](json-output.md) and [safe error details](error_handling.md#fatal-errors-in-json-output). + The CLI works well with VS Code's built-in debugger -- feel free to use breakpoints across the constituent packages and Typescript files. The current recommended practise for testing is to run the "Javascript Debug Terminal" command in VS Code. This launches a terminal where the debugger is automatically attached to any node process. If you there execute `pnpm run shopify` (build and run) or `pnpm run shopify:run` (just run), the CLI will be launched and you can provide any desired arguments for the feature you are testing. As the debugger is automatically attached, any breakpoints you've set will be triggered when they're encountered. diff --git a/docs/cli/error_handling.md b/docs/cli/error_handling.md index 073cb136867..ede0a668a31 100644 --- a/docs/cli/error_handling.md +++ b/docs/cli/error_handling.md @@ -25,7 +25,7 @@ The CLI defines `FatalError` and several subtypes of `FatalError`. Within the CL * Use `AbortSilentError` for user-initiated cancellations * Use `ExternalError` when external commands fail -Please, **don't** use the global `process.exit` and `process.abort` APIs. Also, don't `try {} catch {}` abort errors. If you need to communicate the failure of an operation to the caller (e.g., a 5xx HTTP response), use the result type from the following section. +Please, **don't** use the global `process.exit` and `process.abort` APIs. Do not catch abort errors indiscriminately to continue anyway. Catch only a named domain condition that the operation explicitly expects and can recover from, such as `StoreNotFoundError` while waiting for a newly created store. Rethrow unrelated failures, including ordinary auth/session failures, and preserve user cancellation. If you need to communicate the failure of an operation to the caller (e.g., a 5xx HTTP response), use the result type from the following section. #### AbortError @@ -197,6 +197,10 @@ result.valueOrBug() // throws! result.mapError((error) => new FatalError("other error")) ``` +## Narrow recovery and retries + +Use stable API codes or domain state for retry decisions when supplied, not broad or localized message matches. Test false-positive messages and unrelated failures. When no structured signal exists, retain justified narrow string handling and test the producer-to-consumer contract; the conservative OS/environment backstop below remains valid. + ## Environmental Issue Detection The CLI has a unique pattern for classifying non-fatal errors as environment issues through `shouldReportErrorAsUnexpected` and `errorMessageImpliesEnvironmentIssue`. diff --git a/docs/cli/get-started.md b/docs/cli/get-started.md index 259eabda141..a84d18c8e81 100644 --- a/docs/cli/get-started.md +++ b/docs/cli/get-started.md @@ -7,8 +7,8 @@ This wiki contains documentation that's useful for contributors of the project. If you'd like to contribute to this project, the following system dependencies need to be present in the environment. -- [Node](https://nodejs.org/en/) (v20.10 or higher) -- [PNPM](https://pnpm.io/) (v10) +- [Node](https://nodejs.org/en/): use a supported version that meets the `engines` requirements in [CLI](../../packages/cli/package.json), [app](../../packages/app/package.json), and [CLI Kit](../../packages/cli-kit/package.json). +- [PNPM](https://pnpm.io/): use the version in the root [`packageManager`](../../package.json) field. ### Set up diff --git a/docs/cli/performance.md b/docs/cli/performance.md index 0af0c53b308..f2bf5672023 100644 --- a/docs/cli/performance.md +++ b/docs/cli/performance.md @@ -27,6 +27,10 @@ The visual representation might feel intimidating when you first open it, so we We **strongly recommend** reading [this series of blog posts](https://marvinh.dev/blog/speeding-up-javascript-ecosystem/) on debugging to get more familiar with the process. +Measure the effect of the change before you claim a performance improvement. Choose measurements that fit the change's size and risk. Preserve authentication, fallback, and operating-system behavior. + +Passing tests do not prove a speed increase. Put measurement commands and results in the PR, not in code comments. + ## Principles ### Dependencies will most likely have a cost @@ -38,6 +42,8 @@ When NPM dependencies are used in SPAs, they are tree-shaken through bundling to - If the dependency is large and uses ESM, use dynamic imports to import it. Note that it'll make the dependent modules' APIs asynchronous, but it'll be improved once this [TC39 proposal](https://github.com/tc39/proposal-defer-import-eval) lands. - As a **last resource**, if a dependency is a bottleneck, you can use its CJS version or dynamically import it when needed using `await import("my-dependency")`. +A dynamic import still takes time to load the dependency. For an optional feature, check whether it is needed before you import a large dependency. Small helpers can use static imports. + ### Use concurrency whenever possible When writing code as a sequence of statements, some of which are `awaited` because we are invoking `async` functions, we might end up with logic whose performance has a lot of room for improvement. Take the following example: @@ -49,6 +55,8 @@ async function slowFunction() { } ``` +Run operations at the same time only if they do not depend on each other. Preserve required order, partial results, error handling, and [cleanup](conventions.md#15---resource-lifetime). Limit how many requests run at the same time when service limits or local resources require it. + Since both functions don't depend on each other, we are not using the runtime most efficiently. Instead, consider running them concurrently with the help of the `Promise.all` API: ```js diff --git a/docs/cli/testing-strategy.md b/docs/cli/testing-strategy.md index c28615ece69..a8c4ed6d1c6 100644 --- a/docs/cli/testing-strategy.md +++ b/docs/cli/testing-strategy.md @@ -30,14 +30,34 @@ test("loads the app", async () => { }) ``` -Tests can be run with `pnpm test` for the Vitest suite, `pnpm test:watch` for watch mode, or `pnpm test:e2e` for the Playwright end-to-end suite. If you want to run a single unit test, pass the path to the file as argument: +- `pnpm test`: run the Vitest suite. +- `pnpm exec vitest`: run Vitest in watch mode. +- `pnpm test:e2e`: run the Playwright end-to-end suite. + +To run one unit test, pass its file path: ``` pnpm test path/to/my.test.ts ``` +### Test the behavior that can fail + +A regression test must fail when the bug is present. Use input that reproduces the bug. Check the result that matters to the user or caller. + +- Run the code path affected by the change. Mocks must not replace the behavior the test needs to check. +- Keep tests that check command parsing and how commands call services. +- For encoded data, use an independent expected value when a shared encoder could hide a bug. +- Check that secrets or unwanted actions are absent when that is part of the requirement. + +If a test must wait for async work, use a readiness or completion signal. Clean up tasks, listeners, and temporary resources after the test. Use a short, bounded delay only when no signal is available. + +Confirm that the test fails when the fix is removed or the faulty behavior is restored. Use checks that fit the risk of the change. No mutation-testing framework or complete test matrix is required. + +See [JSON output tests](json-output.md#test-a-new-command) and [UI tests](../cli-kit/ui-kit/contributing.md#testing-components). + ### Filesystem I/O and temporary directories -If the subject under test performs filesystem I/O, prefer using a temporary directory instead of stubbing the filesystem. Create a temporary directory whose lifecycle is tied to the lifecycle of the test: + +For filesystem tests, use real files in a temporary directory. The test must delete the directory after use, including when it fails: ```ts import {file, path} from "@shopify/cli-kit" @@ -63,11 +83,9 @@ test("writes", async () => { > :exclamation: **Tests and promises** > -> If inside your tests you call asynchronous functions and forget to `await` you might end up with false positives. Therefore we recommend that after writing your tests that you always make it fail. +> Await the async operation that your assertion depends on. Otherwise, the assertion can run before the operation completes. -> :exclamation: **Vitest is in beta** -> -> Vitest is still in beta, so you might encounter issues while using it. If you come across any, check out [our troubleshooting page](/contributors/troubleshooting) or the [list of issues](https://github.com/vitest-dev/vitest/issues) on the project's repository. +For Vitest problems, see [our troubleshooting page](troubleshooting.md) or the [Vitest issues](https://github.com/vitest-dev/vitest/issues). ### Resources - [Vitest API](https://vitest.dev/api/) @@ -77,10 +95,8 @@ test("writes", async () => { End-to-end tests live under `packages/e2e` and are implemented using [Playwright](https://playwright.dev/). They test full user journeys by invoking the CLI and verifying outputs. Run them with `pnpm test:e2e`. -## Github Actions -Before being able to marge a PR, it must pass all CI checks executed in Github Actions. +## GitHub Actions -The jobs will detect what packages have changed in that PR and execute the tests only for those. -If you want to execute all the tests for all the packages you can manually schedule a workflow through `Actions -> shopify-cli -> Run workflow` +Use [the PR workflow](../../.github/workflows/tests-pr.yml) and [CLI pre-submit CI guide](../../.agents/skills/cli-pre-submit-ci/SKILL.md) to choose local checks and generated files. Follow the check requirements of the active automation task. -There you can choose the branch and a custom command to send to `nx`, by default the command is `affected` which means only affected packages will be run. You can use `run-many --all` to run all packages instead. +Repository settings determine which checks block a merge. A passing job proves only what that job checked. Jobs with `continue-on-error` can fail without failing the workflow.