Principle:Teamcapybara Capybara Page Navigation

Knowledge Sources	Capybara README
Domains	Testing, Navigation
Last Updated	2026-02-12 00:00 GMT

Overview

A navigation pattern that directs the browser to a specified URL, resolving relative paths against a configured base and handling server port injection.

Description

Page Navigation is the act of directing the testing session to a specific URL. In acceptance testing, this is the starting point of nearly every test — before interacting with elements, the test must navigate to the relevant page. The navigation mechanism handles several concerns:

• Relative URL resolution — Relative paths are resolved against the configured app_host or the test server's URL
• Port injection — When always_include_port is enabled, the test server's port is inserted into the URL
• Error propagation — Any pending server errors are raised before navigation begins

Usage

Use this principle as the first step in any acceptance test that needs to interact with a web page. Call visit with a relative path (for local app testing) or an absolute URL (for remote testing).

Theoretical Basis

# Abstract navigation flow (not actual code)
raise_pending_server_errors
mark_session_as_touched

uri = parse(visit_uri)
base = parse(app_host || server_url)

if uri.relative? and base exists:
  uri = base.merge(uri)
  adjust_port_if_always_include_port

driver.navigate_to(uri)

Related Pages

Implemented By

• Implementation:Teamcapybara_Capybara_Session_Visit