CtrlK
BlogDocsLog inGet started
Tessl Logo

igmarin/rails-agent-skills

Curated library of 41 public AI agent skills for Ruby on Rails development. Organized by category: planning, testing, code-quality, ddd, engines, infrastructure, api, patterns, context, and orchestration. Covers code review, architecture, security, testing (RSpec), engines, service objects, DDD patterns, and TDD automation. Repository workflows remain documented in GitHub but are intentionally excluded from the Tessl tile.

95

1.77x
Quality

93%

Does it follow best practices?

Impact

96%

1.77x

Average score across 41 eval scenarios

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

SKILL.mdskills/testing/test-service/

name:
test-service
license:
MIT
description:
Use when writing RSpec tests for service objects, API clients, orchestrators, or business logic in spec/services/. Covers instance_double, FactoryBot hash factories, shared_examples, subject/let blocks, context/describe structure, aggregate_failures, change matchers, travel_to, and error scenario testing.
metadata:
{"version":"1.0.0","user-invocable":"true"}

Test Service

Quick Reference

AspectRule
File locationspec/services/module_name/service_spec.rb
Subjectsubject(:service_call) { described_class.call(params) }
Unit isolationinstance_double for collaborators
Integrationcreate for DB-backed tests
Multi-assertionaggregate_failures
State verificationchange matchers
Time-dependenttravel_to
API responsesFactoryBot hash factories (class: Hash)

HARD-GATE

DO NOT implement the service before step 1 is written and failing for the right reason.
1. WRITE:   Write the spec (happy path + error cases + edge cases)
2. RUN:     bundle exec rspec spec/services/your_service_spec.rb
3. VERIFY:  Confirm failures are for the right reason (not a typo or missing factory)
4. FIX:     Implement or fix until the spec passes
5. SUITE:   bundle exec rspec spec/services/ — verify no regressions

Core Process

Use this skill when writing tests for service classes under spec/services/.

Core principle: Test the public contract (.call, .find, .search), not internal implementation. Use instance_double for isolation, create for integration.

Spec Template

# frozen_string_literal: true

require 'spec_helper'

RSpec.describe ModuleName::MainService do
  describe '.call' do
    subject(:service_call) { described_class.call(params) }

    let(:shelter) { create(:shelter, :with_animals) }
    let(:params) do
      { shelter: { shelter_id: shelter.id }, items: %w[TAG001 TAG002] }
    end

    context 'when input is valid' do
      before { create(:animal, tag_number: 'TAG001', shelter:) }

      it 'returns success' do
        expect(service_call[:success]).to be true
      end
    end

    context 'when shelter is not found' do
      let(:params) { super().merge(shelter: { shelter_id: 999_999 }) }

      it 'returns error response' do
        expect(service_call[:success]).to be false
      end
    end

    context 'when input is blank' do
      let(:params) { { shelter: { shelter_id: nil }, items: [] } }

      it 'returns error response with meaningful message' do
        aggregate_failures do
          expect(service_call[:success]).to be false
          expect(service_call[:errors]).not_to be_empty
        end
      end
    end
  end
end

Use instance_double for unit isolation:

let(:client) { instance_double(Api::Client) }
before { allow(client).to receive(:execute_query).and_return(api_response) }

Use create for integration tests:

let(:source_shelter) { create(:shelter, :with_animals) }

FactoryBot Hash Factories for API Responses

When testing API clients, use class: Hash with initialize_with to build hash-shaped response fixtures. A minimal example:

FactoryBot.define do
  factory :api_animal_response, class: Hash do
    tag_number { 'TAG001' }
    status     { 'active' }

    initialize_with { attributes.stringify_keys }
  end
end

# In the spec:
let(:api_response) { build(:api_animal_response, tag_number: 'TAG002') }

New Test File Checklist

  • subject defined for the main action
  • instance_double for unit / create for integration
  • Happy path for each public method
  • Error and edge cases (blank input, invalid refs, failures)
  • Partial success scenarios where relevant
  • shared_examples for repeated patterns
  • aggregate_failures for multi-assertion tests
  • change matchers for state verification
  • Logger expectations for error logging

Common Mistakes

MistakeCorrect approach
No error scenario testsHappy path only = false confidence — always test failures
let! everywhereUse let (lazy) unless the value is needed unconditionally for setup
Huge factory setupKeep factories minimal — only attributes required for the test
Spec breaks when implementation changes but behavior is unchangedTests that break on refactoring are testing internals, not contracts

Extended Resources

  • PATTERNS.md for the full pattern and factory placement guidance.
  • assets/spec_examples.md
  • assets/testing_checklist.md

Output Style

  1. Clear structure: Write tests with properly structured describe and context blocks.
  2. Public contract: Name the public method under test (.call, .find, .search) and avoid assertions against private implementation.
  3. Tests-first proof: Show the spec file, focused command, and expected RED failure before implementation or fix.
  4. GREEN checkpoint: Show the focused rerun and the broader spec/services/ command when available.
  5. Collaborator strategy: State where instance_double is used for injected collaborators and where create is used for DB-backed integration.
  6. Failure coverage: Include happy path, error shape, blank/invalid input, and external failure cases when relevant.
  7. Language: Must be in English unless explicitly requested otherwise.

Integration

SkillWhen to chain
write-testsFor general RSpec style and TDD discipline
create-service-objectFor the service conventions being tested
integrate-api-clientFor API client layer testing patterns
test-engineWhen testing engine-specific services

skills

README.md

server.json

tile.json