Implementation:Teamcapybara Capybara Node Base Synchronize

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

Overview

Concrete tool for auto-waiting on asynchronous page changes provided by Capybara::Node::Base#synchronize.

Description

Node::Base#synchronize implements a retry loop using Capybara::Helpers.timer. It guards against re-entrant calls via session.synchronized flag. On each retry, it checks for server errors, verifies the timer hasn't expired, sleeps for default_retry_interval, and optionally calls reload on the node. It raises Capybara::FrozenInTime if Time.now appears stuck (for detecting mocked clocks).

Usage

This method is called internally by all finders and matchers. Direct use is rare but possible when wrapping custom retry logic.

Code Reference

Source Location

Repository: capybara
File: lib/capybara/node/base.rb
Lines: L76-103

Signature

def synchronize(seconds = nil, errors: nil)
  # @param seconds [Integer, nil] Max wait time (default: session_options.default_max_wait_time)
  # @param errors [Array<Exception>] Exception types that trigger retry
  #   (default: driver.invalid_element_errors + [Capybara::ElementNotFound])
  # @yield Block to execute with retry
  # @return [Object] Return value of the block
  # @raise [Capybara::FrozenInTime] If time appears frozen
end

Import

require 'capybara'
# synchronize is a method on Node::Base, available on all node instances

I/O Contract

Inputs

Name	Type	Required	Description
seconds	Integer/nil	No	Maximum wait seconds (default: default_max_wait_time)
errors	Array<Exception>	No	Exception types that trigger retry
block	Block	Yes	The operation to retry

Outputs

Name	Type	Description
block result	Object	The return value of the block on success

Usage Examples

Implicit Use (via find)

# find automatically uses synchronize internally
find('#dynamic-element')  # retries for up to default_max_wait_time

# Override wait time
find('#slow-element', wait: 10)

Direct Use

# Custom retry logic
page.document.synchronize(5) do
  result = page.evaluate_script('window.myApp.ready')
  raise Capybara::ExpectationNotMet unless result
  result
end

Related Pages

Implements Principle

Principle:Teamcapybara_Capybara_Auto_Waiting

Requires Environment

Environment:Teamcapybara_Capybara_Ruby_And_Gem_Dependencies

Uses Heuristic

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment