SKILL.md

name	testing-patterns-ruby
summary	Testing Couchbase Ruby applications — unit testing with RSpec doubles, integration testing with testcontainers-ruby, scope/collection isolation
description	Testing Couchbase Ruby applications — unit testing with RSpec doubles, integration testing with testcontainers-ruby, scope/collection isolation
compatibility	Ruby SDK 3.x. RSpec 3+.
metadata	last_verified min_server_version handoff 2026-05 7.0 condition skill user asks about testing concepts or strategy testing-patterns condition skill user asks about connection setup or SDK configuration server-connection-ruby

Testing Couchbase Ruby Applications

Unit Testing

Use RSpec doubles to mock the collection.

# Gemfile
gem 'rspec', '~> 3.12', group: :test

RSpec.describe UserRepository do
  let(:mock_collection) { double('collection') }
  let(:mock_result)     { double('get_result', content: { 'name' => 'Alice' }) }

  it 'returns the correct document' do
    allow(mock_collection).to receive(:get).with('user::alice').and_return(mock_result)

    repo = UserRepository.new(mock_collection)
    user = repo.get_user('user::alice')

    expect(user['name']).to eq('Alice')
    expect(mock_collection).to have_received(:get).with('user::alice')
  end
end

See shared mock examples for the full pattern reference.

Integration Testing with testcontainers

# Gemfile
gem 'testcontainers-core', group: :test

require 'testcontainers'
require 'couchbase'

RSpec.describe 'OrderRepository integration', :integration do
  before(:all) do
    @container = Testcontainers::DockerContainer.new('couchbase/server:7.6')
      .with_exposed_ports(8091, 8093, 11210)
      .start

    sleep 10 # allow cluster to initialise

    options = Couchbase::Options::Cluster.new
    options.authenticate('Administrator', 'password')
    @cluster = Couchbase::Cluster.connect(
      "couchbase://localhost:#{@container.mapped_port(11210)}",
      options
    )
    @collection = @cluster.bucket('default').default_collection
  end

  after(:all) { @container.stop }

  it 'round-trips a document' do
    @collection.upsert('order::1', { status: 'pending' })
    result = @collection.get('order::1')
    expect(result.content['status']).to eq('pending')
  end
end

Scope/Collection Isolation

require 'securerandom'

scope_name = "test_#{SecureRandom.hex(4)}"
mgr = @cluster.bucket('default').collections

mgr.create_scope(scope_name)
mgr.create_collection(Couchbase::Management::CollectionSpec.new('orders', scope_name))

# after test
mgr.drop_scope(scope_name)

Common Errors in Tests

Error	Likely cause in tests	Fix
Couchbase::Error::DocumentNotFound	Key not seeded before test	Seed data in before(:all)
Couchbase::Error::BucketNotFound	Test bucket not created	Use default bucket or create in setup
Couchbase::Error::UnambiguousTimeout	Container not ready	Increase sleep after container start
Couchbase::Error::AuthenticationFailure	Wrong test credentials	Verify username/password match container config