Como clicar no primeiro link nesse caso:

<div class="item">
  <a href="/agree/">Agree</a>
</div>
<div class="item">
  <a href="/agree/">Agree</a>
</div>

within ".item" do
  first(:link, "Agree").click
end

e recebo este erro:

Capybara::Ambiguous:
  Ambiguous match, found 2 elements matching css ".item"

E sem o withineu recebo este erro:

Failure/Error: first(:link, "Agree").click
NoMethodError:
  undefined method `click' for nil:NilClass

Você pode apenas usar:

first('.item').click_link('Agree')

ou

first('.item > a').click

(se o seletor padrão for: css)

O código na sua pergunta não funciona como:

within ".item" do
  first(:link, "Agree").click
end

é equivalente a:

find('.item').first(:link, "Agree").click

A Capivara encontra vários .item, por isso gera uma exceção. Considero esse comportamento da Capivara 2 muito bom.

Tente o seguinte:

within ".item" do
  click_link("Agree", :match => :first)
end

Fontes:

• http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Actions#click_link-instance_method
• https://github.com/jnicklas/capybara#strategy

Esse fraseado também funciona:

within first(".item") do
  click_link "Agree"
end

Xpath pode endereçar o elemento. Ainda não sou muito bom com isso, mas algo como//div[@class='active'][1]/a

Isso pode ou não funcionar, mas o ponto é que o xpath pode endereçar uma matriz de correspondências e obter uma determinada. Você deve conseguir combinar com isso.

Um exemplo de exemplo de trabalho de um dos meus projetos:

em page.find ("div.panel", texto: / Propostas /) faça
  em page.find ('tr', texto: / Foo /) faça
    page.should_xpath ('td [3]', texto: @today)
  fim
fim

Como first () nem sempre espera, talvez isso seja útil:

expect(page).to have_css("selector")                               
first("selector").click

a maioria dessas soluções não usará os brilhantes recursos de espera da Capivara

melhor fazer como este link sugere:
https://thoughtbot.com/blog/write-reliable-asynchronous-integration-tests-with-capybara#find-the-first-matching-element

Ruim:

first(".active").click
Se ainda não houver um elemento .active na página, o valor retornará nulo e o clique falhará.

Boa:

Se você quiser ter certeza de que há exatamente um
find(".active").click

Se você quiser apenas o primeiro elemento, a
find(".active", match: :first).click
Capivara esperará o elemento aparecer antes de tentar clicar.

Observe que match: :firsté mais frágil, porque ele clicará silenciosamente em um elemento diferente se você introduzir novos elementos correspondentes.

Simples você pode usar:

$('.item').find('a').first().click();