Testing Utilities

MiniAPM provides testing utilities to verify that your application is correctly instrumented.

Setup

Require the testing helpers:

# spec/spec_helper.rb or test/test_helper.rb
require 'miniapm/testing'

RSpec Integration

Use the :miniapm metadata tag:

RSpec.describe OrdersController, :miniapm do
  it "tracks the request" do
    get "/orders"

    expect(MiniAPM::Testing.spans).to include(
      having_attributes(name: /process_action/)
    )
  end
end

Or enable globally:

spec/spec_helper.rb

RSpec.configure do |config|
  config.include MiniAPM::Testing::RSpecHelpers, type: :request
end

Minitest Integration

class OrdersControllerTest < ActionDispatch::IntegrationTest
  include MiniAPM::Testing::MinitestHelpers

  # Enable for all tests in this class
  enable_miniapm!

  def test_tracks_request
    get "/orders"

    assert MiniAPM::Testing.find_span(name: /process_action/)
  end
end

Testing Helpers

Recorded Spans

Access all recorded spans:

# Get all spans
MiniAPM::Testing.spans

# Find spans by name
MiniAPM::Testing.find_spans(name: /ActiveRecord/)

# Find single span
MiniAPM::Testing.find_span(name: "process_action")

Recorded Errors

Access captured errors:

# Get all errors
MiniAPM::Testing.errors

# Find errors by type
MiniAPM::Testing.find_errors(type: "RuntimeError")

# Find single error
MiniAPM::Testing.find_error(message: /something went wrong/)

Clearing State

Clear recorded data between tests:

# Automatically done when using :miniapm tag
# Or manually:
MiniAPM::Testing.clear!

Example Test Cases

Testing Request Tracing

RSpec.describe "Orders API", :miniapm do
  it "creates spans for HTTP requests" do
    get "/api/orders"

    span = MiniAPM::Testing.find_span(name: /process_action/)

    expect(span).to be_present
    expect(span.attributes["http.method"]).to eq("GET")
    expect(span.attributes["http.status_code"]).to eq(200)
  end
end

Testing Database Queries

RSpec.describe "Database queries", :miniapm do
  it "creates spans for SQL queries" do
    Order.all.to_a

    spans = MiniAPM::Testing.find_spans(name: /sql/)

    expect(spans).not_to be_empty
    expect(spans.first.attributes["db.system"]).to eq("postgresql")
  end
end

Testing Error Capture

RSpec.describe "Error handling", :miniapm do
  it "captures exceptions" do
    expect {
      get "/trigger_error"
    }.to raise_error(RuntimeError)

    error = MiniAPM::Testing.find_error(type: "RuntimeError")

    expect(error).to be_present
    expect(error.message).to include("Something went wrong")
    expect(error.backtrace).to be_present
  end
end

Testing Custom Spans

RSpec.describe "Custom instrumentation", :miniapm do
  it "records custom spans" do
    MiniAPM.span("process_payment") do |span|
      span.add_attribute("payment.amount", 100)
      # ... payment logic
    end

    span = MiniAPM::Testing.find_span(name: "process_payment")

    expect(span).to be_present
    expect(span.attributes["payment.amount"]).to eq(100)
  end
end

Testing Background Jobs

RSpec.describe ProcessOrderJob, :miniapm do
  it "traces job execution" do
    perform_enqueued_jobs do
      ProcessOrderJob.perform_later(order_id: 123)
    end

    span = MiniAPM::Testing.find_span(name: /ProcessOrderJob/)

    expect(span).to be_present
    expect(span.attributes["job.queue"]).to eq("default")
  end
end

Asserting Span Attributes

RSpec.describe "Span attributes", :miniapm do
  it "includes expected attributes" do
    get "/orders/123"

    span = MiniAPM::Testing.find_span(name: /process_action/)

    expect(span.attributes).to include(
      "http.method" => "GET",
      "http.route" => "OrdersController#show",
      "http.status_code" => 200
    )
  end
end

Asserting No Spans/Errors

RSpec.describe "Filtered paths", :miniapm do
  it "does not trace health checks" do
    get "/health"

    spans = MiniAPM::Testing.find_spans(name: /health/)

    expect(spans).to be_empty
  end
end