Testing

E2E Controller Testing

Rails-like end-to-end testing framework for Soli MVC applications. Test your controllers with real HTTP requests.

The E2E testing framework provides a comprehensive set of helpers for testing your Soli controllers with real HTTP requests. Built on a test server that runs alongside your test suite, it enables you to write integration tests that simulate actual browser requests and verify controller responses, sessions, and view data.

This framework follows conventions inspired by RSpec Rails testing patterns, making it familiar to developers coming from Ruby on Rails backgrounds while providing the safety and expressiveness of Soli's type system.

Basic Test Structure

Every E2E test file follows the same structure using Soli's test DSL. The framework provides functions for grouping tests, setting up test data, making HTTP requests, and asserting expected outcomes.

describe("HomeController", fn() {
  test("GET /up returns UP status", fn() {
    response = get("/up")
    assert_eq(res_status(response), 200)
    assert_eq(res_body(response), "UP")
  })
})

Running Tests

Execute your E2E tests using the Soli test runner:

soli test tests/builtins/controller_integration_spec.sl
soli test tests/builtins

Request Helpers

Request helpers enable you to make HTTP requests to your controllers from within tests. These functions interact with the test server running on a random available port.

HTTP Method Functions

response = get("/posts")
assert_eq(res_status(response), 200)
posts = res_json(response)
assert_gt(len(posts), 0)

response = post("/posts", {
  "title": "New Post",
  "content": "Hello World"
})
assert_eq(res_status(response), 201)

Custom Headers

Add custom headers to your requests:

set_header("X-Request-ID", "test-123")
set_header("X-Custom-Header", "custom-value")
response = get("/api/data")
clear_headers()

Authentication Headers

with_token("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
response = get("/api/protected")
clear_authorization()

Cookie Management

set_request_cookie("session_id", "abc123session")
response = get("/dashboard")
clear_cookies()

Response Helpers

Response helpers inspect HTTP responses returned by your controllers.

Status Codes

Response Body

body = res_body(response)
assert_contains(body, "expected text")

response = post("/users", {"name": "John"})
user = res_json(response)
assert_eq(user["name"], "John")

Response Headers

content_type = res_header(response, "Content-Type")
assert_contains(content_type, "application/json")

headers = res_headers(response)
assert_hash_has_key(headers, "Content-Type")

Redirects

assert(res_redirect(response))

location = res_location(response)
assert_eq(location, "/expected/path")

Session Helpers

Session helpers manage authentication state and session data during tests. These functions simulate user login/logout and authentication checks.

Authentication State Management

before_each(fn()
  as_guest()
end)

as_user(42)
response = get("/profile")
assert_eq(res_status(response), 200)

as_user(42, {"role": "admin"})
response = get("/admin/dashboard")

# Any keys work — extend as your auth needs grow:
as_user(42, {"role": "admin", "tenant": "acme"})

as_role("admin")
response = get("/admin/dashboard")
assert_eq(res_status(response), 200)

sign_in("admin", 5)         # session.admin_id = 5
sign_in("admin")            # session.admin_id = Admin.first.id
sign_in("user", 42)         # session.user_id = 42
sign_in("staff", 7)         # session.staff_id = 7

as_admin()   # same as as_user(1)
response = get("/admin/dashboard")
assert_eq(res_status(response), 200)

with_token("your-jwt-token-here")
response = get("/api/protected")

Login and Logout

login("user@example.com", "secretpassword")
response = get("/dashboard")
assert_eq(res_status(response), 200)

login("user@example.com", "password")
logout()
response = get("/dashboard")
assert_eq(res_status(response), 302)  # Redirect to login

Session Inspection

as_guest()
assert_not(signed_in())

as_user(1)
assert(signed_in())

as_guest()
assert(signed_out())

as_user(42)
user = current_user()
assert_eq(user["id"], 42)

Session Creation and Destruction

session_id = create_session(42)
assert_not_null(session_id)

create_session(42)
destroy_session()
assert(signed_out())

Custom Session Data

with_session({
  "user_id": 42,
  "role": "editor"
})
response = get("/dashboard")
assert_eq(res_status(response), 200)

Assigns Helpers

Assigns helpers inspect data passed to views during template rendering.

Query Assertions (N+1 detection)

Every response carries the AQL queries the request executed — recorded from the same query log that powers the dev bar's N+1 badge. Assert against it to catch a loop that should have been batched, or to hold an endpoint to a query budget.

test("posts index does not N+1", fn() {
  response = get("/posts")
  assert_eq(res_status(response), 200)
  assert_no_n_plus_one(response)      # fails if the view loops a per-row query
  assert_max_queries(response, 3)     # hold the endpoint to a query budget
})

Fail the whole suite: --fail-on-n1

An assertion only catches an N+1 where you remember to write it. To make the entire suite an N+1 tripwire — without touching a single spec — run:

soli test --fail-on-n1

Every get() / post() / request() that triggers an N+1 fails its test automatically, using the exact same detection and message as assert_no_n_plus_one. Clean and uninstrumented responses are untouched, so it never fails a spec spuriously. It composes with --jobs, --coverage, and the rest — wire it into CI to catch a query regression the moment it lands, even in specs that predate the check.

Complete Example

describe("PostsController", fn() {
  before_each(fn() {
    as_guest()
  })

  test("creates post with valid data", fn() {
    login("author@example.com", "password123")
    response = post("/posts", {
      "title": "New Post Title",
      "body": "Post content here"
    })
    assert_eq(res_status(response), 201)
    result = res_json(response)
    assert_not_null(result["id"])
  })

  test("rejects unauthenticated request", fn() {
    response = post("/posts", {"title": "Test"})
    assert_eq(res_status(response), 302)
  })

  test("shows single post", fn() {
    response = get("/posts/1")
    assert_eq(res_status(response), 200)
    post = res_json(response)
    assert_eq(post["title"], "First Post")
  })
})

Best Practices

Test Organization

Structure your tests hierarchically using describe() blocks. Group tests by controller, then by action, then by concern.

Before and After Hooks

Use before_each() and after_each() to set up and clean up test state. Always reset authentication state between tests.

Test Isolation

Each test should be independent and not rely on the state created by other tests.

Test DSL

Soli's testing framework provides a BDD-style DSL for organizing and writing tests:

Available Functions

Assertions

Soli provides assertion functions for writing tests with expressive syntax:

assert_equal(42, result, "should return 42")
assert_equal("hello", str, "string should match")

assert_true(user.is_active, "user should be active");

assert_false(user.is_blocked, "user should not be blocked");

assert_contains(users, "admin", "should contain admin user");

assert_nil(result.error, "should have no error");

assert_not_nil(user.id, "user should have an id");

response = get("/posts")
assert_no_n_plus_one(response)

response = get("/dashboard")
assert_query_count(response, 3)   # exactly three
assert_max_queries(response, 5)   # at most five

{
  "passed": true,
  "message": "test description",
  "expected": value_that_was_expected,
  "actual": value_that_was_actual
}

Expect Syntax (Alternative)

expect(value).to_equal(expected)
expect(value).to_be(expected)
expect(value).to_not_equal(other)
expect(value).to_be_null()
expect(value).to_not_be_null()
expect(value).to_contain("substring")

Factory Functions

Factory.define("user", {
  "name": "Test User",
  "email": "test@example.com"
})

user = Factory.create("user")

admin = Factory.create_with("user", { "role": "admin" })

Database Testing

Transaction Rollback

Worker databases are truncated between runs. Wrap per-example writes in with_transaction — it always rolls back, even on success (unlike Model.transaction):

describe("User model", fn() {
  test("creates user", fn() {
    Factory.define("user", {"email": "tx@test.com", "name": "Test"})
    Factory.bind("user", User)

    with_transaction(fn() {
      user = Factory.insert("user")
      assert_eq(User.count(), 1)
      assert_eq(user.name, "Test")
    })
    assert_eq(User.count(), 0)
  })
})

Time Travel

Pin datetime_now() for cron, TTL, and expiration specs. Cleared automatically before each test.

freeze_time(1_700_000_000)
travel_to("2024-06-15")
unfreeze_time()

Factory Pattern

Factory.define("user", {
  "email": "user#{n}@example.com",
  "name": "Test User"
})
Factory.define("post", fn() {
  return {"title": "Post #{Factory.sequence("post")}"}
})

user = Factory.create("user")
post = Factory.create_with("post", {"title": "Custom Title"})
users = Factory.create_list("user", 5)

Factory.bind("user", User)
persisted = Factory.insert("user")

Mock Database Queries

For integration tests without a real database, use Model.mock_query_result() to intercept queries and return predefined data:

describe("User queries", fn() {
  before_each(fn() { User.clear_mocks() })
  after_each(fn() { User.clear_mocks() })
  
  test("finds user by id", fn() {
    User.mock_query_result(
      "FOR doc IN users FILTER doc._key == @key RETURN doc",
      [
        {
          "_key": "123",
          "_id": "default:users/123",
          "name": "Alice",
          "email": "alice@example.com"
        }
      ]
    )
    
    user = User.find("123")
    assert_eq(user.name, "Alice")
  })
  
  test("includes returns correct class for relations", fn() {
    # Mock the parent query
    Contact.mock_query_result(
      "FOR doc IN contacts RETURN doc",
      [
        {
          "_key": "c1",
          "_id": "default:contacts/c1",
          "name": "Bob",
          "organisation_id": "default:organisations/o1"
        }
      ]
    )
    
    # Mock the included relation query
    Organisation.mock_query_result(
      "FOR doc IN organisations FILTER doc._key IN @keys RETURN doc",
      [
        {
          "_key": "o1",
          "_id": "default:organisations/o1",
          "name": "Acme Corp"
        }
      ]
    )
    
    contact = Contact.includes("organisation").first
    org = contact.organisation
    
    # Verify the relation has the correct class (not Contact)
    assert_eq(org.class_name, "Organisation")
    assert_eq(org.name, "Acme Corp")
  })
})

Parallel Execution

Tests run in parallel by default:

soli test                    # Parallel (default)
soli test --jobs=4           # 4 workers
soli test --jobs=1           # Sequential (debug)

Coverage Reporting

Generate coverage reports for your tests:

Coverage: 87.5% (1250/1428 lines) ✓

src/controllers/users.sl     ▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░  94.2%
src/models/user.sl           ▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░  91.1%
src/controllers/posts.sl     ▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░  78.5%