DEV Community: constdrop

rspec-wasm v0.2.0: Testing Ruby Code That Integrates with JavaScript and WebAssembly

constdrop — Sun, 01 Nov 2026 15:08:19 +0000

In September 2026, I released rspec-wasm, a tool for running RSpec tests on ruby.wasm, and introduced it in my previous DEV article:

Stop Writing Ruby Tests in JS Template Literals: Meet rspec-wasm

I've now released rspec-wasm v0.2.0, which adds support for asynchronous JavaScript setup and teardown around RSpec execution.

One of the great advantages of building applications with WebAssembly is the ability to combine functionality from different Wasm modules.

However, until now, rspec-wasm had no way to asynchronously initialize an external runtime before running RSpec tests or clean it up afterward.

With v0.2.0, we can initialize external JavaScript or Wasm runtimes before running RSpec, making it possible to test Ruby code that interacts with them.

In this article, I'll demonstrate the new functionality by testing Ruby code that uses a WebAssembly-based MP3 decoder.

Why Use External Wasm Modules with ruby.wasm?

When developing applications with ruby.wasm, building a custom Wasm binary can expand what's possible.

However, if we want to use existing gems with a prebuilt ruby.wasm runtime, we're currently limited to pure Ruby gems.

This can lead to a few challenges:

An appropriate pure Ruby gem might not exist for the functionality we need.
A pure Ruby implementation might not provide the performance we expect.
Our application might be designed to combine multiple Wasm modules from the beginning.

In these situations, using external Wasm modules alongside ruby.wasm can be a practical solution.

For example, we might want to integrate:

Image and video processing libraries
Databases such as SQLite
Python/Wasm runtimes
Compression and cryptography libraries
Numerical computing or machine learning runtimes

But how can we test Ruby code that depends on these external runtimes?

That's where the new functionality in rspec-wasm v0.2.0 comes in.

Example: Decoding MP3 Audio with WebAssembly

Let's build a small example that initializes a WebAssembly-based MP3 decoder, calls it from Ruby, and verifies the decoded audio information using RSpec.

We'll use the following:

Node.js 18 or later
rspec-wasm 0.2.0
mpg123-decoder 1.0.3

Both ruby.wasm and RSpec are included in rspec-wasm, so we don't need to install them separately.

mpg123-decoder is an MP3 decoder that runs mpg123 through WebAssembly.

1. Create the Project

First, create a new project and install the dependencies.

mkdir rspec-wasm-mp3-example
cd rspec-wasm-mp3-example
npm init -y
npm install mpg123-decoder@1.0.3
npm install --save-dev rspec-wasm@0.2.0

Add the test command to package.json.

{
  "type": "module",
  "scripts": {
    "test": "rspec-wasm"
  },
  "dependencies": {
    "mpg123-decoder": "1.0.3"
  },
  "devDependencies": {
    "rspec-wasm": "0.2.0"
  }
}

Our project will have the following structure:

.
├── lib/
│   └── audio_probe.rb
├── spec/
│   ├── fixtures/
│   │   └── tone.mp3
│   └── audio_probe_spec.rb
├── package.json
└── rspec-wasm.config.mjs

2. Prepare an MP3 File for Testing

For this example, we'll use a stereo MP3 file with a sample rate of 44.1 kHz.

Download the test file using the following commands:

mkdir -p spec/fixtures
curl -L https://github.com/eshaz/wasm-audio-decoders/raw/refs/heads/main/test/data/44100.stereo.cbr.mp3 \
  -o spec/fixtures/tone.mp3

This file comes from the test data in eshaz/wasm-audio-decoders, which is distributed under the MIT license.

If you use a different MP3 file, adjust the expected sample rate and channel count in the tests accordingly.

3. Initialize the Wasm Decoder Before Running RSpec

Now comes the main feature introduced in v0.2.0.

Create rspec-wasm.config.mjs to define the setup and teardown operations.

import fs from "node:fs/promises";
import path from "node:path";
import { MPEGDecoder } from "mpg123-decoder";

let decoder;

function summarize(decoded, encodedBytes) {
  const peakLevels = decoded.channelData.map((channel) => {
    let peak = 0;

    for (const sample of channel) {
      peak = Math.max(peak, Math.abs(sample));
    }

    return peak;
  });

  return {
    encoded_bytes: encodedBytes,
    sample_rate: decoded.sampleRate,
    channels: decoded.channelData.length,
    samples_per_channel: decoded.samplesDecoded,
    duration_ms: Math.round(
      decoded.samplesDecoded / decoded.sampleRate * 1000
    ),
    peak_levels: peakLevels,
    errors: decoded.errors.map((error) => error.message),
  };
}

export default {
  async setup({ workspaceRoot }) {
    decoder = new MPEGDecoder();
    await decoder.ready;

    globalThis.audioCodec = {
      async inspect(relativePath) {
        const root = path.resolve(workspaceRoot);
        const filePath = path.resolve(root, relativePath);
        const relative = path.relative(root, filePath);

        if (relative.startsWith("..") || path.isAbsolute(relative)) {
          throw new Error("Audio file must be inside the workspace");
        }

        const encoded = await fs.readFile(filePath);

        try {
          const decoded = decoder.decode(encoded);
          return JSON.stringify(
            summarize(decoded, encoded.byteLength)
          );
        } finally {
          await decoder.reset();
        }
      },
    };
  },

  async teardown() {
    decoder?.free();
    delete globalThis.audioCodec;
  },
};

The setup function initializes the Wasm decoder and waits until it's ready before RSpec starts.

We expose the initialized API through globalThis.audioCodec, allowing Ruby code to access it through the JavaScript bridge.

After the tests finish, teardown releases the decoder.

The execution flow looks like this:

Create Ruby VM
      |
      v
Asynchronously initialize
the MP3 Wasm decoder
      |
      v
Run RSpec tests
      |
      v
Release the decoder

This lifecycle management is particularly useful for external Wasm modules that require asynchronous initialization.

4. Await a JavaScript Promise from Ruby

Next, create lib/audio_probe.rb.

require "json"
require "js"

class AudioProbe
  def self.inspect(path)
    result = JS.global[:audioCodec]
      .call(:inspect, path)
      .await
      .to_s

    JSON.parse(result, symbolize_names: true)
  end
end

The JavaScript inspect function returns a Promise, so we use .await on the Ruby side to wait for the result.

In v0.2.0, rspec-wasm executes RSpec through RubyVM#evalAsync, allowing Ruby code inside specs to await JavaScript Promises.

Another important detail is that the MP3 binary data and decoded PCM data remain on the JavaScript/Wasm side.

Only a small JSON summary is returned to Ruby.

This avoids unnecessarily transferring large binary data across the Ruby–JavaScript boundary.

5. Write the RSpec Tests

Now let's create spec/audio_probe_spec.rb.

require "audio_probe"

RSpec.describe AudioProbe do
  it "decodes MP3 metadata with a WebAssembly codec" do
    result = described_class.inspect("spec/fixtures/tone.mp3")

    expect(result[:encoded_bytes]).to be > 0
    expect(result[:sample_rate]).to eq(44_100)
    expect(result[:channels]).to eq(2)
    expect(result[:samples_per_channel]).to be > 0
    expect(result[:duration_ms]).to be > 0
    expect(result[:peak_levels].first).to be_between(0.0, 1.0)
    expect(result[:errors]).to be_empty
  end

  it "rejects parent-directory traversal" do
    expect {
      described_class.inspect("../outside.mp3")
    }.to raise_error(JS::Error, /inside the workspace/)
  end
end

The first test actually decodes an MP3 file using WebAssembly and verifies properties such as the sample rate, channel count, and audio duration.

The second test verifies that the JavaScript API rejects attempts to access files outside the workspace using ../.

JavaScript exceptions are exposed as JS::Error on the Ruby side, so we can test them using the usual RSpec matchers.

A note about path validation: This example uses lexical path validation with path.relative. If you need to enforce workspace boundaries even when symbolic links are involved, you should also validate the resolved paths using fs.realpath.

For this demonstration, we'll keep things simple.

6. Run the Tests

Finally, run:

npm test

The output should look similar to this:

AudioProbe
  decodes MP3 metadata with a WebAssembly codec
  rejects parent-directory traversal

Finished in 0.10502 seconds (files took 1.3 seconds to load)
2 examples, 0 failures

2 examples, 0 failures!

We've successfully tested Ruby code that calls JavaScript, invokes a WebAssembly MP3 decoder, and returns the result to RSpec.

And we can use ordinary RSpec matchers throughout the process.

What's New in rspec-wasm v0.2.0?

Version 0.2.0 introduces the following features:

Configuration through rspec-wasm.config.mjs — Define JavaScript-side initialization and cleanup behavior.
Asynchronous setup and teardown — Initialize external runtimes before tests and release resources afterward.
Promise support in Ruby specs — Call JavaScript functions that return Promises and wait for their results using .await.
Reliable cleanup — Run teardown operations whether RSpec tests pass or fail.
Initialization failure handling — If setup fails, RSpec won't start, and the process exits with a non-zero status.

The MP3 decoder example demonstrates the first three features directly.

Conclusion

With rspec-wasm v0.2.0, we can now test more than just Ruby code running entirely inside ruby.wasm.

We can also test Ruby applications that use JavaScript as their host environment and integrate functionality from external WebAssembly modules.

I think combining multiple Wasm modules is one of the interesting possibilities of WebAssembly-based application development.

By supporting asynchronous runtime initialization and Promise handling, rspec-wasm makes it easier to write RSpec tests for these applications without moving test logic into JavaScript.

If you're building applications with ruby.wasm and other Wasm modules, give rspec-wasm a try!

References

Stop Writing Ruby Tests in JS Template Literals: Meet rspec-wasm

constdrop — Fri, 04 Sep 2026 16:05:19 +0000

If you have built applications with ruby.wasm, you might have encountered a frustrating developer experience when writing unit tests.

Testing Ruby logic compiled to WebAssembly usually meant embedding Ruby code inside JavaScript template literals and asserting the results using Node.js test runners.

I wanted to write clean, idiomatic RSpec tests for my Ruby WebAssembly code, so I built rspec-wasm—a test runner that executes native RSpec directly within a Node.js-based ruby.wasm VM.

The Old Way: Writing Ruby Tests in JavaScript

When testing ruby.wasm modules, you typically had to pass stringified Ruby code into vm.eval() and serialize the output to JSON so JavaScript could inspect it:

import { test } from "node:test";
import assert from "node:assert";

test("starts with an empty board and player X", async () => {
  // Writing Ruby code inside JS template literals...
  const resultJson = await vm.eval(`
    require_relative "../lib/tic_tac_toe"
    game = TicTacToe.new

    # Needs explicit JSON serialization to pass values to JS
    { current_player: game.current_player, winner: game.winner }.to_json
  `);

  const data = JSON.parse(resultJson.toString());

  // Relying on JS assertions instead of RSpec syntax...
  assert.strictEqual(data.current_player, "X");
  assert.strictEqual(data.winner, null);
});

This approach comes with noticeable drawbacks:

No syntax highlighting or autocomplete in your editor for the embedded Ruby code.
Manual serialization (.to_json) just to exchange data between VM boundaries.
Loss of RSpec's intuitive matcher syntax and failure reporting.

The New Way: Pure RSpec with `rspec-wasm`

rspec-wasm eliminates the JavaScript wrapper layer. You write standard Ruby files and run them with a single CLI command.

Standard File Discovery: Auto-detects spec/**/*_spec.rb files.
Full IDE Support: Enjoy syntax highlighting, formatting, and linting in standard .rb files.
Zero Host Setup: Runs instantly via npx without requiring a local Ruby environment.

Tutorial: Testing a Tic-Tac-Toe Game

Let's walk through building a game logic module and testing it with rspec-wasm.

1. Setup

Initialize your project and install rspec-wasm:

mkdir tictactoe-wasm
cd tictactoe-wasm
npm init -y
npm install --save-dev rspec-wasm

2. Write the Game Logic (`lib/tic_tac_toe.rb`)

Create a pure Ruby class that handles game state without DOM or Web dependencies:

class TicTacToe
  attr_reader :board, :current_player, :winner

  def initialize
    @board = Array.new(9, nil)
    @current_player = "X"
    @winner = nil
  end

  def move(index)
    return false if index < 0 || index > 8 || @board[index] || @winner

    @board[index] = @current_player
    if check_winner
      @winner = @current_player
    else
      @current_player = (@current_player == "X" ? "O" : "X")
    end
    true
  end

  def draw?
    @board.none?(&:nil?) && @winner.nil?
  end

  private

  def check_winner
    lines = [
      [0, 1, 2], [3, 4, 5], [6, 7, 8],
      [0, 3, 6], [1, 4, 7], [2, 5, 8],
      [0, 4, 8], [2, 4, 6]
    ]
    lines.any? { |a, b, c| @board[a] && @board[a] == @board[b] && @board[a] == @board[c] }
  end
end

3. Write RSpec Tests (`spec/tic_tac_toe_spec.rb`)

Write standard RSpec specs requiring your library:

require "tic_tac_toe"

RSpec.describe TicTacToe do
  subject(:game) { TicTacToe.new }

  it "starts with an empty board and player X" do
    expect(game.current_player).to eq("X")
    expect(game.winner).to be_nil
  end

  it "alternates turns between players" do
    game.move(0) # X
    expect(game.current_player).to eq("O")
    game.move(1) # O
    expect(game.current_player).to eq("X")
  end

  it "detects a winning row" do
    game.move(0) # X
    game.move(3) # O
    game.move(1) # X
    game.move(4) # O
    game.move(2) # X wins

    expect(game.winner).to eq("X")
  end
end

4. Run the Tests

Execute the CLI command in your terminal:

npx rspec-wasm

Output:

TicTacToe
  starts with an empty board and player X
  alternates turns between players
  detects a winning row

Finished in 0.06 seconds (files took 1.7 seconds to load)
3 examples, 0 failures

Bonus: Running the Tested Logic in the Browser

Because the core domain logic in lib/tic_tac_toe.rb is decoupled from the UI, you can import it directly into your frontend HTML using ruby.wasm:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>ruby.wasm Tic-Tac-Toe</title>
  <script src="https://cdn.jsdelivr.net/npm/@ruby/3.3-wasm-wasi@2.5.0/dist/browser.script.iife.js"></script>
  <style>
    .board { display: grid; grid-template-columns: repeat(3, 80px); gap: 5px; }
    .cell { width: 80px; height: 80px; font-size: 32px; font-weight: bold; cursor: pointer; }
  </style>
</head>
<body>
  <h1>ruby.wasm Tic-Tac-Toe</h1>
  <div id="status">Loading...</div>
  <div class="board" id="board"></div>

  <script type="text/ruby" data-eval="async">
    require "js"

    # Fetch and evaluate the tested Ruby logic
    response = JS.global.fetch("lib/tic_tac_toe.rb").await
    eval(response.text.await.to_s)

    $game = TicTacToe.new

    def render
      document = JS.global[:document]
      status_text = $game.winner ? "Winner: #{$game.winner} 🎉" : "Turn: #{$game.current_player}"
      document.getElementById("status")[:innerText] = status_text

      board_el = document.getElementById("board")
      board_el[:innerHTML] = ""
      $game.board.each_with_index do |cell, idx|
        btn = document.createElement("button")
        btn[:className] = "cell"
        btn[:innerText] = cell || ""
        btn.addEventListener("click") { $game.move(idx) && render }
        board_el.appendChild(btn)
      end
    end

    render
  </script>
</body>
</html>

Serve the directory (npx serve .) and open it in your browser to play the game with verified logic!

Conclusion

By separating pure Ruby business logic from DOM integration, you can maintain test coverage using native RSpec while deploying to WebAssembly environments.

npm: rspec-wasm
GitHub: dogrun-inc/rspec-wasm

DEV Community: constdrop

rspec-wasm v0.2.0: Testing Ruby Code That Integrates with JavaScript and WebAssembly

Why Use External Wasm Modules with ruby.wasm?

Example: Decoding MP3 Audio with WebAssembly

1. Create the Project

2. Prepare an MP3 File for Testing

3. Initialize the Wasm Decoder Before Running RSpec

4. Await a JavaScript Promise from Ruby

5. Write the RSpec Tests

6. Run the Tests

What's New in rspec-wasm v0.2.0?

Conclusion

References

Stop Writing Ruby Tests in JS Template Literals: Meet rspec-wasm

The Old Way: Writing Ruby Tests in JavaScript

The New Way: Pure RSpec with rspec-wasm

Tutorial: Testing a Tic-Tac-Toe Game

1. Setup

2. Write the Game Logic (lib/tic_tac_toe.rb)

3. Write RSpec Tests (spec/tic_tac_toe_spec.rb)

4. Run the Tests

Bonus: Running the Tested Logic in the Browser

Conclusion

The New Way: Pure RSpec with `rspec-wasm`

2. Write the Game Logic (`lib/tic_tac_toe.rb`)

3. Write RSpec Tests (`spec/tic_tac_toe_spec.rb`)