Package com.oracle.truffle.tck

Class TruffleRunner

java.lang.Object

org.junit.runner.Runner

org.junit.runners.ParentRunner<org.junit.runners.model.FrameworkMethod>

org.junit.runners.BlockJUnit4ClassRunner

com.oracle.truffle.tck.TruffleRunner

All Implemented Interfaces:

org.junit.runner.Describable, org.junit.runner.manipulation.Filterable, org.junit.runner.manipulation.Orderable, org.junit.runner.manipulation.Sortable

public class TruffleRunner
extends org.junit.runners.BlockJUnit4ClassRunner

JUnit test runner for unit testing Truffle AST interpreters.

A test using TruffleRunner consists of 2 parts, a Truffle AST to be tested, and a test method that drives the test, provides input argument values and validates the result.

Writing a test AST

The Truffle AST to be tested is written as a RootNode subclass, for example:

public class TestExecuteNode extends RootNode {

    @Child InteropLibrary interop;

    public TestExecuteNode() {
        super(runWithPolyglot.getTestLanguage());
        interop = InteropLibrary.getFactory().createDispatched(5);
    }

    @Override
    public Object execute(VirtualFrame frame) {
        Object obj = frame.getArguments()[0];
        try {
            return interop.execute(obj);
        } catch (InteropException ex) {
            CompilerDirectives.transferToInterpreter();
            Assert.fail(ex.getMessage());
            return null;
        }
    }
}

Writing a test method

The test method is a normal method annotated with Test. It may have one or more arguments of type CallTarget that are annotated with TruffleRunner.Inject. The TruffleRunner.Inject annotation specifies a RootNode subclass that is the root of a test AST, and the TruffleRunner will create one CallTarget for each of these test ASTs. The test method can then execute the AST by calling the CallTarget.call(java.lang.Object...) method.

Typically a test method will prepare some arguments, and then do a single call to CallTarget.call(java.lang.Object...). Then it should verify the result by inspecting the return value and checking the expected side effects of the test code.

@RunWith(TruffleRunner.class)
public class ExampleTest {

    @Test
    public void executeTest(@Inject(TestExecuteNode.class) CallTarget target) {
        TruffleObject receiver = prepareArgumentValue();
        Object ret = target.call(receiver);
        Assert.assertEquals(expectedRetValue(), ret);
    }
}

Running a test in the polyglot engine

If a test should be run in the context of a polyglot engine, TruffleRunner.RunWithPolyglotRule can be used.

@RunWith(TruffleRunner.class)
public static class PolyglotTest {

    @ClassRule RunWithPolyglotRule runWithPolyglot = new RunWithPolyglotRule();

    private static Object prepared;

    @BeforeClass
    public void prepare() {
        prepared = runWithPolyglot.getTruffleTestEnv().importSymbol("...");
    }

    @Test
    public void executeTest(@Inject(TestExecuteNode.class) CallTarget target) {
        Object ret = target.call(prepared);
        Assert.assertEquals(expectedRetValue(), ret);
    }
}

Since:

0.25

See Also:

• warmup iterations and compilation
• parameterized Truffle AST tests

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static @interface	TruffleRunner.Inject	A parameter annotated with TruffleRunner.Inject specifies the RootNode of the test AST.
static final class	TruffleRunner.ParametersFactory	ParametersRunnerFactory for testing Truffle AST interpreters using Parameterized unit tests.
static final class	TruffleRunner.RunWithPolyglotRule	JUnit rule to run the tests in the context of a polyglot engine.
static @interface	TruffleRunner.Warmup	A test method can be annotated with TruffleRunner.Warmup to specify how many warmup iterations of a test should be done before the Truffle tree is compiled.

Constructor Summary

Constructors

Constructor	Description
TruffleRunner(Class<?> klass)	Should not be called directly.
TruffleRunner(org.junit.runners.model.TestClass testClass)	Should not be called directly.

Method Summary

Modifier and Type	Method	Description
protected final org.junit.runners.model.Statement	methodInvoker(org.junit.runners.model.FrameworkMethod method, Object test)	Internal method used by the JUnit framework.
protected final void	validateTestMethods(List<Throwable> errors)	Internal method used by the JUnit framework.

Methods inherited from class org.junit.runners.BlockJUnit4ClassRunner

collectInitializationErrors, computeTestMethods, createTest, createTest, describeChild, getChildren, getTestRules, isIgnored, methodBlock, possiblyExpectingExceptions, rules, runChild, testName, validateConstructor, validateFields, validateInstanceMethods, validateNoNonStaticInnerClass, validateOnlyOneConstructor, validateZeroArgConstructor, withAfters, withBefores, withPotentialTimeout

Methods inherited from class org.junit.runners.ParentRunner

childrenInvoker, classBlock, classRules, createTestClass, filter, getDescription, getName, getRunnerAnnotations, getTestClass, order, run, runLeaf, setScheduler, sort, validatePublicVoidNoArgMethods, withAfterClasses, withBeforeClasses, withInterruptIsolation

Methods inherited from class org.junit.runner.Runner

testCount

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

TruffleRunner

public TruffleRunner(Class<?> klass)
              throws org.junit.runners.model.InitializationError

Should not be called directly. To use this class, annotate your test class with @RunWith(TruffleRunner.class).

Throws:

org.junit.runners.model.InitializationError

Since:

0.25

See Also:

• TruffleRunner

TruffleRunner

public TruffleRunner(org.junit.runners.model.TestClass testClass)
              throws org.junit.runners.model.InitializationError

Should not be called directly. To use this class, annotate your test class with @RunWith(TruffleRunner.class).

Throws:

org.junit.runners.model.InitializationError

Since:

24.2

See Also:

• TruffleRunner

Method Details

methodInvoker

protected final org.junit.runners.model.Statement methodInvoker(org.junit.runners.model.FrameworkMethod method,
 Object test)

Internal method used by the JUnit framework. Do not call directly.

Overrides:

methodInvoker in class org.junit.runners.BlockJUnit4ClassRunner

Since:

0.25

validateTestMethods

protected final void validateTestMethods(List<Throwable> errors)

Internal method used by the JUnit framework. Do not call directly.

Overrides:

validateTestMethods in class org.junit.runners.BlockJUnit4ClassRunner

Since:

0.25