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_admin()
response = get("/admin/dashboard")
assert_eq(res_status(response), 200)

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

Login and Logout

login("[email protected]", "secretpassword")
response = get("/dashboard")
assert_eq(res_status(response), 200)

login("[email protected]", "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.

Complete Example

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

  test("creates post with valid data", fn() {
    login("[email protected]", "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");

{
  "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": "[email protected]"
})

user = Factory.create("user")

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

Database Testing

Transaction Rollback

Tests are isolated using database transactions:

describe("User model", fn() {
  test("creates user", fn() {
    with_transaction(fn() {
      user = Factory.create("user", hash("name": "Test"))
      expect(User.count).to_equal(1)
      expect(user.name).to_equal("Test")
    })
  })
})

Factory Pattern

# Define factories
Factory.define("user", hash(
  "email": "[email protected]",
  "name": "Test User"
))
Factory.define("post", hash(
  "title": "Test Post",
  "content": "Content here"
))
# Use factories
user = Factory.create("user")
post = Factory.create("post", hash("title": "Custom Title"))
users = Factory.create_list("user", 5);

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": "[email protected]"
        }
      ]
    )
    
    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%