gba_test

Game Boy Advance 测试框架。

入门

使用 gba_test 需要安装 nightly 版本的 Rust。

先决条件

• ARM Binutils：至少需要 ARM GNU 链接器 (arm-none-eabi-ld) 才能正确构建使用 gba_test 的项目。您可以从 ARM 网站 获取。
• rust-src - GBA 开发需要 build-std 才能工作。运行 rustup component add rust-src 以启用它。
• cargo 配置 - 应在项目中的 cargo/config.toml 文件中提供 cargo 的配置。以下是一个示例配置：

[build]
target = "thumbv4t-none-eabi"

[target.thumbv4t-none-eabi]
runner = "mgba"
rustflags = ["-Clinker=arm-none-eabi-ld", "-Clink-arg=-Tgba.ld", "-Ztrap-unreachable=no"]

[unstable]
build-std = ["core"]

将 gba_test 添加到依赖列表

在您的 Cargo.toml 清单中，将 gba_test 添加到 dev-dependencies 列表

[package]
name = "your_project"
version = "0.1.0"
edition = "2021"

[dev-dependencies]
gba_test = "0.1.0"

运行测试运行器

gba_test 提供了自己的测试运行器。要运行测试，您需要在您的 main() 函数中调用运行器。

以下代码可以在运行 cargo test 时调用测试运行器：

#![no_std]
#![cfg_attr(test, no_main)]
#![cfg_attr(test, feature(custom_test_frameworks))]
#![cfg_attr(test, test_runner(gba_test::runner))]
#![cfg_attr(test, reexport_test_harness_main = "test_harness")]

#[cfg(test)]
#[no_mangle]
pub fn main() {
    test_harness()
}

调用 test_harness() 将运行项目中定义的所有测试。

定义测试

gba_test 提供了自己的自定义 #[test] 属性来定义测试。它的工作方式与默认的 #[test] 属性类似。

// A very simple function to test.
pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::add;
    use gba_test::test;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

其他常见的测试属性也受到支持，包括 #[ignore] 和 #[should_panic]。

运行测试

gba_test 可以在任何可以运行 .gba 文件的地方运行，从原始的 Game Boy Advance 硬件到仿真器。

使用 cargo test 配置在 mGBA 上运行

对于开发工作流程，建议在仿真器上运行测试。在“先决条件”部分提供的示例 cargo/config.toml 将允许您在运行 cargo test 时在 mGBA（假设 mgba 在您的 PATH 中）上运行测试。

在真实硬件上运行

要在真实 Game Boy Advance 硬件上运行，您可以将生成的测试二进制文件闪存到卡带中。

准备 .gba 文件

当运行 cargo test 时，会生成一个 .elf 测试二进制文件。仿真器如 mGBA 可以运行此 .elf 文件，但真实硬件需要 .gba 文件。您的测试二进制文件的路径由 cargo test 输出。例如，在 gba_test 库上运行 cargo test 时输出如下

Running unittests src\lib.rs (target\thumbv4t-none-eabi\debug\deps\gba_test-5b5cf1bdf24b2915)

括号中的路径是测试二进制文件的位置。您可以使用 arm-none-eabi-objcopy（从 ARM 网站 获取）从这个二进制文件创建一个 .gba 文件

arm-none-eabi-objcopy -O binary target\thumbv4t-none-eabi\debug\deps\gba_test-5b5cf1bdf24b2915 test.gba

接下来，运行 gbafix

cargo install gbafix
gbafix test.gba

现在，test.gba 已准备就绪，可以在真实的 Game Boy Advance 硬件上运行。有关将 .gba 文件闪存到卡带并运行的说明，请参阅您的闪存卡的文档。

使用 mgba-rom-test 运行

gba_test 已配置为使用 mgba-rom-test 二进制文件通过 SWI 调用 0x27 并将 r0 作为输出寄存器运行。退出值为 0 被认为是成功的测试运行。

[dev-dependencies]
gba_test = {version = "0.1.0", features = ["log"]}

use gba_test::test;

#[test]
fn foo() {
    log::info!("important information");
}

#![no_std]
#![cfg_attr(test, no_main)]
#![cfg_attr(test, feature(custom_test_frameworks))]
#![cfg_attr(test, test_runner(gba_test::runner))]
#![cfg_attr(test, reexport_test_harness_main = "test_harness")]

#[cfg(test)]
#[no_mangle]
pub fn main() {
    mgba_log::init();
    test_harness()
}