Class TestPipeline
- All Implemented Interfaces:
TestRule
It is recommended to tag hand-selected tests for this purpose using the ValidatesRunner Category annotation, as each test run against a pipeline runner will
utilize resources of that pipeline runner.
In order to run tests on a pipeline runner, the following conditions must be met:
- System property "beamTestPipelineOptions" must contain a JSON delimited list of pipeline
options. For example:
Note that the set of pipeline options required is pipeline runner specific.[ "--runner=TestDataflowRunner", "--project=mygcpproject", "--stagingLocation=gs://mygcsbucket/path" ] - Jars containing the SDK and test classes must be available on the classpath.
Use PAssert for tests, as it integrates with this test harness in both direct and
remote execution modes.
JUnit 4 Usage
For JUnit 4 tests, use this class as a TestRule:
@Rule
public final transient TestPipeline p = TestPipeline.create();
@Test
@Category(NeedsRunner.class)
public void myPipelineTest() throws Exception {
final PCollection<String> pCollection = pipeline.apply(...)
PAssert.that(pCollection).containsInAnyOrder(...);
pipeline.run();
}
JUnit5 Usage
For JUnit5 tests, useTestPipelineExtension from the module
sdks/java/testing/junit (artifact org.apache.beam:beam-sdks-java-testing-junit
):
@ExtendWith(TestPipelineExtension.class)
class MyPipelineTest {
@Test
@Category(NeedsRunner.class)
void myPipelineTest(TestPipeline pipeline) {
final PCollection<String> pCollection = pipeline.apply(...)
PAssert.that(pCollection).containsInAnyOrder(...);
pipeline.run();
}
}
For pipeline runners, it is required that they must throw an AssertionError containing
the message from the PAssert that failed.
See also the Testing documentation section.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classAn exception thrown in case an abandonedPTransformis detected, that is, aPTransformthat has not been run.static classAn exception thrown in case a test finishes without invokingPipeline.run().static final classFor internal use only; no backwards-compatibility guarantees.static interfaceImplementation detail ofnewProvider(T), do not use.Nested classes/interfaces inherited from class org.apache.beam.sdk.Pipeline
Pipeline.PipelineExecutionException, Pipeline.PipelineVisitor -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringSystem property used to setTestPipelineOptions.static final StringSystem property which, whentrue, gives everyTestPipelinea unique root transform name of the formt<N>-<test name>as soon as its JUnit rule is applied. -
Method Summary
Modifier and TypeMethodDescriptionapply(Statement statement, Description description) static TestPipelinecreate()Creates and returns a new test pipeline.enableAbandonedNodeEnforcement(boolean enable) Enables the abandoned node detection.enableAutoRunIfMissing(boolean enable) If enabled, apipeline.run()statement will be added automatically in case it is missing in the test.static TestPipelinefromOptions(PipelineOptions options) For internal use only; no backwards-compatibility guarantees.booleanFor internal use only; no backwards-compatibility guarantees.voidFor internal use only; no backwards-compatibility guarantees.<T> ValueProvider<T> newProvider(T runtimeValue) Returns a newValueProviderthat is inaccessible beforerun(), but will be accessible while the pipeline runs.run()Runs thisTestPipeline, unwrapping anyAssertionErrorthat is raised during testing.run(PipelineOptions options) Likerun()but with the given potentially modified options.runWithAdditionalOptionArgs(List<String> additionalArgs) Runs thisTestPipelinewith additional cmd pipeline option args.static PipelineOptionsCreatesPipelineOptionsfor testing.toString()static voidverifyPAssertsSucceeded(Pipeline pipeline, PipelineResult pipelineResult) Verifies all {PAsserts} in the pipeline have been executed and were successful.Methods inherited from class org.apache.beam.sdk.Pipeline
apply, apply, applyTransform, applyTransform, begin, create, forTransformHierarchy, getCoderRegistry, getSchemaRegistry, registerBadRecordErrorHandler, replaceAll, setCoderRegistry, traverseTopologically
-
Field Details
-
PROPERTY_BEAM_TEST_PIPELINE_OPTIONS
System property used to setTestPipelineOptions.- See Also:
-
PROPERTY_BEAM_TEST_PIPELINE_UNIQUE_ROOT_NAMES
System property which, whentrue, gives everyTestPipelinea unique root transform name of the formt<N>-<test name>as soon as its JUnit rule is applied. Every transform andPCollectionname in the test is then prefixed by it (for examplet12-ParDoTest$BasicTests-testParDo/ParDo(Anonymous)), so the graphs of different tests never share a name. Runners that merge several test pipelines into one job rely on this; seegetRootName().- See Also:
-
-
Method Details
-
create
Creates and returns a new test pipeline.Use
PAssertto add tests, then callPipeline.run()to execute the pipeline and check the tests. -
fromOptions
-
getOptions
- Overrides:
getOptionsin classPipeline
-
apply
-
getRootName
For internal use only; no backwards-compatibility guarantees.Returns the unique root transform name of this pipeline, or the empty string if it has none (see
PROPERTY_BEAM_TEST_PIPELINE_UNIQUE_ROOT_NAMES). When non-empty, every full transform name in this pipeline starts withgetRootName() + "/". -
nameRoot
For internal use only; no backwards-compatibility guarantees.Gives this pipeline a unique root name of the form
t<N>-<testName>(sanitized and truncated). Normally invoked by the JUnit rule or extension; only has an effect if no transform has been applied yet, otherwise a warning is logged and the pipeline stays unnamed. -
isStandaloneExecutionRequired
For internal use only; no backwards-compatibility guarantees.Returns
trueif thisTestPipelineshould not be merged into a shared batch pipeline (for example, when the test expects an exception or assertion failure, uses custom per-test option arguments, is marked for serial execution, or is being re-executed after a merged attempt; seeTestPipeline.StandaloneRerunRequested). -
run
Runs thisTestPipeline, unwrapping anyAssertionErrorthat is raised during testing. -
runWithAdditionalOptionArgs
Runs thisTestPipelinewith additional cmd pipeline option args.This is useful when using
PipelineOptions.as(Class)directly introduces circular dependency.Most of logic is similar to
testingPipelineOptions(). -
run
Likerun()but with the given potentially modified options. -
newProvider
Returns a newValueProviderthat is inaccessible beforerun(), but will be accessible while the pipeline runs. -
enableAbandonedNodeEnforcement
Enables the abandoned node detection. Abandoned nodes arePTransforms,PAssertsincluded, that were not executed by the pipeline runner. Abandoned nodes are most likely to occur due to the one of the following scenarios:- Lack of a
pipeline.run()statement at the end of a test. - Addition of PTransforms after the pipeline has already run.
CrashingRunner) and/or aNeedsRunneror aValidatesRunnerannotation are detected. - Lack of a
-
enableAutoRunIfMissing
If enabled, apipeline.run()statement will be added automatically in case it is missing in the test. -
toString
-
testingPipelineOptions
CreatesPipelineOptionsfor testing. -
verifyPAssertsSucceeded
Verifies all {PAsserts} in the pipeline have been executed and were successful.Note this only runs for runners which support Metrics. Runners which do not should verify this in some other way. See: https://issues.apache.org/jira/browse/BEAM-2001
-