Lucky Logo

# Setup

Located in your app’s spec/support/ directory is an ApiClient that you can use to make requests to your app’s Action classes. Use this object to set any custom headers, or params you need.

# Making requests

All requests can be made by using ApiClient.exec, and passing the action class. Lucky will automatically infer which HTTP method to use based on route defined in the Action class.

# GET /users

# POST /posts

You can also pass path and query params using with if your Action requires them.

# PUT /users/1

# DELETE /posts/3

# or pass additional query params
ApiClient.exec(Posts::Search.with(q: "Lucky"))

Read more on URL generation.

# Setting body params

The second argument to the exec method will take a NamedTuple of params you want to send. In most cases, these params will be sent to an Operation, so these params will need to be nested with the proper param_key.

ApiClient.exec(Posts::Create, post: {title: "My next Taco Dish", posted_at:})

ApiClient.exec(Users::Update.with(, user: {email: ""})

# Setting headers

If you need to set custom headers, you’ll use the headers method on an instance of the ApiClient.

client =

  .headers("Accept": "application/vnd.api.v1+json")
  .headers("Set-Cookie": "remember_me=1")
  .headers("Authorization": "Bearer abc123")

# Then make your request:

# Creating methods for common setup

Let’s say your API uses a Range header to determine which range of items should be included. We can create a method on our ApiClient to make this easier to reuse.

# spec/support/
class ApiClient < Lucky::BaseHTTPClient
  # ...

  def page(page : Int32, per_page = 10)
    # Set pagination headers
    headers("Range":  "order,id #{page * per_page}; order=desc,max=#{per_page}")

Now we can use this in our tests

response =

# User Auth

If you generated your app with User Authentication, your API endpoints may require being authenticated to access those endpoints. You can use the ApiClient.auth(user) method to set the proper header.

user = UserFactory.create


# JSON Actions

If you need to test your JSON API, or any action that has a JSON response, Lucky gives you some built-in helper methods to make testing responses easier.

We will use this action as an example:

class Api::Rockets::Show < ApiAction
  get "/api/rockets/:rocket_id" do
    rocket = RocketQuery.find(rocket_id)
    json({id:, type: rocket.type, name:})
# spec/requests/api/rockets/
require "../../../spec_helper"

describe Api::Rockets::Show do
  it "returns a 200 response with the rocket name" do
    rocket = RocketFactory.create &.name("Dragon 1")
    response = ApiClient.auth(current_user).exec(Api::Rockets::Show.with(

    # The JSON response should have the key `name` with a value `"Dragon 1"`.
    response.should send_json(200, name: "Dragon 1")

  it "returns a 401 for unauthenticated requests" do
    response = ApiClient.exec(Api::Rockets::Show.with(4))

    response.status_code.should eq(401)

private def current_user : User
  UserFactory.create &.email("")

The send_json method will check that the HTTP status matches, and the JSON response contains your expected values.

See a problem? Have an idea for improvement? Edit this page on GitHub