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 框架!
