在開始替我們的康威生命遊戲實作更多功能之前,要先將目前的 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 了。

下一個章節,我們要來替這個康威生命遊戲加上與玩家互動的功能。

下一章:讓康威生命遊戲能與玩家互動。