From a07eea11981fc77994f33c7f0c460aeaec0748ab Mon Sep 17 00:00:00 2001 From: Stas Levin Date: Fri, 24 Feb 2017 00:02:14 +0200 Subject: [PATCH 1/4] Updated TestPipeline's javadoc. --- .../apache/beam/sdk/testing/TestPipeline.java | 39 +++++++++++++++---- 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java index 02eefa95d67b..26da494e946d 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java @@ -79,17 +79,24 @@ *

Use {@link PAssert} for tests, as it integrates with this test harness in both direct and * remote execution modes. For example: * - * 

{@code
- * Pipeline p = TestPipeline.create();
- * PCollection output = ...
+ * 

+ * {@literal @Rule}
+ * public final transient TestPipeline p = TestPipeline.create();
  *
- * PAssert.that(output)
- *     .containsInAnyOrder(1, 2, 3, 4);
- * p.run();
- * }

+ * {@literal @Test}
+ * {@literal @Category}(NeedsRunner.class)
+ * public void myPipelineTest() throws Exception {
+ *   final PCollection pCollection = pipeline.apply(...)
+ *   PAssert.that(pCollection).containsInAnyOrder(...);
+ *   pipeline.run();
+ * }
+ *
* *

For pipeline runners, it is required that they must throw an {@link AssertionError} containing * the message from the {@link PAssert} that failed. + * + *

See also the Testing documentation + * section.

*/ public class TestPipeline extends Pipeline implements TestRule { @@ -309,6 +316,20 @@ public PipelineResult run() { } } + /** + * Enables the abandoned node detection. Abandoned nodes are PTransforms, + * PAsserts included, that were not executed by the pipeline runner. Abandoned nodes are + * most likely to occur due to the one of the following scenarios: + * + * + * + * Abandoned node detection is automatically enabled when a real pipeline runner (i.e. not a + * {@link CrashingRunner}) and/or a {@link NeedsRunner} or a {@link RunnableOnService} annotation + * are detected. + */ public TestPipeline enableAbandonedNodeEnforcement(final boolean enable) { enforcement = enable @@ -318,6 +339,10 @@ public TestPipeline enableAbandonedNodeEnforcement(final boolean enable) { return this; } + /** + * If enabled, a pipeline.run() statement will be added automatically in case it is + * missing in the test. + */ public TestPipeline enableAutoRunIfMissing(final boolean enable) { enforcement.get().enableAutoRunIfMissing(enable); return this; From cc668f8e412486be9254adfb34f44f7defaba2e1 Mon Sep 17 00:00:00 2001 From: Stas Levin Date: Fri, 24 Feb 2017 00:50:48 +0200 Subject: [PATCH 2/4] An attempt at making the "enforcement level" not set exception clearer. --- .../main/java/org/apache/beam/sdk/testing/TestPipeline.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java index 26da494e946d..52a79d7443f3 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java @@ -299,8 +299,8 @@ public void evaluate() throws Throwable { public PipelineResult run() { checkState( enforcement.isPresent(), - "Attempted to run a pipeline while it's enforcement level was not set. Are you " - + "using TestPipeline without a @Rule annotation?"); + "Is your TestPipeline declaration missing a @Rule annotation? Usage: " + + "@Rule public final transient TestPipeline pipeline = TestPipeline.Create();"); try { return super.run(); From cc861e72abe9fba2edc50cf09d5b522449ee12a8 Mon Sep 17 00:00:00 2001 From: Stas Levin Date: Fri, 24 Feb 2017 16:23:24 +0200 Subject: [PATCH 3/4] Fixup! --- .../main/java/org/apache/beam/sdk/testing/TestPipeline.java | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java index 52a79d7443f3..5580ce5cfcb8 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java @@ -93,8 +93,7 @@ * * *

For pipeline runners, it is required that they must throw an {@link AssertionError} containing - * the message from the {@link PAssert} that failed. - * + * the message from the {@link PAssert} that failed.

*

See also the Testing documentation * section.

*/ @@ -320,12 +319,10 @@ public PipelineResult run() { * Enables the abandoned node detection. Abandoned nodes are PTransforms, * PAsserts included, 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. *
- * * Abandoned node detection is automatically enabled when a real pipeline runner (i.e. not a * {@link CrashingRunner}) and/or a {@link NeedsRunner} or a {@link RunnableOnService} annotation * are detected. From 109f1f09ce78fc886f03c556d32dac6d0a6ee84e Mon Sep 17 00:00:00 2001 From: Stas Levin Date: Fri, 24 Feb 2017 16:34:48 +0200 Subject: [PATCH 4/4] Fixup! --- .../src/main/java/org/apache/beam/sdk/testing/TestPipeline.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java index 5580ce5cfcb8..6c5244d03da0 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java @@ -86,7 +86,7 @@ * {@literal @Test} * {@literal @Category}(NeedsRunner.class) * public void myPipelineTest() throws Exception { - * final PCollection pCollection = pipeline.apply(...) + * final PCollection<String> pCollection = pipeline.apply(...) * PAssert.that(pCollection).containsInAnyOrder(...); * pipeline.run(); * }