Gerust

Instead of validating entities directly, Gerust uses a changeset architecture. Data is validated within a changeset struct before it is applied to an existing entity (for updates) or converted into a new entity (for inserts).

Validations are implemented using the validator crate and are declared using the #[validate(...)] attribute on the changeset fields.

Example: Creating a user with validation

#[derive(Deserialize, Validate, Clone)]
pub struct UserChangeset {
    #[validate(length(min = 1))]
    pub name: String,
}

pub async fn create(
    user: UserChangeset,
    executor: impl sqlx::Executor<'_, Database = Postgres>,
) -> Result<User, crate::Error> {
    user.validate()?;

    let record = sqlx::query!(
        "INSERT INTO users (name) VALUES ($1) RETURNING id",
        user.name
    )
    .fetch_one(executor)
    .await
    .map_err(|e| crate::Error::DbError(e.into()))?;

    Ok(User {
        id: record.id,
        description: user.name,
    })
}

Gerust provides a #[db_test] macro (from the macros crate) for testing API endpoints. Unlike standard Rust tests, #[db_test] creates a fresh, isolated database for every individual test case using a template from your main test database. This ensures tests do not interfere with each other.

Key features:

• Isolation: Each test gets its own dedicated database that is automatically deleted after the test completes.
• Context: Test functions receive a DbTestContext argument, which provides access to both the dedicated db_pool and the application instance (app) configured to use that specific database.
• Helpers: The context.app object provides helper methods like .request() to simulate HTTP requests.

#[db_test]
async fn test_read_all(context: &DbTestContext) {
    // 1. Setup state using the test database pool
    let changeset: entities::notes::NoteChangeset = Faker.fake();
    entities::notes::create(changeset.clone(), &context.db_pool)
        .await
        .unwrap();

    // 2. Execute request via the app helper
    let response = context
        .app
        .request("/notes")
        .send()
        .await;

    // 3. Assert results
    assert_that!(response.status(), eq(StatusCode::OK));
}

The db crate uses SQLx with PostgreSQL (no ORM). Data is managed through two primary structures:

1. Entities: Simple structs representing a database record (e.g., Task).
2. Changesets: Structs used for validating and preparing data for insertion or updates. Changesets use the validator crate for logic (e.g., #[validate(length(min = 1))]).

To persist data, you implement functions that take a changeset and an executor (implementing sqlx::Executor). The function should validate the changeset before executing the SQL query.

Example pattern:

• load(id, executor): Retrieves an entity by ID.
• create(changeset, executor): Validates the changeset and inserts a new record.

#[derive(Serialize, Debug, Deserialize)]
pub struct Task {
    pub id: Uuid,
    pub description: String,
}

#[derive(Deserialize, Validate, Clone)]
pub struct TaskChangeset {
    #[validate(length(min = 1))]
    pub description: String,
}

pub async fn create(
    task: TaskChangeset,
    executor: impl sqlx::Executor<'_, Database = Postgres>,
) -> Result<Task, crate::Error> {
    task.validate()?;

    let record = sqlx::query!(
        "INSERT INTO tasks (description) VALUES ($1) RETURNING id",
        task.description
    )
    .fetch_one(executor)
    .await
    .map_err(|e| crate::Error::DbError(e.into()))?;

    Ok(Task {
        id: record.id,
        description: task.description,
    })
}

Gerust provides a #[db_test] macro to enable parallel test execution with database isolation. Every test marked with this macro runs in its own unique database, which is created as a copy of the main test database and destroyed automatically after the test completes.

To use it, define an async test function that accepts a &DbTestContext. This context provides:

• app: The axum::Router for the application.
• db_pool: A connection pool connected to the test-specific database.

This allows you to seed the database using the db_pool and then make HTTP requests against the app to verify the state.

#[db_test]
async fn test_read_all(context: &DbTestContext) {
    let task_changeset: TaskChangeset = Faker.fake();
    create_task(task_changeset.clone(), &context.db_pool)
        .await
        .unwrap();

    let response = context
        .app
        .request("/tasks")
        .method(Method::GET)
        .send()
        .await;

    assert_that!(response.status(), eq(StatusCode::OK));

    let tasks: TasksList = response.into_body().into_json::<TasksList>().await;
    assert_that!(tasks, len(eq(1)));
    assert_that!(
        tasks.first().unwrap().description,
        eq(task_changeset.description)
    );
}

When writing application tests in a Gerust project, use the test and db_test macros provided by the macros crate instead of the standard tokio::test macro.

These macros wrap tokio's testing functionality but add Gerust-specific lifecycle management:

1. test macro: Automatically creates a new instance of your application and injects it into your test function via the test context.
2. db_test macro: Extends the test macro by creating a dedicated, isolated database for the test. This database is cloned from your main test database template. The macro ensures the database is automatically deleted once the test completes to prevent clutter.

// Note: Actual usage syntax depends on the web crate implementation,
// but the concept involves replacing #[tokio::test] with Gerust's macros.

#[gerust::db_test]
async fn my_application_test(ctx: TestContext) {
    // ctx contains the application instance and the isolated database
}