QA Standards

// Breaks the moment a class name or DOM depth changes
await page.locator('div.container > ul > li:nth-child(3) > button.btn-primary').click();

// Survives most markup and styling changes, and reads like a spec
await page.getByTestId('checkout-submit').click();

// When there's no test-id, an accessible role query works just as well
await page.getByRole('button', { name: 'Submit order' }).click();

await page.click('#save-button');
await page.waitForTimeout(3000); // guessing how long the save takes
expect(await page.locator('.toast-success').isVisible()).toBe(true);

await page.click('#save-button');
await expect(page.locator('.toast-success')).toBeVisible(); // retries until it appears or times out

public sealed class SoftAssertions
{
    private readonly List<Exception> _failures = new();

    public void Check(Action assertion, string label)
    {
        try
        {
            assertion();
        }
        catch (Exception ex)
        {
            _failures.Add(new Exception($"{label}: {ex.Message}"));
        }
    }

    public void Verify()
    {
        if (_failures.Count == 0) return;
        var messages = string.Join("\n", _failures.Select(f => f.Message));
        throw new AssertionException($"{_failures.Count} soft assertion(s) failed:\n{messages}");
    }
}

[Test]
[Category("smoke")]
[Category("regression")]
public async Task Test_Login_ValidCredentials_RedirectsToDashboard()
{
    // Given I am on the login page
    await Page.GotoAsync(Config.BaseUrl + "/login");

    // When I submit valid credentials
    await Page.FillAsync("#email", Config.TestUser.Email);
    await Page.FillAsync("#password", Config.TestUser.Password);
    await Page.ClickAsync("#login-submit");

    // Then I land on the dashboard
    await Expect(Page).ToHaveURLAsync(new Regex(".*/dashboard"));
    await Expect(Page.Locator("h1")).ToContainTextAsync("Welcome back");
}

describe('Checkout flow', () => {
  beforeEach(() => {
    cy.login(Cypress.env('testUser')); // custom command, keeps setup out of each test
    cy.visit('/cart');
  });

  it('lets a signed-in user complete checkout with a saved card', () => {
    cy.get('[data-cy=checkout-button]').click();
    cy.get('[data-cy=saved-card-0]').click();
    cy.get('[data-cy=place-order]').click();

    cy.get('[data-cy=order-confirmation]').should('be.visible');
    cy.get('[data-cy=order-number]').invoke('text').should('match', /^ORD-\d+$/);
  });
});

// What It Tests: The checkout page shows an inline error when a declined card is submitted.
// Why It Matters: A silent failure here leaves the customer stuck with no path to complete an order.
[Test]
public async Task Test_Checkout_DeclinedCard_ShowsInlineError() { /* ... */ }

/// <summary>
/// Waits for the given locator to become visible, then clicks it. Retries the wait once if
/// the element detaches mid-check (common on pages that re-render after a websocket push).
/// </summary>
/// <param name="locator">The element to wait for and click.</param>
/// <param name="timeoutMs">Max time to wait before failing, in milliseconds.</param>
public async Task ClickWhenStableAsync(ILocator locator, int timeoutMs = 5000)
{
    // ...
}

/**
 * Polls the given selector until its text matches `expected` or the timeout elapses.
 *
 * @param {string} selector - CSS selector for the element to poll.
 * @param {string} expected - Exact text content to wait for.
 * @param {number} [timeoutMs=5000] - How long to keep polling before throwing.
 * @returns {Promise<void>}
 */
async function waitForText(selector, expected, timeoutMs = 5000) {
  // ...
}

## Summary
One sentence describing the defect.

## Environment
- Browser/App version:
- OS:
- Environment: (local / staging / production)

## Preconditions
What state the system needs to be in before reproducing.

## Steps to Reproduce
1.
2.
3.

## Expected Result


## Actual Result


## Severity / Priority
Severity: (blocker / critical / major / minor / trivial)
Priority: (P1 / P2 / P3)

## Evidence
Screenshots, screen recording, console logs, network traces.

## Additional Notes
Anything that doesn't fit above — workarounds, related tickets, frequency.