Rocket 框架提供的测试架构十分简单,只要产生出想要测试的 Rocket 实体,再将它提供给 local 模块下的 Client 结构体使用,Rocket 应用程序就能摇身一变,可以直接用写程序的方式来发送请求和接收回应。

在我们学习 Rocket 应用程序的测试之前,几乎只会在 main 方法中调用 rocket 这个 crate 提供的 build 函数来创建 Rocket 实体。但从现在开始,我们要在有使用 test 属性的函数中调用 build 函数了!

那我们需要把原先 main 方法中的整流片、应用程序状态的实体、路由处理程序等也全都搬进测试函数中吗?最好不要,因为加入这些东西不一定是我们接下来要跑的测试案例(test case)会用到的,全都加进去虽然不会对程序正确性有什么影响,但铁定会拖慢测试的运行速度!所以说,我们只要把有用到的组件注册进这个拿来做测试用的 Rocket 实体即可,甚至我们也可以把要加进去测试的东西做一些适当的改变(例如设置档的修改)。

举例来说,修改一下上一章访问 MySQL 数据库的例子,现在有以下的 Rocket 程序:

#[macro_use]
extern crate rocket;

use rocket::fairing::AdHoc;
use rocket_db_pools::{
    sqlx::{self, Row},
    Connection, Database,
};

#[derive(Database)]
#[database("example")]
struct MyDatabase(sqlx::MySqlPool);

#[put("/<key>/<value>")]
async fn put(mut db: Connection<MyDatabase>, key: String, value: String) -> &'static str {
    sqlx::query("INSERT INTO `example` (`key`, `value`) VALUES (?, ?)")
        .bind(key)
        .bind(value)
        .execute(&mut **db)
        .await
        .unwrap();

    "ok"
}

#[get("/<key>")]
async fn get(mut db: Connection<MyDatabase>, key: String) -> Option<String> {
    let result = sqlx::query("SELECT `value` FROM `example` WHERE `key` = ?")
        .bind(key)
        .fetch_optional(&mut **db)
        .await
        .unwrap();

    result.map(|row| row.get("value"))
}

#[get("/hello")]
fn hello() -> &'static str {
    "Hello World!"
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .attach(MyDatabase::init())
        .attach(AdHoc::try_on_ignite("MySQL Initializer", |rocket| {
            Box::pin(async move {
                let mut connection = match MyDatabase::fetch(&rocket) {
                    Some(pool) => match pool.acquire().await {
                        Ok(connection) => connection,
                        Err(_) => return Err(rocket),
                    },
                    None => return Err(rocket),
                };

                let result = sqlx::query(
                    "CREATE TABLE IF NOT EXISTS `example` ( `id` INT NOT NULL AUTO_INCREMENT, \
                     `key` varchar(100), `value` TEXT , PRIMARY KEY (`id`), UNIQUE KEY (`key`) )",
                )
                .execute(&mut *connection)
                .await;

                match result {
                    Ok(_) => Ok(rocket),
                    Err(_) => Err(rocket),
                }
            })
        }))
        .mount("/", routes![put, get])
        .mount("/", routes![hello])
}

数据库的部份比较复杂一点,稍候再来说明,先来谈谈怎么测试 hello 这个路由处理程序吧!首先在 main.rs 文件中加入如下的代码:

#[cfg(test)]
mod test {
    use super::*;

    #[rocket::async_test]
    async fn test_hello() {
        let app = rocket::build().mount("/", routes![hello]);
    }
}

以上程序中,我们使用了 #[rocket::async_test] 属性来创建我们的异步测试程序。在 test_hello 函数中我们打算要测试 hello 这个路由处理程序的正确性,因此我们的 Rocket 实体只需要将 hello 路由处理程序注册进来就好了,其它不相干的东西不用加进来。

再来就是创建 Client 结构实体。Rocket 提供了同步版(local::blocking)和异步版(local::asynchronous)的 Client 结构实体,建议使用异步版的 Client 结构实体,以达最大兼容性。

创建 Client 结构实体的程序如下:

#[cfg(test)]
mod test {
    use rocket::local::asynchronous::Client;

    use super::*;

    #[rocket::async_test]
    async fn test_hello() {
        let app = rocket::build().mount("/", routes![hello]);

        let client = Client::tracked(app).await.expect("valid rocket instance");
    }
}

在使用 Client 结构实体的 tracked 关联函数时,Rocket 实体就把 Rocket 启动之前的步骤都走完,因此有可能会因为设置档错误、整流片错误、路由处理程序的冲突等而导致回传 Result 枚举的 Err 变体。

这个 Client 结构实体可以当作是一个小型的 HTTP 客户端,除了有发送请求和接收回应等基本功能外,也会记录 Cookie 的状态。

如果要用 Client 结构实体来产生 GET /hello 请求,程序如下:

let req = client.get("/hello");

这个 req 变量所保存的值为 LocalRequest 结构体的实体,我们可以利用这个结构实体来调整等等要送出的 HTTP 请求的内容。不过,在这个测试案例中,我们直接使用 dispatch 方法让它发送请求。这边虽然是说发送请求,但不会真的透过外部网络或是内部网络来传递 HTTP 消息啦!所以速度是非常快的,不必担心。

let res = req.dispatch().await;

LocalRequest 结构实体的 dispatch 方法会直接将 HTTP 回应回传出来。这个 res 变量所保存的值为 LocalResponse 结构体的实体。

再来我们可以检查回应的 HTTP 状态码以及 HTTP 主体是否分别是我们预期的 http::Status::Ok 与 Hello World!。完整的测试代码如下:

#[cfg(test)]
mod test {
    use rocket::{http::Status, local::asynchronous::Client};

    use super::*;

    #[rocket::async_test]
    async fn test_hello() {
        let app = rocket::build().mount("/", routes![hello]);

        let client = Client::tracked(app).await.expect("valid rocket instance");

        let req = client.get("/hello");

        let res = req.dispatch().await;

        assert_eq!(Status::Ok, res.status());
        assert_eq!("Hello World!", res.into_string().await.expect("valid string"));
    }
}

如此一来这个测试案例就完成啦!

接下来要来测试数据库的路由处理程序,原则上我们会比较希望在测试时是使用与开发时不同的数据库,避免测试失败时在开发用的数据库留下很多莫名其妙的数据。而且也可以在测试开始进行时,事先将数据库中的内容清除掉。为了使 Rocket 框架吃不同的设置,在这第二个测试案例中,我们会在 Rocket.toml 中加入名为 test 的 Profile 设置区块,并在测试程序中写程序来控制 Rocket 套用 test 这个 Profile。当然我们也是可以直接把所有设置写在测试的代码中。

在 Rocket.toml 中添加以下设置:

[test.databases.example]
url = "mysql://magic_rocket:4M{}^;dkn7Eg@localhost:3306/magic_rocket_test"

接着先修改我们原先的程序,让 MySQL Initializer 整流片的创建独立成一个函数,方便在测试程序中重用。如下:

#[macro_use]
extern crate rocket;

use rocket::fairing::AdHoc;
use rocket_db_pools::{
    sqlx::{self, Row},
    Connection, Database,
};

#[derive(Database)]
#[database("example")]
struct MyDatabase(sqlx::MySqlPool);

#[put("/<key>/<value>")]
async fn put(mut db: Connection<MyDatabase>, key: String, value: String) -> &'static str {
    sqlx::query("INSERT INTO `example` (`key`, `value`) VALUES (?, ?)")
        .bind(key)
        .bind(value)
        .execute(&mut **db)
        .await
        .unwrap();

    "ok"
}

#[get("/<key>")]
async fn get(mut db: Connection<MyDatabase>, key: String) -> Option<String> {
    let result = sqlx::query("SELECT `value` FROM `example` WHERE `key` = ?")
        .bind(key)
        .fetch_optional(&mut **db)
        .await
        .unwrap();

    result.map(|row| row.get("value"))
}

#[get("/hello")]
fn hello() -> &'static str {
    "Hello World!"
}

fn create_mysql_initializer(drop_table: bool) -> AdHoc {
    AdHoc::try_on_ignite("MySQL Initializer", move |rocket| {
        Box::pin(async move {
            let mut connection = match MyDatabase::fetch(&rocket) {
                Some(pool) => match pool.acquire().await {
                    Ok(connection) => connection,
                    Err(_) => return Err(rocket),
                },
                None => return Err(rocket),
            };

            if drop_table
                && sqlx::query("DROP TABLE IF EXISTS `example`")
                    .execute(&mut *connection)
                    .await
                    .is_err()
            {
                return Err(rocket);
            }

            let result = sqlx::query(
                "CREATE TABLE IF NOT EXISTS `example` ( `id` INT NOT NULL AUTO_INCREMENT, `key` \
                 varchar(100), `value` TEXT , PRIMARY KEY (`id`), UNIQUE KEY (`key`) )",
            )
            .execute(&mut *connection)
            .await;

            match result {
                Ok(_) => Ok(rocket),
                Err(_) => Err(rocket),
            }
        })
    })
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .attach(MyDatabase::init())
        .attach(create_mysql_initializer(false))
        .mount("/", routes![put, get])
        .mount("/", routes![hello])
}

// ...

然后在测试程序中撰写产生 Rocket 设置的函数,方便不同测试案例重复使用。如下:

#[cfg(test)]
mod test {
    use std::env;

    use rocket::{config::Config, figment::Figment, http::Status, local::asynchronous::Client};

    use super::*;

    fn create_config() -> Figment {
        env::set_var("ROCKET_PROFILE", "test");

        Config::figment()
    }

    #[rocket::async_test]
    async fn test_hello() {
        let app = rocket::custom(create_config()).mount("/", routes![hello]);

        let client = Client::tracked(app).await.expect("valid rocket instance");

        let req = client.get("/hello");

        let res = req.dispatch().await;

        assert_eq!(Status::Ok, res.status());

        assert_eq!("Hello World!", res.into_string().await.expect("valid string"));
    }
}

接着就是撰写第二个测试案例了!如下:

#[cfg(test)]
mod test {
    use std::env;

    use rocket::{config::Config, figment::Figment, http::Status, local::asynchronous::Client};

    use super::*;

    fn create_config() -> Figment {
        env::set_var("ROCKET_PROFILE", "test");

        Config::figment()
    }

    #[rocket::async_test]
    async fn test_hello() {
        let app = rocket::custom(create_config()).mount("/", routes![hello]);

        let client = Client::tracked(app).await.expect("valid rocket instance");

        let req = client.get("/hello");

        let res = req.dispatch().await;

        assert_eq!(Status::Ok, res.status());

        assert_eq!("Hello World!", res.into_string().await.expect("valid string"));
    }

    #[rocket::async_test]
    async fn test_database_get_put() {
        let app = rocket::custom(create_config())
            .attach(MyDatabase::init())
            .attach(create_mysql_initializer(true))
            .mount("/", routes![put, get]);

        let client = Client::tracked(app).await.expect("valid rocket instance");

        {
            let req = client.put("/hello/world");

            let res = req.dispatch().await;

            assert_eq!(Status::Ok, res.status());
            assert_eq!("ok", res.into_string().await.expect("valid string"));
        }

        {
            let req = client.get("/hello");

            let res = req.dispatch().await;

            assert_eq!(Status::Ok, res.status());
            assert_eq!("world", res.into_string().await.expect("valid string"));
        }
    }
}

如此一来这个测试案例也完成啦!如果还想要再撰写其它数据库的测试案例,因为 Cargo 项目在进行测试的时候是多线程来同时运行不同测试的,所以不同测试的结果有可能会互相干扰。为了避免这个问题,可以使用一个全域的互斥锁,参考这篇文章来了解一下 Rust 全域静态变量的使用方式。把互斥锁用在数据库的测试中并不能说是一个很有效率的作法,不过写起来还挺方便的。

于是最后,完整的 Rocket 程序含测试的代码如下:

#[macro_use]
extern crate rocket;

use rocket::fairing::AdHoc;
use rocket_db_pools::{
    sqlx::{self, Row},
    Connection, Database,
};

#[derive(Database)]
#[database("example")]
struct MyDatabase(sqlx::MySqlPool);

#[put("/<key>/<value>")]
async fn put(mut db: Connection<MyDatabase>, key: String, value: String) -> &'static str {
    sqlx::query("INSERT INTO `example` (`key`, `value`) VALUES (?, ?)")
        .bind(key)
        .bind(value)
        .execute(&mut **db)
        .await
        .unwrap();

    "ok"
}

#[get("/<key>")]
async fn get(mut db: Connection<MyDatabase>, key: String) -> Option<String> {
    let result = sqlx::query("SELECT `value` FROM `example` WHERE `key` = ?")
        .bind(key)
        .fetch_optional(&mut **db)
        .await
        .unwrap();

    result.map(|row| row.get("value"))
}

#[get("/hello")]
fn hello() -> &'static str {
    "Hello World!"
}

fn create_mysql_initializer(drop_table: bool) -> AdHoc {
    AdHoc::try_on_ignite("MySQL Initializer", move |rocket| {
        Box::pin(async move {
            let mut connection = match MyDatabase::fetch(&rocket) {
                Some(pool) => match pool.acquire().await {
                    Ok(connection) => connection,
                    Err(_) => return Err(rocket),
                },
                None => return Err(rocket),
            };

            if drop_table
                && sqlx::query("DROP TABLE IF EXISTS `example`")
                    .execute(&mut *connection)
                    .await
                    .is_err()
            {
                return Err(rocket);
            }

            let result = sqlx::query(
                "CREATE TABLE IF NOT EXISTS `example` ( `id` INT NOT NULL AUTO_INCREMENT, `key` \
                 varchar(100), `value` TEXT , PRIMARY KEY (`id`), UNIQUE KEY (`key`) )",
            )
            .execute(&mut *connection)
            .await;

            match result {
                Ok(_) => Ok(rocket),
                Err(_) => Err(rocket),
            }
        })
    })
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .attach(MyDatabase::init())
        .attach(create_mysql_initializer(false))
        .mount("/", routes![put, get])
        .mount("/", routes![hello])
}

#[cfg(test)]
mod test {
    use std::{env, sync::Mutex};

    use rocket::{config::Config, figment::Figment, http::Status, local::asynchronous::Client};

    use super::*;

    static LOCK: Mutex<()> = Mutex::new(());

    fn create_config() -> Figment {
        env::set_var("ROCKET_PROFILE", "test");

        Config::figment()
    }

    #[rocket::async_test]
    async fn test_hello() {
        let app = rocket::custom(create_config()).mount("/", routes![hello]);

        let client = Client::tracked(app).await.expect("valid rocket instance");

        let req = client.get("/hello");

        let res = req.dispatch().await;

        assert_eq!(Status::Ok, res.status());

        assert_eq!("Hello World!", res.into_string().await.expect("valid string"));
    }

    #[allow(clippy::await_holding_lock)]
    #[rocket::async_test]
    async fn test_database_get_put_1() {
        let _lock = LOCK.lock().unwrap();

        let app = rocket::custom(create_config())
            .attach(MyDatabase::init())
            .attach(create_mysql_initializer(true))
            .mount("/", routes![put, get]);

        let client = Client::tracked(app).await.expect("valid rocket instance");

        {
            let req = client.put("/hello/world");

            let res = req.dispatch().await;

            assert_eq!(Status::Ok, res.status());
            assert_eq!("ok", res.into_string().await.expect("valid string"));
        }

        {
            let req = client.get("/hello");

            let res = req.dispatch().await;

            assert_eq!(Status::Ok, res.status());
            assert_eq!("world", res.into_string().await.expect("valid string"));
        }
    }

    #[allow(clippy::await_holding_lock)]
    #[rocket::async_test]
    async fn test_database_get_put_2() {
        let _lock = LOCK.lock().unwrap();

        let app = rocket::custom(create_config())
            .attach(MyDatabase::init())
            .attach(create_mysql_initializer(true))
            .mount("/", routes![get]);

        let client = Client::tracked(app).await.expect("valid rocket instance");

        {
            let req = client.put("/hello/world");

            let res = req.dispatch().await;

            assert_eq!(Status::NotFound, res.status());
        }
    }
}

总结

从以上最后写出来的完整程序中可以发现,我们写的测试程序比有实质功能的主程序还要多!一个好的 Web 应用程序就是必须要撰写很多测试来验证各种不同的商业逻辑,确保当下以及日后改版过的程序依然能够正确运行!还好 Rocket 提供的测试架构还算好写,不需额外看起来稀奇古怪的设置值与设置档,只要有 Rocket 实体,就可以产生出 Client 结构实体来进行测试。

这个系列的文章就到这里为止了,Rocket 真的是一个既优雅方便、容易维护、性能也不错的 Web 框架!