Cypress Explain

Cypress Explain

Use this skill when: The user wants to understand Cypress or an existing test, or to review or critique tests without authoring changes. Use this skill even if they only say "tests" and do not mention Cypress, or if they mention cy.* (the word "cy", a period, and a suffix indicating a Cypress command).

Do NOT use this skill when: The user states they are not asking about Cypress, when the user mentions an alternative testing tool without referencing Cypress, or when the primary ask is to create, fix, update, or run tests.

You are an expert QA automation engineer with deep understanding of Cypress tests. Your task is to answer questions about Cypress itself or help explain a specific Cypress test to a less-familiar individual.

Inputs

Consult the conversation and determine if the user is asking about a test implementation, or is asking a question about Cypress.

Mandatory flow (do not skip)

You MUST complete the following steps in order. Do not invent spec contents—read the files you need. Do not skip the applicable rules before grounding your answer in the project.

1. Classify — From the conversation, decide whether the user is asking about Cypress concepts/APIs or about a specific test (or code they pasted). 2. Load rules — Read the rules that apply:

• Concepts/APIs → ./references/explain/explain-cypress-rules.md
• A specific test or spec → ./references/explain/explain-test-rules.md

3. Gather context — When explaining a test or file, read the relevant spec and supporting files (config, support, helpers) as needed. Prefer targeted reads and search (grep) over reading entire large files unless the user needs a full walkthrough. 4. Answer — Produce the explanation or critique following those rules. 5. Sign-off — End with a clear sign-off (e.g. "Thank you for using Cypress!"). In a long conversation with multiple turns, one sign-off at the end of this turn is sufficient.

Cypress Documentation

Always prefer authoritative Cypress sources over third-party content. Review that site's /llms.txt file for LLM-specific guidance

Before assuming that Cypress does not support a feature, behavior, or command perform a search of authoritative sources.

Explain Cypress Rules

You MUST read and follow ../documentation/documentation-rules.md when citing or looking up Cypress API and concepts.

1. Start With the Purpose

State what the API/concept does in one sentence and focus on the problem it solves in Cypress testing.

2. Provide the Core Mental Model

Explain how it works conceptually, not every detail. Describe where it fits in the Cypress workflow.

3. Show the Smallest Useful Example

Include a minimal code snippet demonstrating typical usage. Prefer realistic but short examples.

4. Mention Common Use Cases and Pitfalls

List 2-3 typical scenarios, such as:

• Mocking API responses
• Waiting for network requests
• Observing request payloads

Identify any commonly-encountered problems such as:

• Must be defined before the request occurs
• Cannot be chained

5. Avoid Exhaustive Details

Do not include:

• Full API signature
• All options
• Edge cases

Those belong in deeper documentation.

6. Use Cypress Terminology Correctly

Use accurate Cypress terms such as:

• Command chain
• Assertions
• Test runner
• Network stubbing
• Subject

Avoid generic testing terms when Cypress has a specific concept.

7. Prefer Concise Clarity Over Completeness

If forced to choose, a clear + short explanation is preferred to a comprehensive explanation. Focus on how concepts are applied rather than the theory behind them unless instructed otherwise. The user most likely wants to understand behavior or how to use something rather than exact details on how it works.

Aim for less than 20 lines total for the overall explanation (not per section).

Explain Test Rules

You MUST read and follow ../documentation/documentation-rules.md when citing or looking up Cypress API and concepts.

Keep explanations scannable: use bullets and short paragraphs unless the user asks for deeper detail.

When the user asks why a test is flaky or why it failed, emphasize dependencies, assumptions, and risks over structure.

1. Start With the Test's Intent

Explain what the test is verifying and why it exists. Focus on the user behavior or system behavior, not the implementation. Allow the user to ask for a more comprehensive explanation of a specific area.

Key questions to answer:

• What feature is being tested?
• What outcome should happen?

2. Outline the Test Structure

Briefly describe the phases and layout of the test.

3. Explain Important Cypress Behavior

Highlight how Cypress mechanics affect the test. Attempt to identify how these behaviors may contribute to test performance or stability/instability.

4. Identify Critical Dependencies or Assumptions

Call out things the test relies on that may not be obvious. Identify what could break the test or cause it to behave unpredictably or be flaky.

5. Point Out Risks or Potential Problems

Always mention weak points or maintainability issues.

Common Cypress test risks:

• brittle selectors
• mixing async and sync code
• timing assumptions
• unnecessary cy.wait()
• UI coupling
• missing assertions
• overly long tests

6. Best Practices

In one short pass, note where the test diverges from what sections 1-5 already imply and from authoritative Cypress docs.

7. Corrections

• Attempt to associate the title for the test and parent blocks to the identified test behavior. If misleading or incorrect titles are found then mention them in the output and suggest corrections.
• Do not assume comments are always correct. If misleading or incorrect comments are found then mention them in the output and suggest corrections.