# DamageBDD Browser (CDP) Steps

Canonical HTML: <https://damagebdd.com/modules/cdp.html>



<a id="browser-cdp-steps"></a>

## Browser (CDP) Steps

These steps allow you to describe ****what a real user sees and does****
in a real web browser.

They are used to test:

-   Pages loading
-   Buttons and links
-   Text visibility
-   Layout and alignment
-   Mobile vs desktop behaviour
-   Visual bugs that users complain about

You do **not** need to understand browsers, JavaScript, or automation.

If you can explain the behaviour to another human,
you can write these steps.

****Important rule****

Every browser scenario must start by attaching to the browser.

****Example minimal structure****

```gherkin
Scenario: User opens homepage
  Given I attach CDP
  When I open "https://example.com"
  Then the page should contain "Welcome"
```


<a id="connecting-to-the-browser"></a>

## Connecting to the Browser


<a id="given-i-attach-cdp"></a>

### Given I attach CDP

Attaches DamageBDD to a real browser session.

This step:

-   Starts (or connects to) the browser
-   Prepares it for interaction
-   Must appear before **any** browser action

```gherkin
Given I attach CDP
```

Use this ****once per scenario****.


<a id="opening-pages"></a>

## Opening Pages


<a id="when-i-open-url"></a>

### When I open "{{URL}}"

Opens a web page and waits until it finishes loading.

```gherkin
When I open "https://example.com"
```

This behaves like:

-   Typing the address into the browser
-   Pressing Enter
-   Waiting until the page is ready


<a id="waiting-for-the-page"></a>

## Waiting for the Page

Modern websites load things gradually.
These steps help your scenario behave like a patient human.


<a id="and-i-wait-for-selector"></a>

### And I wait for "{{Selector}}"

Waits until a specific element appears on the page.

```gherkin
And I wait for "#login-button"
```

Use this:

-   After opening a page
-   After clicking a button
-   Before typing into a field


<a id="and-i-wait-until-the-page-contains-text"></a>

### And I wait until the page contains "{{Text}}"

Waits until visible text appears anywhere on the page.

```gherkin
And I wait until the page contains "Welcome back"
```

This prevents timing-related failures.


<a id="clicking-things"></a>

## Clicking Things


<a id="and-i-click-selector"></a>

### And I click "{{Selector}}"

Clicks an element using its identifier.

```gherkin
And I click "#submit"
```

Use this when you know the element identifier.


<a id="and-i-click-text-text"></a>

#### And I click text "{{Text}}"

Clicks a button or link by the text the user sees.

```gherkin
And I click text "Sign in"
```

This is usually the ****most readable**** way to click.


<a id="typing-and-keyboard-input"></a>

## Typing and Keyboard Input


<a id="and-i-type-text-into-selector"></a>

### And I type "{{Text}}" into "{{Selector}}"

Types text into a form field.

```gherkin
And I type "alice@example.com" into "#email"
```

This behaves like real typing.


<a id="and-i-press-enter"></a>

### And I press Enter

Presses the Enter key on the currently focused element.

```gherkin
And I press Enter
```

Useful for:

-   Login forms
-   Search boxes


<a id="reading-and-verifying-content"></a>

## Reading and Verifying Content


<a id="then-the-page-should-contain-text"></a>

### Then the page should contain "{{Text}}"

Checks that the given text is visible on the page.

```gherkin
Then the page should contain "Dashboard"
```

This verifies ****what the user actually sees****.


<a id="and-i-save-text-of-selector-as-name"></a>

### And I save text of "{{Selector}}" as "{{Name}}"

Reads visible text from the page and stores it for later use.

```gherkin
And I save text of "#order-id" as "OrderId"
```

You can later use this value in other checks.


<a id="viewport-and-screen-size"></a>

## Viewport and Screen Size

These steps simulate different devices.


<a id="given-i-set-viewport-to-width-x-height"></a>

### Given I set viewport to "{{Width}} x {{Height}}"

Simulates a screen of the given size.

```gherkin
Given I set viewport to 390 x 844
```

This is useful for:

-   Mobile testing
-   Tablet testing
-   Responsive layout checks


<a id="given-i-set-viewport-to-width-x-height-scale-scale"></a>

### Given I set viewport to "{{Width}} x {{Height}} scale "{{Scale}}"

Like the previous step, but with explicit scaling.

```gherkin
Given I set viewport to 1440 x 900 scale 1
```


<a id="layout-and-visual-correctness"></a>

## Layout and Visual Correctness

These steps verify ****visual alignment****, not code.

They catch bugs users complain about.


<a id="then-the-element-a-should-be-the-same-size-as-b"></a>

### Then the element "{{A}}" should be the same size as "{{B}}"

Ensures two elements are visually the same size.

```gherkin
Then the element "#logo-header" should be the same size as "#logo-footer"
```


<a id="then-the-element-a-should-be-the-same-size-as-b-within-px-px"></a>

### Then the element "{{A}}" should be the same size as "{{B}}" within "{{Px}}" px

Allows a small tolerance.

```gherkin
Then the element "#card1" should be the same size as "#card2" within 2 px
```


<a id="then-the-text-of-element-selector-should-be-center-aligned"></a>

### Then the text of element "{{Selector}}" should be center aligned

Checks that text is centered according to styling rules.

```gherkin
Then the text of element "#title" should be center aligned
```


<a id="then-the-text-of-element-selector-should-be-visually-centered-within-px-px"></a>

### Then the text of element "{{Selector}}" should be visually centered within "{{Px}}" px

Checks what the human eye perceives as centered.

```gherkin
Then the text of element "#title" should be visually centered within 2 px
```


<a id="alignment-between-elements"></a>

## Alignment Between Elements


<a id="then-the-elements-a-and-b-should-be-horizontally-aligned-at-left-center-right"></a>

### Then the elements "{{A}}" and "{{B}}" should be horizontally aligned at "{{left|center|right}}"

Checks horizontal alignment.

```gherkin
Then the elements "#price" and "#buy-button" should be horizontally aligned at center
```


<a id="then-the-elements-a-and-b-should-be-vertically-aligned-at-top-center-bottom"></a>

### Then the elements "{{A}}" and "{{B}}" should be vertically aligned at "{{top|center|bottom}}"

Checks vertical alignment.

```gherkin
Then the elements "#icon" and "#label" should be vertically aligned at center
```


<a id="overflow-and-screen-safety"></a>

## Overflow and Screen Safety

These steps prevent “broken on mobile” bugs.


<a id="then-the-page-should-have-no-horizontal-overflow"></a>

### Then the page should have no horizontal overflow

Ensures the page does not scroll sideways.

```gherkin
Then the page should have no horizontal overflow
```


<a id="then-the-page-should-have-no-horizontal-overflow-within-px-px"></a>

### Then the page should have no horizontal overflow within "{{Px}}" px

Allows a small tolerance.

```gherkin
Then the page should have no horizontal overflow within 1 px
```


<a id="then-the-element-selector-should-be-within-the-viewport-horizontally"></a>

### Then the element "{{Selector}}" should be within the viewport horizontally

Ensures an element stays on screen.

```gherkin
Then the element "#menu" should be within the viewport horizontally
```


<a id="console-javascript-error-verification"></a>

## Console & JavaScript Error Verification

These steps allow DamageBDD to deterministically verify that a page executed
without JavaScript errors and that expected console output occurred.

Unlike DOM assertions, these steps inspect the browser runtime itself via the
Chrome DevTools Protocol (CDP), ensuring that silent failures, uncaught
exceptions, and runtime errors are detected reliably.


<a id="then-the-page-must-have-no-javascript-errors"></a>

### Then the page must have no JavaScript errors

Asserts that no JavaScript runtime errors or uncaught exceptions occurred on the
page.

This step fails if:

-   Any \`Runtime.exceptionThrown\` event is observed
-   Any console message with level \`error\` is emitted

This guarantees that the page executed cleanly at the JavaScript runtime level,
not merely that it rendered successfully.


<a id="example"></a>

#### Example

```gherkin
Then the page must have no JavaScript errors
```


<a id="then-the-page-console-should-contain-log-text"></a>

### Then the page console should contain log "<text>"

Asserts that a console log message containing the given text was emitted.

This step is useful for:

-   Verifying application lifecycle milestones
-   Confirming feature flags or execution paths
-   Ensuring client-side initialization completed

The match is a substring match against the console message text.


<a id="example-2"></a>

#### Example

```gherkin
Then the page console should contain log "App started"
```


<a id="then-the-page-console-should-have-no-error-logs"></a>

### Then the page console should have no error logs

Asserts that the browser console contains no messages with level \`error\`.

This step is stricter than DOM-based checks and will fail the feature if any
JavaScript errors, failed imports, or runtime violations are logged.


<a id="example-3"></a>

#### Example

```gherkin
Then the page console should have no error logs
```


<a id="notes-on-console-verification"></a>

### Notes on Console Verification

-   Console logs are captured directly from the browser runtime via CDP
-   No DOM inspection or JavaScript injection is used
-   Logs are accumulated across the scenario execution
-   Errors cannot be hidden by try/catch or silent failures

This makes console verification suitable for:

-   Continuous integration
-   Economic verification (paid test execution)
-   Frontend regression detection
-   Trust-minimized browser validation


<a id="complete-example"></a>

## Complete Example

```gherkin
Scenario: Mobile login page behaves correctly
  Given I attach CDP
  And I set viewport to 390 x 844
  When I open "https://example.com/login"
  And I wait for "#email"
  And I type "alice@example.com" into "#email"
  And I type "secret" into "#password"
  And I click text "Sign in"
  Then the page should contain "Welcome back"
  And the page should have no horizontal overflow
```


<a id="how-to-think-as-a-bdd-writer"></a>

## How to Think as a BDD Writer

Ask:

-   What does the user see?
-   What feels broken if wrong?
-   What would support report say?

Write **that**.


<a id="summary"></a>

## Summary

CDP steps allow you to turn:

-   Visual expectations
-   Design rules
-   UX promises

into ****verifiable behaviour****.

If a human can complain about it,
DamageBDD can test it.