If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/teamcapybara/capybara shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3w ago
• 26+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 68% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live teamcapybara/capybara repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/teamcapybara/capybara.

What it runs against: a local clone of teamcapybara/capybara — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in teamcapybara/capybara | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 50 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of teamcapybara/capybara. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/teamcapybara/capybara.git
#   cd capybara
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of teamcapybara/capybara and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "teamcapybara/capybara(\\.git)?\\b" \\
  && ok "origin remote is teamcapybara/capybara" \\
  || miss "origin remote is not teamcapybara/capybara (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 50 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~20d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/teamcapybara/capybara"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Capybara is a Ruby acceptance testing framework that simulates real user interactions with web applications by automating browser control through multiple drivers (Rack::Test, Selenium, WebKit). It provides a high-level DSL for clicking, filling forms, querying DOM elements, and asserting application state without requiring deep knowledge of the underlying driver technology. Monolithic gem structure: lib/capybara/node/ contains core node/element interaction logic (actions, finders, matchers); lib/capybara/driver/ abstracts driver implementations; lib/capybara/config.rb and lib/capybara.rb provide global configuration and DSL entry points. Integration test examples live in features/ using Gherkin syntax with step definitions in features/step_definitions/capybara_steps.rb.

Ruby/Rails developers writing integration and end-to-end tests who need to verify user workflows across their web applications. QA engineers and developers use it with Cucumber, RSpec, Minitest, or Test::Unit for BDD-style test suites.

Highly mature and production-ready. The project shows extensive CI/CD setup (GitHub Actions in .github/workflows/build.yml), comprehensive test coverage (Badge in README references coveralls.io), support across multiple Ruby versions and Gemfiles (gemfiles/Gemfile.* variants for Rack 2/3, Chrome, Firefox, IE), and active maintenance with Patreon funding. This is a de facto standard in the Rails testing ecosystem.

Minimal risk for stability but moderate risk for version compatibility: the codebase depends on external driver availability (Selenium, Rack::Test maturity), version constraints across multiple Ruby/Rails combinations evident from the gemfiles/, and some features like WebKit require external gems. However, the extensive test suite and CI matrix mitigate regression risk. Breaking change announcements are documented in UPGRADING.md.

Active maintenance visible through Dependabot configuration (.github/dependabot.yml) for automated dependency updates and Patreon-funded ongoing development. CI workflow runs on commits (workflows/build.yml). Specific ongoing work should be checked in GitHub Issues/Discussions and recent commits, but the file structure suggests ongoing compatibility work with multiple browser drivers and Ruby versions.

git clone https://github.com/teamcapybara/capybara.git && cd capybara && bundle install (uses Gemfile at root). Run tests with bundle exec rake or bundle exec rspec. Examine features/capybara.feature and features/step_definitions/capybara_steps.rb for integration test examples.

Daily commands: bundle exec rake (default task runs full test suite including Cucumber features in features/). For Cucumber specifically: bundle exec cucumber. For RSpec: bundle exec rspec. Tests require a test application (see features/support/env.rb for test app setup). Docker support available via docker-compose.yml for isolated test environments.

• lib/capybara.rb: Main entry point loading all modules, configuration initialization, and DSL root setup
• lib/capybara/node/finders.rb: Core logic for find(), all(), first() queries and XPath/CSS selector resolution
• lib/capybara/node/actions.rb: User interaction implementations (click, fill_in, select, check, etc) mapped to driver calls
• lib/capybara/driver/base.rb: Abstract driver interface that Rack::Test and Selenium drivers must implement
• lib/capybara/config.rb: Global configuration DSL and defaults (wait_time, app, driver selection, selector strategies)
• lib/capybara/dsl.rb: Session wrapper providing the top-level Capybara DSL methods like visit(), page, within()
• lib/capybara/node/matchers.rb: RSpec/Minitest matcher implementations (have_text, have_selector, have_field, etc)
• features/step_definitions/capybara_steps.rb: Gherkin step definitions demonstrating real Capybara usage patterns for integration tests
• .github/workflows/build.yml: CI configuration testing across multiple Ruby versions, drivers, and dependency gemfiles

Core query/finder logic changes: lib/capybara/node/finders.rb. New DSL methods or actions: lib/capybara/node/actions.rb. Driver implementation: lib/capybara/driver/base.rb and lib/capybara/driver/node.rb. Matchers/assertions: lib/capybara/node/matchers.rb. Configuration options: lib/capybara/config.rb. Integration examples: features/ directory with step definitions.

1. Wait time behavior: Capybara has default 2-second wait times (Capybara.default_max_wait_time) that retry finders but not all matchers—async test failures stem from misunderstanding which operations wait. 2. Driver differences: Rack::Test doesn't execute JavaScript; Selenium does—tests pass locally with Selenium but fail in CI using Rack::Test without explicit driver switching. 3. Selector strategy: By default, Capybara uses CSS selectors; XPath is slower but required for complex DOM queries—mixing them without understanding precedence causes unexpected element location failures. 4. Session scope: Tests must reset between examples; database transactions don't roll back Capybara-driven changes in some driver modes, requiring explicit cleanup. 5. Element staleness: Selenium elements become stale after page navigation; storing element references across actions causes 'stale element reference' errors.

• Page Object Model — Although not enforced by Capybara, this design pattern (wrapping page-specific DSL calls in reusable classes) is the standard way to structure maintainable Capybara test suites and appears implicitly in features/ examples
• Implicit Wait / Polling — Capybara's Capybara.default_max_wait_time applies retry logic to finders to handle asynchronous DOM updates—understanding when polling occurs vs. immediate assertion is critical to avoiding flaky tests
• CSS and XPath Selectors — Capybara supports both CSS and XPath query languages with configurable precedence; knowing their strengths (CSS speed vs. XPath flexibility) is essential for efficient element location in lib/capybara/node/finders.rb logic
• Driver Abstraction Pattern — Capybara's lib/capybara/driver/base.rb defines an abstract driver interface allowing swappable implementations (Rack::Test, Selenium, WebKit) without changing test code—understanding this abstraction is key to extending or debugging driver behavior
• Browser Session Management — Capybara maintains isolated session objects (lib/capybara/dsl.rb) allowing parallel test execution with named sessions and automatic cleanup—critical for avoiding test pollution and understanding scoping bugs
• Rack::Test HTTP-level Testing — Capybara's default driver uses Rack::Test to make direct HTTP calls to the Rack application without JavaScript execution—understanding when this suffices vs. when Selenium is required is fundamental to test architecture decisions
• Matcher DSL / RSpec Integration — Capybara extends RSpec matchers (lib/capybara/node/matchers.rb) with custom predicates like have_text, have_selector, have_field that integrate with RSpec's expectation syntax—this fluent API design is pervasive in the codebase

• teamcapybara/capybara-webkit — Official external gem adding Qt-based WebKit driver support to Capybara, used when Selenium is overkill and JavaScript support needed
• SeleniumHQ/selenium — Core Selenium WebDriver library that Capybara wraps for cross-browser automation—understanding WebDriver API is essential for advanced Capybara driver work
• rack/rack — Rack framework that Capybara's built-in RackTest driver interfaces with for HTTP-level testing of Rack and Rails apps
• jnicklas/cabybara-example-rails-app — Community reference Rails application demonstrating Capybara patterns and integration testing best practices
• cucumber/cucumber-ruby — Gherkin/BDD framework that Capybara integrates with via lib/capybara/cucumber.rb for feature-driven acceptance tests

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test suite for lib/capybara/queries/ directory

The queries directory contains 9 query classes (active_element_query.rb, ancestor_query.rb, base_query.rb, current_path_query.rb, match_query.rb, selector_query.rb, sibling_query.rb, style_query.rb, text_query.rb) but there's no dedicated spec directory visible for them. These are core matching/finding logic and likely lack isolated unit tests. Adding thorough specs would improve maintainability and catch regressions in query behavior.

• [ ] Create spec/capybara/queries/ directory structure
• [ ] Add unit tests for each query class in lib/capybara/queries/
• [ ] Test both successful and failure cases for query execution
• [ ] Test parameter validation and edge cases (empty strings, nil values, special characters)
• [ ] Ensure tests cover the base_query.rb contract that other queries inherit from

Add integration tests for lib/capybara/rack_test/ driver with form handling

The rack_test driver is a critical built-in driver with specific file handling logic (css_handlers.rb, form.rb, node.rb). While features/capybara.feature exists, there are likely gaps in testing complex form submissions, file uploads, multipart handling, and CSS selector edge cases specific to the rack_test implementation that aren't covered by generic feature tests.

• [ ] Review existing features/step_definitions/capybara_steps.rb for rack_test-specific scenarios
• [ ] Add feature tests for file upload handling in forms (lib/capybara/rack_test/form.rb)
• [ ] Add tests for CSS selector handling specific to rack_test (lib/capybara/rack_test/css_handlers.rb)
• [ ] Test rack_test node behavior with nested elements and edge cases (lib/capybara/rack_test/node.rb)
• [ ] Test error handling in lib/capybara/rack_test/errors.rb

Create documentation guide for implementing custom drivers in lib/capybara/driver/

The driver architecture (base.rb, node.rb) is the extension point for custom Selenium/Appium drivers, but there's no CONTRIBUTING.md section or dedicated guide explaining the driver interface contract. New contributors building custom drivers struggle because the required methods, lifecycle, and expectations aren't documented. A guide would reduce support burden and enable community driver contributions.

• [ ] Review lib/capybara/driver/base.rb and lib/capybara/driver/node.rb to identify required interface methods
• [ ] Create docs/CUSTOM_DRIVER_GUIDE.md documenting the driver interface contract
• [ ] Document required methods (visit, current_url, title, etc.) with examples
• [ ] Add a minimal example driver implementation or reference existing lib/capybara/rack_test/driver.rb as template
• [ ] Link the guide from CONTRIBUTING.md

• Document the exact wait behavior differences between find_all() and have_selector() matcher in lib/capybara/node/matchers.rb with examples in comments—currently undocumented why one waits and the other may not depending on matcher implementation.
• Add integration test coverage in features/ for all DSL methods listed in README (e.g., verify current_window, switch_to_window, and modal handling are fully exercised with step definitions)—inspection suggests some advanced window management features lack Gherkin examples.
• Create a minimal reproducible Selenium driver configuration example in features/support/ showing how to configure headless Chrome with desired capabilities—many contributors struggle with driver setup based on GitHub discussions pattern.

The Capybara codebase shows generally good security practices as a testing framework. Primary concerns are Docker infrastructure configuration (host network mode, unbound shared memory) and dependency management visibility. No obvious injection vulnerabilities, hardcoded credentials, or critical misconfigurations were detected in the visible files. The framework itself appears well-structured with separation of concerns across driver, node, and query modules. Main recommendations: (1) Refactor docker-compose to use bridge networks instead of host mode, (2) Implement shared memory size limits, (3) Establish and maintain a dependency audit process, (4) Document security considerations for test environment setup.

• Medium · Docker Compose Network Mode Host Exposure — docker-compose.yml (selenium_chrome and selenium_firefox services). The docker-compose.yml uses 'network_mode: host' for Selenium services, which bypasses Docker's network isolation. This could potentially expose the Selenium services directly to the host network and increase attack surface. Fix: Use a dedicated Docker network instead of 'host' mode. Define a service network and communicate through internal DNS. Example: Remove 'network_mode: host' and let services communicate via service names on a custom bridge network.
• Medium · Shared Memory Volume Without Size Limits — docker-compose.yml (volumes section for Selenium services). The /dev/shm volume is mounted for Selenium services without explicit size limits. This could potentially be exploited for resource exhaustion attacks or DoS conditions. Fix: Add explicit size limits to the /dev/shm mount: 'volumes: ["/dev/shm:/dev/shm:rw,size=1gb"]' or use tmpfs with size constraints.
• Low · Missing Environment Variable Documentation for Selenium — docker-compose.yml (selenium_firefox environment section). The SE_OPTS environment variable in selenium_firefox service accepts arbitrary options without validation. While primarily a test framework, this could be exploited if configuration is dynamically sourced from untrusted input. Fix: Document all accepted SE_OPTS values and validate any user-supplied configuration. Consider using explicit configuration parameters instead of raw option strings.
• Low · No HTTPS/TLS Configuration Visible — docker-compose.yml. Docker Compose configuration does not show explicit TLS/SSL configuration for Selenium services. While this is a test framework, production test environments should enforce encrypted communication. Fix: For production-like test environments, configure Selenium services with TLS certificates and enforce HTTPS communication between test runner and Selenium hub.
• Low · Potential for Dependency Vulnerabilities — capybara.gemspec (not fully analyzed). The gemspec file (capybara.gemspec) is referenced but not provided for analysis. Capybara has multiple dependencies (Selenium, Rack, etc.) that could contain vulnerabilities. No dependency pinning strategy is visible in the provided files. Fix: Review and regularly audit all gem dependencies using tools like 'bundle audit' or 'bundler-audit'. Consider using specific version constraints and keeping dependencies updated with security patches.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.