在开始替我们的康威生命游戏实作更多功能之前,要先将目前的 Rust 程序加入测试(Testing),除了可以用来验证目前的程序正确性之外,还可以避免日后因修改程序而把原本可以正常工作的程序弄出问题了。另外,有些程序问题发生的原因很难确认,我们也需要在 Rust 程序中输出 Log 到网页浏览器的主控台(console)中,才能调试(Debugging)。

测试(Testing)

我们虽然成功在上一章的最后在网页浏览器上显示出康威生命游戏的画面,看到细胞发疯似地繁殖又灭亡,但我们根本无法确定这些细胞的变化是不是正确的。

为了验证游戏逻辑的正确性,我们会需要撰写测试程序。我们其实可以使用 Node.js 引用 WebAssembly 程序来对其做集成测试,但笔者并不建议这么做。因为 Rust 的 WebAssembly 开发环境已经有提供不错的测试功能了,而且使用起来就像是原生的 Rust 测试程序的架构。

虽然本篇系列文章中还没提到,但如果您有自行稍微看过 wasm-pack-template 模板的话,应该会注意到 Cargo 程序项目底下有个 tests 目录,里面有个 web.rs 文件。这个文件的内容如下:

#![cfg(target_arch = "wasm32")]

extern crate wasm_bindgen_test;
use wasm_bindgen_test::*;

wasm_bindgen_test_configure!(run_in_browser);

#[wasm_bindgen_test]
fn pass() {
    assert_eq!(1 + 1, 2);
}

注意到这个 #[wasm_bindgen_test] 属性,这边的程序结构非常像 Rust 原生的 #[test] 属性,套用这个 #[test] 属性的函数会变成测试函数。而 #[wasm_bindgen_test] 属性也是类似的作用,套用 #[wasm_bindgen_test] 属性的函数,也会变成测试函数,只不过这个测试函数的调用者不是 Rust 程序,而是系统环境中已安装的网页浏览器。

什么意思呢?我们可以在终端机内运行以下指令:

wasm-pack test --firefox

运行 wasm-pack test --firefox

以上指令运行后,wasm-pack 就会启动一个 HTTP 服务器,并针对 Firefox 浏览器提供程序的测试脚本。当我们用 Firefox 浏览器打开 http://127.0.0.1:8000/ 这个网址时,就会开始运行测试脚本了!

在 Firefox 运行测试脚本的结果

除了能使用 --firefox 参数来指定用 Firefox 浏览器之外,wasm-pack 也可以使用 --chrome 或 --safari 参数来指定用 Google 浏览器或是 Safari 浏览器。浏览器参数可以同时使用多个。

不管用哪个网页浏览器,都可以替 wasm-pack test 指令再加上 --headless 参数,使我们不必手动用网页浏览器打开网址,就能在终端机上直接看到测试结果。

加上 --headless 的测试结果

再来看到 wasm_bindgen_test_configure 宏,它来自于 wasm_bindgen_test 这个 crate,用法蛮奇怪,可以传入多个用空格 分隔的参数,run_in_browser 这个参数表示要求让目前这个测试程序在网页浏览器上运行。不错,wasm-pack test 指令除了用网页浏览器来运行测试脚本之外,也可以用 Node.js 来测试,只要加上 --node 参数即可。

替康威生命游戏撰写 WebAssembly 测试

我们希望可以测试培养皿从目前这个状态到下一个阶段的状态的变化,所以打算把那四条规则都测试过。在开始撰写测试前,我们可以思考一下,看是不是需要替 Universe 结构体添加更多方法来完成测试。我们既然要测试培养皿的状态变化,势必得有个方法能够手动设置哪些格子有活细胞,而且在计算完下一个状态之后,也还要有个方法能够取得或是判断培养皿上的活细胞分布状态。

于是,我们需要先在 src/lib.rs 加入以下程序:

impl Universe {
    pub fn check_cells(&self, cells_indexes: &[usize]) -> bool {
        for (index, block) in self.blocks.iter().enumerate() {
            if cells_indexes.contains(&index) {
                if let Block::NoCell = block {
                    return false;
                }
            } else if let Block::HasCell = block {
                return false;
            }
        }

        true
    }

    pub fn add_cells(&mut self, indexes: &[usize]) {
        for &index in indexes {
            self.blocks[index] = Block::HasCell;
        }
    }
}

注意这边添加的 Universe 的方法,并不需要使用 #[wasm_bindgen] 属性,因为我们不想把它们暴露给 JavaScript 程序。

然后就能开始撰写测试的程序了,如下:

#![cfg(target_arch = "wasm32")]

use wasm_bindgen_test::*;
use wasm_game_of_life::Universe;

wasm_bindgen_test_configure!(run_in_browser);

#[wasm_bindgen_test]
fn rule_1() {
    let mut universe = Universe::new(5, 5);

    universe.add_cells(&[12, 13]);

    universe.tick();

    assert!(universe.check_cells(&[]));
}

#[wasm_bindgen_test]
fn rule_2() {
    let mut universe = Universe::new(5, 5);

    universe.add_cells(&[8, 12, 16]);

    universe.tick();

    assert!(universe.check_cells(&[12]));
}

#[wasm_bindgen_test]
fn rule_3() {
    let mut universe = Universe::new(5, 5);

    universe.add_cells(&[7, 8, 12, 13, 16]);

    universe.tick();

    assert!(universe.check_cells(&[7, 8, 11, 13, 17]));
}

#[wasm_bindgen_test]
fn rule_4() {
    let mut universe = Universe::new(5, 5);

    universe.add_cells(&[6, 13, 16]);

    universe.tick();

    assert!(universe.check_cells(&[12]));
}

#[wasm_bindgen_test]
fn case_1() {
    let mut universe = Universe::new(5, 5);

    universe.add_cells(&[7, 12, 17]);

    universe.tick();

    assert!(universe.check_cells(&[11, 12, 13]));
}

测试的程序写好之后就可以用刚才提到的 wasm-pack test 指令来运行。

康威生命游戏测试函数的运行结果

调试(Debugging)

用调试模式来建置项目

我们之前都是用 wasm-pack build 指令来建置项目,这个指令预设会使用 release 模式来编译 Rust 程序。如果不要用 release 模式的话,可以改用 wasm-pack build --debug 指令来建置项目。

显示 panic 消息

当 WebAssembly 程序发生 panic 时,网页浏览器或是 Node.js 的主控台不会出现 panic 消息,这会让调试变得有点麻烦。也许您可能已经有注意到,wasm-pack-template 模板的 src 目录中,除了有 lib.rs 文件外,还有一个 utils.rs 文件。在这个 utils 模块中,有提供一个 set_panic_hook 函数,只要让 WebAssembly 程序在运行的过程中调用到这个函数,之后若 WebAssembly 程序发生 panic,就会把 panic 消息输出到主控台。

我们可以在 Universe 结构体的 new 关联函数中调用 set_panic_hook 函数。程序如下:

#[wasm_bindgen]
impl Universe {
    #[wasm_bindgen(constructor)]
    pub fn new(width: u32, height: u32) -> Universe {
        if cfg![debug_assertions] {
            utils::set_panic_hook();
        }

        ...
    }

    ...
}

如此一来,使用调试模式编译出来的 WebAssembly 程序就会把 panic 消息输出到主控台了!

输出消息到主控台

我们无法直接用 Rust 的 print! 等宏使 WebAssembly 程序输出消息到主控台。想要做到这件事的话,我们可以使用 web-sys 套件,它能用来绑定网页浏览器的 API (Web API),主控台的 console 也是可以绑定的。

想在 Rust 中调用到 JavaScript 的 console,首先需要在 Cargo.toml 设置档中,加入以下设置:

web-sys = { version = "*", features = ["console"] }

接着在 src/lib.rs 中,加入以下代码:

macro_rules! log {
    ( $( $t:tt )* ) => {
        web_sys::console::log_1(&format!( $( $t )* ).into());
    }
}

web_sys 这个 crate 提供的 log_1 函数即为 JavaScript 的 console.log 函数的只能传一个参数的版本。web_sys 也有提供能传两个参数的 log_2 函数,如果要传三个参数就是用 log_3,依此类推。不过由于这种 API 用起来有点麻烦,所以我们在这里自订了一个 log 宏,就可以透过它来以类似 print! 宏那样的语法格式输出消息了!

例如:

log!("A = {}, B = {}", 5, 6);

以上程序会在主控台中输出:

A = 5, B = 6

我们可以试着在 Universe 结构体的 tick 方法中加入以下程序:

#[wasm_bindgen]
impl Universe {
    pub fn tick(&mut self) {
        ...

        for row in 0..self.height {
            for column in 0..self.width {
                ...

                let has_cell = self.has_cell(index);

                let live_neighbor_cells_count = {
                    ...
                };

                if cfg![debug_assertions] {
                    log!(
                        "Is blocks[{row:5}, {column:5}] has a live cell? {has_cell:5}. And it has \
                         {live_neighbor_cells_count} live neighbors.",
                    );
                }

                ...
            }
        }

        ...
    }
}

如果您加上以上程序片段后就直接用调试模式重新建置项目,然后打开网页浏览器的主控台看结果,您的网页浏览器很可能会变得非常卡,甚至到冻结的地步,CPU 使用率也会狂飙。这是因为 tick 方法是透过 JavaScript 的 requestAnimationFrame 函数来重复调用,它在一秒钟内就有可能会被运行 60 次,且每运行一次就会输出 32 x 32 = 1024 个 Log(因为培养皿的 WIDTH 和 HEIGHT 预设为 32),所以会产生大量的主控台消息,让网页浏览器来不及处理。

用 JavaScript 的 debugger 关键字创建调试点

为了解决上述网页浏览器卡住的问题,在调用 tick 方法前,我们可以加入 JavaScript 提供的 debugger 关键字,用来创建一个调试点。

...

const renderLoop = () => {
    // eslint-disable-next-line no-debugger
    debugger;

    universe.tick();

    drawCells();

    requestAnimationFrame(renderLoop);
};

...

当网页浏览器正在启动「检查元素」时,JavaScript 程序若运行到 debugger 关键字,就会自动暂停,直到我们按下继续运行(Resume)的按钮,它才会再继续运行接下来的程序。我们需要使用 Webpack 的 development 模式进行打包才能保留 debugger 关键字,请在 www/package.json 文件的 scripts 中加上 "build:webpack:dev": "webpack --mode development" 脚本,这样就可以使用 npm run build:webpack:dev 指令来打包。

在浏览器主控台暂停的 JavaScript 程序

我们可以在 JavaScript 程序暂停的期间,慢慢研究主控台中已经被输出的消息,看看程序到底是在哪个环节出问题了。

主控台中输出的消息

其它类型的消息

我们都知道,console 除了能用 log 函数来输出一般消息到主控台之外,还可以用 info 函数输出信息消息、warn 输出警告消息、error 输出错误消息,这些函数都可以使用 web_sys 这个 crate 提供的 log_1、info_1、warn_1、error_1 等函数来绑定。

当然,我们可以为它们都撰写出如下的宏:

macro_rules! log {
    ( $( $t:tt )* ) => {
        web_sys::console::log_1(&format!( $( $t )* ).into());
    }
}

macro_rules! info {
    ( $( $t:tt )* ) => {
        web_sys::console::info_1(&format!( $( $t )* ).into());
    }
}

macro_rules! warn {
    ( $( $t:tt )* ) => {
        web_sys::console::warn_1(&format!( $( $t )* ).into());
    }
}

macro_rules! error {
    ( $( $t:tt )* ) => {
        web_sys::console::error_1(&format!( $( $t )* ).into());
    }
}

总结

在这个章节中,我们学会了用 Rust 撰写 WebAssembly 测试的方式,也知道要怎么样在网页浏览器上对 WebAssembly 程序进行调试。另外,也大概会用 web-sys 套件来绑定网页浏览器的 API 了。

下一个章节,我们要来替这个康威生命游戏加上与玩家交互的功能。

下一章:让康威生命游戏能与玩家交互。