Mastering Java Fault Injection with Byteman: A Hands‑On Guide

Fault testing aims to simulate potential problems to see how a system reacts, uncover hidden issues, and evaluate recovery capabilities by inducing network latency, service interruptions, or resource exhaustion.

For Java applications, Byteman is a powerful dynamic fault‑injection tool developed by JBoss that modifies bytecode at runtime, allowing injection of faults and exceptions without changing the original source code.

Key Features of Byteman

Dynamic fault injection at runtime, enabling simulation of network delays, service crashes, or resource exhaustion.

Bytecode manipulation using asm9, providing fine‑grained control over method behavior.

Rule‑based DSL (.btm files) to specify when, where, and how faults are injected.

Seamless integration with JUnit and TestNG for automated testing.

Getting Started

Download Byteman from the official site, set the BYTEMAN_HOME environment variable, and configure the JVM with the appropriate -javaagent option, for example:

-javaagent://byteman-download-4.0.23/lib/byteman.jar=listener:true,boot://byteman-download-4.0.23/lib/byteman.jar

Optionally add the helper jar and set -Dorg.jboss.byteman.home as needed.

Sample Java Program

package com.funtest.temp;

public class BytemanDemo {
    public static void main(String[] args) {
        while (true) {
            try {
                Thread.sleep(1000);
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }
            print();
        }
    }

    static void print() {
        System.out.println("Hello Word from Byteman ,By FunTester !!!");
    }
}

Creating a Byteman Rule

The following .btm file injects a line of text at the entry of the print method:

RULE Byteman Demo
CLASS com.funtest.temp.BytemanDemo
METHOD print
AT ENTRY
IF true
DO System.out.println("Byteman Print Hello World !!!");
ENDRULE

Explanation of each line: RULE Byteman Demo – defines the rule name. CLASS com.funtest.temp.BytemanDemo – targets the specified class. METHOD print – selects the method to instrument. AT ENTRY – injects code at method entry. IF true – unconditional execution. DO System.out.println(...) – the action performed. ENDRULE – terminates the rule.

Injecting and Removing Faults

Install the rule with: bmsubmit.sh -l temp.btm The console will show “install rule Byteman Demo”. Running the Java program now prints both the original and injected messages, confirming successful injection.

To remove the rule, execute: bmsubmit.sh -u temp.btm Omitting the rule file name removes all loaded rules:

bmsubmit.sh -u

Supporting Shell Scripts

bminstall.sh installs the Byteman Java agent into a running JVM without restarting, automatically discovers JVMs, and allows PID‑specific installation with optional configuration flags such as listener:true or custom boot jars.

bmsubmit.sh submits or revokes .btm rule files to a target JVM, supports rule replacement, and can list currently active rules, providing fine‑grained control over fault‑injection scenarios.