Introducing JVM SandBox for Exception Injection Testing

Functional testing often focuses on normal business logic and neglects the impact of various exceptions on services. Exception testing should cover server system exceptions (e.g., CPU/memory shortage, power loss), dependency service exceptions (e.g., database or third‑party service timeouts), and application‑level exceptions (e.g., process restart, hangs, slow responses).

JVM SandBox is a non‑intrusive, dynamically pluggable AOP solution at the JVM level. It can be attached to a running JVM process (provided the target JVM does not disable the attach feature) and later detached, with all its effects disappearing after removal.

The sandbox works by using a Java Agent that maintains an Instrument object as the sole channel to access and manipulate the JVM. After starting, it also launches an internal Jetty server for communication between external processes and the sandbox.

The core idea of SandBox is to split any Java method invocation into three stages—BEFORE, RETURN, and THROWS—allowing fine‑grained control over input parameters, return values, and execution flow, thus enabling detailed fault injection.

Implementation steps include:

Implement the com.alibaba.jvm.sandbox.api.Module interface and annotate the class with @MetaInfServices .

Provide a no‑argument constructor.

Add a @Command method to receive a Map<String, String> of parameters (class name, method name, exception type, exception content, etc.).

Use EventWatchBuilder to specify the target class and method, then register an AdviceListener to modify behavior, for example throwing an exception via ProcessController.throwsImmediately(new Exception()) .

@MetaInfServices(Module.class)
@Information(id="exceptionModule", version="0.0.2", author="lll")
public class ExceptionModule implements Module {
    @Resource
    private ModuleEventWatcher moduleEventWatcher;

    @Command("throwException")
    public void injectPoint(final Map
param){
        final String className = getParameter(param, "className");
        final String method = getParameter(param, "methodName");
        final String exceptionName = getParameter(param, "exceptionName");
        final String exceptionContent = getParameter(param, "exceptionContent");
        final Integer injectPoint = Integer.parseInt(getParameter(param, "injectPoint"));
        new EventWatchBuilder(moduleEventWatcher)
            .onClass(className)
            .onBehavior(method)
            .onWatch(new AdviceListener() {
                protected void afterReturning(Advice advice) throws Throwable {
                    // Change method behavior, throw exception
                    ProcessController.throwsImmediately(new Exception());
                }
            });
    }
}

After building the module JAR (e.g., XXX-with-dependencies.jar ) and placing it in the /sandbox/module directory, attach the sandbox to the target JVM using its process ID (obtainable via ps -ef | grep serviceName ), start the sandbox script to get the HTTP port, and then mount the module either via command line:

sh sandbox.sh -p 24399 -d 'moduleName?param=param'

or via an HTTP request such as:

http://127.0.0.1:40050/sandbox/default/module/http/module?classPath=com.user.User&methodName=getUserInfo&exceptionName=java.lang.Exception&exceptionContent=拦截异常

Once the sandbox is successfully attached, the specified method will be intercepted and the configured exception will be thrown, allowing testing of catch blocks that are otherwise hard to cover. This approach aims to improve system resilience by enabling targeted exception injection, ultimately helping systems remain stable even under adverse conditions.