This is an automated email from the ASF dual-hosted git repository. git-site-role pushed a commit to branch asf-site in repository https://gitbox.apache.org/repos/asf/beam.git
The following commit(s) were added to refs/heads/asf-site by this push: new 89207a5 Publishing website 2019/01/17 02:12:38 at commit 1c1c7be 89207a5 is described below commit 89207a518d93339d676cea1ca878a64e816572f8 Author: jenkins <bui...@apache.org> AuthorDate: Thu Jan 17 02:12:38 2019 +0000 Publishing website 2019/01/17 02:12:38 at commit 1c1c7be --- .../contribute/become-a-committer/index.html | 2 +- .../contribute/committer-guide/index.html | 2 +- .../contribute/dependencies/index.html | 2 +- .../contribute/design-documents/index.html | 2 +- .../contribute/docker-images/index.html | 2 +- .../contribute/feature-branches/index.html | 2 +- .../contribute/get-help/index.html | 2 +- website/generated-content/contribute/index.html | 4 +- .../contribute/postcommits-guides/index.html | 2 +- .../postcommits-policies-details/index.html | 2 +- .../contribute/postcommits-policies/index.html | 4 +- .../contribute/precommit-policies/index.html | 2 +- .../contribute/precommit-triage-guide/index.html | 4 +- .../contribute/ptransform-style-guide/index.html | 4 +- .../contribute/release-guide/index.html | 2 +- .../contribute/runner-guide/index.html | 2 +- .../contribute/testing/index.html | 746 +-------------------- 17 files changed, 28 insertions(+), 758 deletions(-) diff --git a/website/generated-content/contribute/become-a-committer/index.html b/website/generated-content/contribute/become-a-committer/index.html index da5c0df..524de5c 100644 --- a/website/generated-content/contribute/become-a-committer/index.html +++ b/website/generated-content/contribute/become-a-committer/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/committer-guide/index.html b/website/generated-content/contribute/committer-guide/index.html index bd4ad74..b8b889f 100644 --- a/website/generated-content/contribute/committer-guide/index.html +++ b/website/generated-content/contribute/committer-guide/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/dependencies/index.html b/website/generated-content/contribute/dependencies/index.html index d9ff8ff..f1ea86a 100644 --- a/website/generated-content/contribute/dependencies/index.html +++ b/website/generated-content/contribute/dependencies/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/design-documents/index.html b/website/generated-content/contribute/design-documents/index.html index 4491de2..ce8cf2f 100644 --- a/website/generated-content/contribute/design-documents/index.html +++ b/website/generated-content/contribute/design-documents/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/docker-images/index.html b/website/generated-content/contribute/docker-images/index.html index 59ee66a..48a2a34 100644 --- a/website/generated-content/contribute/docker-images/index.html +++ b/website/generated-content/contribute/docker-images/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/feature-branches/index.html b/website/generated-content/contribute/feature-branches/index.html index 2965018..1ecbed7c 100644 --- a/website/generated-content/contribute/feature-branches/index.html +++ b/website/generated-content/contribute/feature-branches/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/get-help/index.html b/website/generated-content/contribute/get-help/index.html index 3de7cb9..07e210a 100644 --- a/website/generated-content/contribute/get-help/index.html +++ b/website/generated-content/contribute/get-help/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/index.html b/website/generated-content/contribute/index.html index 78cdc94..86b5760 100644 --- a/website/generated-content/contribute/index.html +++ b/website/generated-content/contribute/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> @@ -393,7 +393,7 @@ This will automatically link the pull request to the issue. Use descriptive commit messages that make it easy to identify changes and provide a clear history. To support efficient and quality review, avoid tiny or out-of-context changes and huge mega-changes.</li> <li> - <p>The pull request and any changes pushed to it will trigger <a href="/contribute/testing/">pre-commit + <p>The pull request and any changes pushed to it will trigger <a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide#ContributionTestingGuide-Pre-commit">pre-commit jobs</a>. If a test fails and appears unrelated to your change, you can cause tests to be re-run by adding a single line comment on your PR</p> diff --git a/website/generated-content/contribute/postcommits-guides/index.html b/website/generated-content/contribute/postcommits-guides/index.html index f7144c7..d45928f 100644 --- a/website/generated-content/contribute/postcommits-guides/index.html +++ b/website/generated-content/contribute/postcommits-guides/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/postcommits-policies-details/index.html b/website/generated-content/contribute/postcommits-policies-details/index.html index da1fa26..fa6a2b4 100644 --- a/website/generated-content/contribute/postcommits-policies-details/index.html +++ b/website/generated-content/contribute/postcommits-policies-details/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/postcommits-policies/index.html b/website/generated-content/contribute/postcommits-policies/index.html index 74ada15..428567d 100644 --- a/website/generated-content/contribute/postcommits-policies/index.html +++ b/website/generated-content/contribute/postcommits-policies/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> @@ -322,7 +322,7 @@ to do with what is being tested, making our signal unreliable.</li> <h2 id="useful-links">Useful links</h2> <ul> - <li><a href="/contribute/testing/index.html#best_practices">Best practices for writing tests</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide#ContributionTestingGuide-Bestpracticesforwritingtests">Best practices for writing tests</a></li> </ul> <h2 id="references">References</h2> diff --git a/website/generated-content/contribute/precommit-policies/index.html b/website/generated-content/contribute/precommit-policies/index.html index c66e813..326b08e 100644 --- a/website/generated-content/contribute/precommit-policies/index.html +++ b/website/generated-content/contribute/precommit-policies/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/precommit-triage-guide/index.html b/website/generated-content/contribute/precommit-triage-guide/index.html index 8963347..cfd6d3b 100644 --- a/website/generated-content/contribute/precommit-triage-guide/index.html +++ b/website/generated-content/contribute/precommit-triage-guide/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> @@ -245,7 +245,7 @@ limitations under the License. machines for each pull request (PR) submitted to <a href="https://github.com/apache/beam">apache/beam</a>. For more information and the difference between pre-commits and post-commits, see -<a href="/contribute/testing/">testing</a>.</p> +<a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">testing</a>.</p> <h2 id="what-are-fast-pre-commits">What are fast pre-commits?</h2> diff --git a/website/generated-content/contribute/ptransform-style-guide/index.html b/website/generated-content/contribute/ptransform-style-guide/index.html index 445300f..e6d7f80 100644 --- a/website/generated-content/contribute/ptransform-style-guide/index.html +++ b/website/generated-content/contribute/ptransform-style-guide/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> @@ -502,7 +502,7 @@ E.g. when expanding a filepattern into files, log what the filepattern was and h <li>To unit test <code class="highlighter-rouge">DoFn</code>s, <code class="highlighter-rouge">CombineFn</code>s, and <code class="highlighter-rouge">BoundedSource</code>s, consider using <code class="highlighter-rouge">DoFnTester</code>, <code class="highlighter-rouge">CombineFnTester</code>, and <code class="highlighter-rouge">SourceTestUtils</code> respectively which can exercise the code in non-trivial ways to flesh out potential bugs.</li> <li>For transforms that work over unbounded collections, test their behavior in the presence of late or out-of-order data using <code class="highlighter-rouge">TestStream</code>.</li> <li>Tests must pass 100% of the time, including in hostile, CPU- or network-constrained environments (continuous integration servers). Never put timing-dependent code (e.g. sleeps) into tests. Experience shows that no reasonable amount of sleeping is enough - code can be suspended for more than several seconds.</li> - <li>For detailed instructions on test code organization, see the <a href="/contribute/testing/">Beam Testing Guide</a>.</li> + <li>For detailed instructions on test code organization, see the <a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Beam Testing Guide</a>.</li> </ul> <h4 id="testing-transform-construction-and-validation">Testing transform construction and validation</h4> diff --git a/website/generated-content/contribute/release-guide/index.html b/website/generated-content/contribute/release-guide/index.html index 24caad3..8476f3c 100644 --- a/website/generated-content/contribute/release-guide/index.html +++ b/website/generated-content/contribute/release-guide/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/runner-guide/index.html b/website/generated-content/contribute/runner-guide/index.html index 657f21b..a84c7e3 100644 --- a/website/generated-content/contribute/runner-guide/index.html +++ b/website/generated-content/contribute/runner-guide/index.html @@ -157,7 +157,7 @@ <span class="section-nav-list-title">Technical Docs</span> <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> + <li><a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Testing guide</a></li> <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> diff --git a/website/generated-content/contribute/testing/index.html b/website/generated-content/contribute/testing/index.html index 198e978..c549125 100644 --- a/website/generated-content/contribute/testing/index.html +++ b/website/generated-content/contribute/testing/index.html @@ -1,740 +1,10 @@ <!DOCTYPE html> -<!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. See accompanying LICENSE file. ---> - -<html lang="en"> - <!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. See accompanying LICENSE file. ---> - -<head> - <meta charset="utf-8"> - <meta http-equiv="X-UA-Compatible" content="IE=edge"> - <meta name="viewport" content="width=device-width, initial-scale=1"> - <title>Beam Testing</title> - <meta name="description" content="Apache Beam is an open source, unified model and set of language-specific SDKs for defining and executing data processing workflows, and also data ingestion and integration flows, supporting Enterprise Integration Patterns (EIPs) and Domain Specific Languages (DSLs). Dataflow pipelines simplify the mechanics of large-scale batch and streaming data processing and can run on a number of runtimes like Apache Flink, Apache Spark, and Google Cloud Dataflow [...] -"> - <link href="https://fonts.googleapis.com/css?family=Roboto:100,300,400" rel="stylesheet"> - <link rel="stylesheet" href="/css/site.css"> - <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js"></script> - <script src="/js/bootstrap.min.js"></script> - <script src="/js/language-switch.js"></script> - <script src="/js/fix-menu.js"></script> - <script src="/js/section-nav.js"></script> - <script src="/js/page-nav.js"></script> - <link rel="canonical" href="https://beam.apache.org/contribute/testing/" data-proofer-ignore> - <link rel="shortcut icon" type="image/x-icon" href="/images/favicon.ico"> - <link rel="alternate" type="application/rss+xml" title="Apache Beam" href="https://beam.apache.org/feed.xml"> - <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.4.1/css/all.css" integrity="sha384-5sAR7xN1Nv6T6+dT2mhtzEpVJvfS3NScPQTrOxhwjIuvcA67KV2R5Jz6kr4abQsz" crossorigin="anonymous"> - <script> - (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ - (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), - m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) - })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); - ga('create', 'UA-73650088-1', 'auto'); - ga('send', 'pageview'); - </script> -</head> - - <body class="body" data-spy="scroll" data-target=".page-nav" data-offset="0"> - <!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. See accompanying LICENSE file. ---> - -<nav class="header navbar navbar-fixed-top"> - <div class="navbar-header"> - <button type="button" class="navbar-toggle" aria-expanded="false" aria-controls="navbar"> - <span class="sr-only">Toggle navigation</span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - </button> - - <a href="/" class="navbar-brand" > - <img alt="Brand" style="height: 25px" src="/images/beam_logo_navbar.png"> - </a> - </div> - - <div class="navbar-mask closed"></div> - - <div id="navbar" class="navbar-container closed"> - <ul class="nav navbar-nav"> - <li> - <a href="/get-started/beam-overview/">Get Started</a> - </li> - <li> - <a href="/documentation/">Documentation</a> - </li> - <li> - <a href="/documentation/sdks/java/">Languages</a> - </li> - <li> - <a href="/documentation/runners/capability-matrix/">RUNNERS</a> - </li> - <li> - <a href="/roadmap/">Roadmap</a> - </li> - <li> - <a href="/contribute/">Contribute</a> - </li> - <li> - <a href="/community/contact-us/">Community</a> - </li> - <li><a href="/blog">Blog</a></li> - </ul> - <ul class="nav navbar-nav navbar-right"> - <li class="dropdown"> - <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false"><img src="https://www.apache.org/foundation/press/kit/feather_small.png" alt="Apache Logo" style="height:20px;"><span class="caret"></span></a> - <ul class="dropdown-menu dropdown-menu-right"> - <li><a href="http://www.apache.org/">ASF Homepage</a></li> - <li><a href="http://www.apache.org/licenses/">License</a></li> - <li><a href="http://www.apache.org/security/">Security</a></li> - <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> - <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> - <li><a href="https://www.apache.org/foundation/policies/conduct">Code of Conduct</a></li> - </ul> - </li> - <li> - <!-- - data-proofer-ignore disables link checking from website test automation. - GitHub links will not resolve until the markdown source is available on the master branch. - New pages would fail validation during development / PR test automation. - --> - <a href="https://github.com/apache/beam/edit/master/website/src/contribute/testing.md" data-proofer-ignore> - <i class="far fa-edit fa-lg" alt="Edit on GitHub" title="Edit on GitHub"></i> - </a> - </li> - </ul> - </div> -</nav> - - <div class="clearfix container-main-content"> - <div class="section-nav closed" data-offset-top="90" data-offset-bottom="500"> - <span class="section-nav-back glyphicon glyphicon-menu-left"></span> - <nav> - <ul class="section-nav-list" data-section-nav> - <!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. See accompanying LICENSE file. ---> - -<li><span class="section-nav-list-main-title">Contribute</span></li> -<li><a href="/contribute/">Get started contributing</a></li> -<li><a href="/contribute/get-help/">Get Help</a></li> -<li> - <span class="section-nav-list-title">Technical Docs</span> - - <ul class="section-nav-list"> - <li><a href="/contribute/testing/">Testing guide</a></li> - <li><a href="/contribute/precommit-triage-guide/">Pre-commit Slowness Triage</a></li> - <li><a href="/contribute/ptransform-style-guide/">PTransform style guide</a></li> - <li><a href="/contribute/runner-guide/">Runner authoring guide</a></li> - <li><a href="/contribute/docker-images/">Docker images</a></li> - <li><a href="/contribute/design-documents/">Design documents</a></li> - <li><a href="/contribute/dependencies/">Dependencies guide</a></li> - <li><a href="/contribute/feature-branches/">Feature branches</a></li> - </ul> -</li> -<li> - <span class="section-nav-list-title">Policies</span> - <ul class="section-nav-list"> - <li><a href="/contribute/precommit-policies/">Pre-commit test policies</a></li> - <li><a href="/contribute/postcommits-policies/">Post-commit test policies</a></li> - </ul> -</li> -<li> - <span class="section-nav-list-title">Committers</span> - <ul class="section-nav-list"> - <li><a href="/contribute/become-a-committer/">Become a committer</a></li> - <li><a href="/contribute/committer-guide/">Committer guide</a></li> - <li><a href="/contribute/release-guide/">Release guide</a></li> - </ul> -</li> - - </ul> - </nav> - </div> - - <nav class="page-nav clearfix" data-offset-top="90" data-offset-bottom="500"> - <!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. See accompanying LICENSE file. ---> - - - -<ul class="nav"> - <li><a href="#testing-scenarios">Testing Scenarios</a> - <ul> - <li><a href="#pre-commit">Pre-commit</a></li> - <li><a href="#post-commit">Post-commit</a></li> - </ul> - </li> - <li><a href="#testing-types">Testing Types</a> - <ul> - <li><a href="#unit">Unit</a></li> - <li><a href="#validatesrunner">ValidatesRunner</a></li> - <li><a href="#e2e">E2E</a></li> - </ul> - </li> - <li><a href="#testing-systems">Testing Systems</a> - <ul> - <li><a href="#e2e-testing-framework">E2E Testing Framework</a></li> - <li><a href="#validatesrunner-tests">ValidatesRunner Tests</a></li> - <li><a href="#effective-use-of-the-testpipeline-junit-rule">Effective use of the TestPipeline JUnit rule</a></li> - <li><a href="#api-surface-testing">API Surface testing</a></li> - </ul> - </li> - <li><a href="#best_practices">Best practices for writing tests</a> - <ul> - <li><a href="#aim-for-one-failure-path">Aim for one failure path</a></li> - <li><a href="#avoid-non-deterministic-code">Avoid non-deterministic code</a></li> - <li><a href="#use-descriptive-test-names">Use descriptive test names</a></li> - <li><a href="#use-a-pre-commit-test-if-possible">Use a pre-commit test if possible</a></li> - </ul> - </li> -</ul> - - - </nav> - - <div class="body__contained body__section-nav"> - <!-- -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. ---> - -<h1 id="beam-testing">Beam Testing</h1> - -<p>This document outlines how to write tests, which tests are appropriate where, -and when tests are run, with some additional information about the testing -systems at the bottom.</p> - -<h2 id="testing-scenarios">Testing Scenarios</h2> - -<p>Ideally, all available tests should be run against a pull request (PR) before -it’s allowed to be committed to Beam’s <a href="https://github.com/apache/beam">Github</a> -repo. This is not possible, however, due to a combination of time and resource -constraints. Running all tests for each PR would take hours or even days using -available resources, which would slow down development considerably.</p> - -<p>Thus tests are split into <em>pre-commit</em> and <em>post-commit</em> suites. Pre-commit is -fast, while post-commit is comprehensive. As their names imply, pre-commit tests -are run on each PR before it is committed, while post-commits run periodically -against the master branch (i.e. on already committed PRs).</p> - -<p>Beam uses <a href="https://builds.apache.org/view/A-D/view/Beam/">Jenkins</a> to run -pre-commit and post-commit tests.</p> - -<h3 id="pre-commit">Pre-commit</h3> - -<p>The pre-commit test suite verifies correctness via two testing tools: unit tests -and end-to-end (E2E) tests. Unit tests ensure correctness at a basic level, -while WordCount E2E tests are run againsts each supported SDK / runner -combination as a smoke test, to verify that a basic level of functionality -exists.</p> - -<p>This combination of tests hits the appropriate tradeoff between a desire for -short (ideally <30m) pre-commit times and a desire to verify that PRs going -into Beam function in the way in which they are intended.</p> - -<p>Pre-commit jobs are kicked off when a contributor makes a PR against the -<code class="highlighter-rouge">apache/beam</code> repository. Job statuses are displayed at the bottom of the PR -page. Clicking on “Details” will open the status page in the selected tool; -there, you can view test status and output.</p> - -<h3 id="post-commit">Post-commit</h3> - -<p>Running in post-commit removes as stringent of a time constraint, which gives us -the ability to do some more comprehensive testing. In post-commit we have a test -suite running the ValidatesRunner tests against each supported runner, and -another for running the full set of E2E tests against each runner. -Currently-supported runners are Dataflow, Flink, Spark, and Gearpump, with -others soon to follow. Work is ongoing to enable Flink, Spark, and Gearpump in -the E2E framework, with full support targeted for end of August 2016. -Post-commit tests run periodically, with timing defined in their Jenkins -configurations.</p> - -<p>Adding new post-commit E2E tests is generally as easy as adding a *IT.java file -to the repository - Failsafe will notice it and run it - but if you want to do -more interesting things, take a look at -<a href="https://github.com/apache/beam/blob/master/examples/java/src/test/java/org/apache/beam/examples/WordCountIT.java">WordCountIT.java</a>.</p> - -<p>Post-commit test results can be found in -<a href="https://builds.apache.org/view/A-D/view/Beam/">Jenkins</a>.</p> - -<h2 id="testing-types">Testing Types</h2> - -<h3 id="unit">Unit</h3> - -<p>Unit tests are, in Beam as everywhere else, the first line of defense in -ensuring software correctness. As all of the contributors to Beam understand the -importance of testing, Beam has a robust set of unit tests, as well as testing -coverage measurement tools, which protect the codebase from simple to moderate -breakages. Beam Java unit tests are written in JUnit.</p> - -<h4 id="how-to-run-python-unit-tests">How to run Python unit tests</h4> - -<p>Python tests are written using the standard Python unittest library. -To run all unit tests, execute the following command in the <code class="highlighter-rouge">sdks/python</code> -subdirectory</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>$ python setup.py test [-s apache_beam.package.module.TestClass.test_method] -</code></pre> -</div> - -<p>We also provide a <a href="https://tox.readthedocs.io/en/latest/">tox</a> configuration -in that same directory to run all the tests, including lint, cleanly in all -desired configurations.</p> - -<h4 id="how-to-run-java-needsrunner-tests">How to run Java NeedsRunner tests</h4> - -<p>NeedsRunner is a category of tests that require a Beam runner. To run -NeedsRunner tests:</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>$ ./gradlew beam-runners-direct-java:needsRunnerTests -</code></pre> -</div> - -<p>To run a single NeedsRunner test use the <code class="highlighter-rouge">test</code> property, e.g.</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>$ ./gradlew beam-runners-direct-java:needsRunnerTests --tests org.apache.beam.sdk.transforms.MapElementsTest.testMapBasic -</code></pre> -</div> - -<p>will run the <code class="highlighter-rouge">MapElementsTest.testMapBasic()</code> test.</p> - -<p>NeedsRunner tests in modules that are not required to build runners (e.g. -<code class="highlighter-rouge">sdks/java/io/google-cloud-platform</code>) can be executed with the <code class="highlighter-rouge">gradle test</code> -command:</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>$ ./gradlew beam-sdks-java-io-google-cloud-platform:test --tests org.apache.beam.sdk.io.gcp.spanner.SpannerIOWriteTest -</code></pre> -</div> - -<h3 id="validatesrunner">ValidatesRunner</h3> - -<p>ValidatesRunner tests contain components of both component and end-to-end -tests. They fulfill the typical purpose of a component test - they are meant to -test a well-scoped piece of Beam functionality or the interactions between two -such pieces and can be run in a component-test-type fashion against the -DirectRunner. Additionally, they are built with the ability to run in an -end-to-end fashion against a runner, allowing them to verify not only core Beam -functionality, but runner functionality as well. They are more lightweight than -a traditional end-to-end test and, because of their well-scoped nature, provide -good signal as to what exactly is working or broken against a particular runner.</p> - -<h3 id="e2e">E2E</h3> - -<p>End-to-End tests are meant to verify at the very highest level that the Beam -codebase is working as intended. Because they are implemented as a thin wrapper -around existing pipelines, they can be used to prove that the core Beam -functionality is available. They will be used to verify runner correctness, but -they can also be used for IO connectors and other core functionality.</p> - -<h2 id="testing-systems">Testing Systems</h2> - -<h3 id="e2e-testing-framework">E2E Testing Framework</h3> - -<p>The Beam end-to-end testing framework is a framework designed in a -runner-agnostic fashion to exercise the entire lifecycle of a Beam pipeline. We -run a pipeline as a user would and allow it to run to completion in the same -way, verifying after completion that it behaved how we expected. Using pipelines -from the Beam examples, or custom-built pipelines, the framework will provide -hooks during several pipeline lifecycle events, e.g., pipeline creation, -pipeline success, and pipeline failure, to allow verification of pipeline state.</p> - -<p>The E2E testing framework is currently built to execute the tests in <a href="https://github.com/GoogleCloudPlatform/PerfKitBenchmarker">PerfKit -Benchmarker</a>, -invoked via Gradle tasks. Once it is determined how Python and other future -languages will integrate into the overall build/test system (via Gradle or -otherwise) we will adjust this. The framework provides a wrapper around actual -Beam pipelines, enabling those pipelines to be run in an environment which -facilitates verification of pipeline results and details.</p> - -<p>Verifiers include:</p> - -<ul> - <li>Output verification. Output verifiers ensure that the pipeline has produced -the expected output. Current verifiers check text-based output, but future -verifiers could support other output such as BigQuery and Datastore.</li> - <li>Aggregator verification. Aggregator verifiers ensure that the user-defined -aggregators present in the pipelines under test finish in the expected -state.</li> -</ul> - -<p>The E2E framework will support running on various different configurations of -environments. We currently provide the ability to run against the DirectRunner, -against a local Spark instance, a local Flink instance, and against the Google -Cloud Dataflow service.</p> - -<h3 id="validatesrunner-tests">ValidatesRunner Tests</h3> - -<p>ValidatesRunner tests are tests built to use the Beam TestPipeline class, -which enables test authors to write simple functionality verification. They are -meant to use some of the built-in utilities of the SDK, namely PAssert, to -verify that the simple pipelines they run end in the correct state.</p> - -<h3 id="effective-use-of-the-testpipeline-junit-rule">Effective use of the TestPipeline JUnit rule</h3> - -<p><code class="highlighter-rouge">TestPipeline</code> is JUnit rule designed to facilitate testing pipelines. -In combination with <code class="highlighter-rouge">PAssert</code>, the two can be used for testing and -writing assertions over pipelines. However, in order for these assertions -to be effective, the constructed pipeline <strong>must</strong> be run by a pipeline -runner. If the pipeline is not run (i.e., executed) then the -constructed <code class="highlighter-rouge">PAssert</code> statements will not be triggered, and will thus -be ineffective.</p> - -<p>To prevent such cases, <code class="highlighter-rouge">TestPipeline</code> has some protection mechanisms in place.</p> - -<p><strong>Abandoned node detection (performed automatically)</strong></p> - -<p>Abandoned nodes are <code class="highlighter-rouge">PTransforms</code>, <code class="highlighter-rouge">PAsserts</code> included, that were not -executed by the pipeline runner. Abandoned nodes are most likely to occur -due to the one of the following scenarios:</p> -<ol> - <li>Lack of a <code class="highlighter-rouge">pipeline.run()</code> statement at the end of a test.</li> - <li>Addition of <code class="highlighter-rouge">PTransform</code>s after the pipeline has already run.</li> -</ol> - -<p>Abandoned node detection is <em>automatically enabled</em> when a real pipeline -runner (i.e. not a <code class="highlighter-rouge">CrashingRunner</code>) and/or a -<code class="highlighter-rouge">@NeedsRunner</code> / <code class="highlighter-rouge">@ValidatesRunner</code> annotation are detected.</p> - -<p>Consider the following test:</p> - -<div class="language-java highlighter-rouge"><pre class="highlight"><code><span class="c1">// Note the @Rule annotation here</span> -<span class="nd">@Rule</span> -<span class="kd">public</span> <span class="kd">final</span> <span class="kd">transient</span> <span class="n">TestPipeline</span> <span class="n">pipeline</span> <span class="o">=</span> <span class="n">TestPipeline</span><span class="o">.</span><span class="na">create</span><span class="o">();</span> - -<span class="nd">@Test</span> -<span class="nd">@Category</span><span class="o">(</span><span class="n">NeedsRunner</span><span class="o">.</span><span class="na">class</span><span class="o">)</span> -<span class="kd">public</span> <span class="kt">void</span> <span class="nf">myPipelineTest</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span> - -<span class="kd">final</span> <span class="n">PCollection</span><span class="o"><</span><span class="n">String</span><span class="o">></span> <span class="n">pCollection</span> <span class="o">=</span> - <span class="n">pipeline</span> - <span class="o">.</span><span class="na">apply</span><span class="o">(</span><span class="s">"Create"</span><span class="o">,</span> <span class="n">Create</span><span class="o">.</span><span class="na">of</span><span class="o">(</span><span class="n">WORDS</span><span class="o">).</span><span class="na">withCoder</span><span class="o">(</span><span class="n">StringUtf8Coder</span><span class="o">.</span><span class="na">of</span><span class="o">()))</span> - <span class="o">.</span><span class="na">apply</span><span class="o">(</span> - <span class="s">"Map1"</span><span class="o">,</span> - <span class="n">MapElements</span><span class="o">.</span><span class="na">via</span><span class="o">(</span> - <span class="k">new</span> <span class="n">SimpleFunction</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>()</span> <span class="o">{</span> - - <span class="nd">@Override</span> - <span class="kd">public</span> <span class="n">String</span> <span class="nf">apply</span><span class="o">(</span><span class="kd">final</span> <span class="n">String</span> <span class="n">input</span><span class="o">)</span> <span class="o">{</span> - <span class="k">return</span> <span class="n">WHATEVER</span><span class="o">;</span> - <span class="o">}</span> - <span class="o">}));</span> - -<span class="n">PAssert</span><span class="o">.</span><span class="na">that</span><span class="o">(</span><span class="n">pCollection</span><span class="o">).</span><span class="na">containsInAnyOrder</span><span class="o">(</span><span class="n">WHATEVER</span><span class="o">);</span> - -<span class="cm">/* ERROR: pipeline.run() is missing, PAsserts are ineffective */</span> -<span class="o">}</span> -</code></pre> -</div> - -<div class="language-py highlighter-rouge"><pre class="highlight"><code><span class="c"># The suggested pattern of using pipelines as targets of with statements</span> -<span class="c"># eliminates the possibility for this kind of error or a framework</span> -<span class="c"># to catch it.</span> - -<span class="k">with</span> <span class="n">beam</span><span class="o">.</span><span class="n">Pipeline</span><span class="p">(</span><span class="o">...</span><span class="p">)</span> <span class="k">as</span> <span class="n">p</span><span class="p">:</span> - <span class="p">[</span><span class="o">...</span><span class="n">arbitrary</span> <span class="n">construction</span><span class="o">...</span><span class="p">]</span> - <span class="c"># p.run() is automatically called on successfully exiting the context</span> -</code></pre> -</div> - -<p>The <code class="highlighter-rouge">PAssert</code> at the end of this test method will not be executed, since -<code class="highlighter-rouge">pipeline</code> is never run, making this test ineffective. If this test method -is run using an actual pipeline runner, an exception will be thrown -indicating that there was no <code class="highlighter-rouge">run()</code> invocation in the test.</p> - -<p>Exceptions that are thrown prior to executing a pipeline, will fail -the test unless handled by an <code class="highlighter-rouge">ExpectedException</code> rule.</p> - -<p>Consider the following test:</p> - -<div class="language-java highlighter-rouge"><pre class="highlight"><code><span class="c1">// Note the @Rule annotation here</span> -<span class="nd">@Rule</span> -<span class="kd">public</span> <span class="kd">final</span> <span class="kd">transient</span> <span class="n">TestPipeline</span> <span class="n">pipeline</span> <span class="o">=</span> <span class="n">TestPipeline</span><span class="o">.</span><span class="na">create</span><span class="o">();</span> - -<span class="nd">@Test</span> -<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testReadingFailsTableDoesNotExist</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span> - <span class="kd">final</span> <span class="n">String</span> <span class="n">table</span> <span class="o">=</span> <span class="s">"TEST-TABLE"</span><span class="o">;</span> - - <span class="n">BigtableIO</span><span class="o">.</span><span class="na">Read</span> <span class="n">read</span> <span class="o">=</span> - <span class="n">BigtableIO</span><span class="o">.</span><span class="na">read</span><span class="o">()</span> - <span class="o">.</span><span class="na">withBigtableOptions</span><span class="o">(</span><span class="n">BIGTABLE_OPTIONS</span><span class="o">)</span> - <span class="o">.</span><span class="na">withTableId</span><span class="o">(</span><span class="n">table</span><span class="o">)</span> - <span class="o">.</span><span class="na">withBigtableService</span><span class="o">(</span><span class="n">service</span><span class="o">);</span> - - <span class="c1">// Exception will be thrown by read.validate() when read is applied.</span> - <span class="n">thrown</span><span class="o">.</span><span class="na">expect</span><span class="o">(</span><span class="n">IllegalArgumentException</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> - <span class="n">thrown</span><span class="o">.</span><span class="na">expectMessage</span><span class="o">(</span><span class="n">String</span><span class="o">.</span><span class="na">format</span><span class="o">(</span><span class="s">"Table %s does not exist"</span><span class="o">,</span> <span class="n">table</span><span class="o">));</span> - - <span class="n">p</span><span class="o">.</span><span class="na">apply</span><span class="o">(</span><span class="n">read</span><span class="o">);</span> -<span class="o">}</span> -</code></pre> -</div> - -<div class="language-py highlighter-rouge"><pre class="highlight"><code><span class="c"># Unneeded in Beam's Python SDK.</span> -</code></pre> -</div> - -<p>The application of the <code class="highlighter-rouge">read</code> transform throws an exception, which is then -handled by the <code class="highlighter-rouge">thrown</code> <code class="highlighter-rouge">ExpectedException</code> rule. -In light of this exception, the fact this test has abandoned nodes -(the <code class="highlighter-rouge">read</code> transform) does not play a role since the test fails before -the pipeline would have been executed (had there been a <code class="highlighter-rouge">run()</code> statement).</p> - -<p><strong>Auto-add <code class="highlighter-rouge">pipeline.run()</code> (disabled by default)</strong></p> - -<p>A <code class="highlighter-rouge">TestPipeline</code> instance can be configured to auto-add a missing <code class="highlighter-rouge">run()</code> -statement by setting <code class="highlighter-rouge">testPipeline.enableAutoRunIfMissing(true/false)</code>. -If this feature is enabled, no exception will be thrown in case of a -missing <code class="highlighter-rouge">run()</code> statement, instead, one will be added automatically.</p> - -<h3 id="api-surface-testing">API Surface testing</h3> - -<p>The surface of an API is the set of public classes that are exposed to the -outer world. In order to keep the API tight and avoid unnecessarily exposing -classes, Beam provides the <code class="highlighter-rouge">ApiSurface</code> utility class. -Using the <code class="highlighter-rouge">ApiSurface</code> class, we can assert the API surface against an -expected set of classes.</p> - -<p>Consider the following snippet:</p> -<div class="language-java highlighter-rouge"><pre class="highlight"><code><span class="nd">@Test</span> -<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testMyApiSurface</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span> - - <span class="kd">final</span> <span class="n">Package</span> <span class="n">thisPackage</span> <span class="o">=</span> <span class="n">getClass</span><span class="o">().</span><span class="na">getPackage</span><span class="o">();</span> - <span class="kd">final</span> <span class="n">ClassLoader</span> <span class="n">thisClassLoader</span> <span class="o">=</span> <span class="n">getClass</span><span class="o">().</span><span class="na">getClassLoader</span><span class="o">();</span> - - <span class="kd">final</span> <span class="n">ApiSurface</span> <span class="n">apiSurface</span> <span class="o">=</span> - <span class="n">ApiSurface</span><span class="o">.</span><span class="na">ofPackage</span><span class="o">(</span><span class="n">thisPackage</span><span class="o">,</span> <span class="n">thisClassLoader</span><span class="o">)</span> - <span class="o">.</span><span class="na">pruningPattern</span><span class="o">(</span><span class="s">"org[.]apache[.]beam[.].*Test.*"</span><span class="o">)</span> - <span class="o">.</span><span class="na">pruningPattern</span><span class="o">(</span><span class="s">"org[.]apache[.]beam[.].*IT"</span><span class="o">)</span> - <span class="o">.</span><span class="na">pruningPattern</span><span class="o">(</span><span class="s">"java[.]lang.*"</span><span class="o">);</span> - - <span class="nd">@SuppressWarnings</span><span class="o">(</span><span class="s">"unchecked"</span><span class="o">)</span> - <span class="kd">final</span> <span class="n">Set</span><span class="o"><</span><span class="n">Matcher</span><span class="o"><</span><span class="n">Class</span><span class="o"><?>>></span> <span class="n">allowed</span> <span class="o">=</span> - <span class="n">ImmutableSet</span><span class="o">.</span><span class="na">of</span><span class="o">(</span> - <span class="n">classesInPackage</span><span class="o">(</span><span class="s">"org.apache.beam.x"</span><span class="o">),</span> - <span class="n">classesInPackage</span><span class="o">(</span><span class="s">"org.apache.beam.y"</span><span class="o">),</span> - <span class="n">classesInPackage</span><span class="o">(</span><span class="s">"org.apache.beam.z"</span><span class="o">),</span> - <span class="n">Matchers</span><span class="o">.<</span><span class="n">Class</span><span class="o"><?>></span><span class="n">equalTo</span><span class="o">(</span><span class="n">Other</span><span class="o">.</span><span class="na">class</span><span class="o">));</span> - - <span class="n">assertThat</span><span class="o">(</span><span class="n">apiSurface</span><span class="o">,</span> <span class="n">containsOnlyClassesMatching</span><span class="o">(</span><span class="n">allowed</span><span class="o">));</span> -<span class="o">}</span> -</code></pre> -</div> - -<div class="language-py highlighter-rouge"><pre class="highlight"><code><span class="c"># Unsupported in Beam's Python SDK.</span> -</code></pre> -</div> - -<p>This test will fail if the classes exposed by <code class="highlighter-rouge">getClass().getPackage()</code>, except -classes which reside under <code class="highlighter-rouge">"org[.]apache[.]beam[.].*Test.*"</code>,<br /> -<code class="highlighter-rouge">"org[.]apache[.]beam[.].*IT"</code> or <code class="highlighter-rouge">"java[.]lang.*"</code>, belong to neither -of the packages: <code class="highlighter-rouge">org.apache.beam.x</code>, <code class="highlighter-rouge">org.apache.beam.y</code>, <code class="highlighter-rouge">org.apache.beam.z</code>, -nor equal to <code class="highlighter-rouge">Other.class</code>.</p> - -<h2 id="best_practices">Best practices for writing tests</h2> - -<p>The following best practices help you to write reliable and maintainable tests.</p> - -<h3 id="aim-for-one-failure-path">Aim for one failure path</h3> - -<p>An ideal test has one failure path. When you create your tests, minimize the -possible reasons for a test failure. A developer can debug a problem more -easily when there are fewer failure paths.</p> - -<h3 id="avoid-non-deterministic-code">Avoid non-deterministic code</h3> - -<p>Reliable tests are predictable and deterministic. Tests that contain -non-deterministic code are hard to debug and are often flaky. Non-deterministic -code includes the use of randomness, time, and multithreading.</p> - -<p>To avoid non-deterministic code, mock the corresponding methods or classes.</p> - -<h3 id="use-descriptive-test-names">Use descriptive test names</h3> - -<p>Helpful test names contain details about your test, such as test parameters and -the expected result. Ideally, a developer can read the test name and know where -the buggy code is and how to reproduce the bug.</p> - -<p>An easy and effective way to name your methods is to use these three questions:</p> - -<ul> - <li>What you are testing?</li> - <li>What are the parameters of the test?</li> - <li>What is the expected result of the test?</li> -</ul> - -<p>For example, consider a scenario where you want to add a test for the -<code class="highlighter-rouge">Divide</code> method:</p> - -<div class="language-java highlighter-rouge"><pre class="highlight"><code><span class="kt">float</span> <span class="nf">Divide</span><span class="o">(</span><span class="kt">float</span> <span class="n">dividend</span><span class="o">,</span> <span class="kt">float</span> <span class="n">divisor</span><span class="o">)</span> <span class="o">{</span> - <span class="k">return</span> <span class="n">dividend</span> <span class="o">/</span> <span class="n">divisor</span><span class="o">;</span> -<span class="o">}</span> - -<span class="o">...</span> - -<span class="nd">@Test</span> -<span class="kt">void</span> <span class="o"><--</span><span class="n">TestMethodName</span><span class="o">-->()</span> <span class="o">{</span> - <span class="n">assertThrows</span><span class="o">(</span><span class="n">Divide</span><span class="o">(</span><span class="mi">10</span><span class="o">,</span> <span class="mi">0</span><span class="o">))</span> -<span class="o">}</span> -</code></pre> -</div> - -<p>If you use a simple test name, such as <code class="highlighter-rouge">testDivide()</code>, you are missing important -information such as the expected action, parameter information, and expected -test result. As a result, triaging a test failure requires you to look at the -test implementation to see what the test does.</p> - -<p>Instead, use a name such as <code class="highlighter-rouge">invokingDivideWithDivisorEqualToZeroThrowsException()</code>, -which specifies:</p> - -<ul> - <li>the expected action of the test (<code class="highlighter-rouge">invokingDivide</code>)</li> - <li>details about important parameters (the divisor is zero)</li> - <li>the expected result (the test throws an exception)</li> -</ul> - -<p>If this test fails, you can look at the descriptive test name to find the most -probable cause of the failure. In addition, test frameworks and test result -dashboards use the test name when reporting test results. Descriptive names -enable contributors to look at test suite results and easily see what -features are failing.</p> - -<p>Long method names are not a problem for test code. Test names are rarely used -(usually when you triage and debug), and when you do need to look at a -test, it is helpful to have descriptive names.</p> - -<h3 id="use-a-pre-commit-test-if-possible">Use a pre-commit test if possible</h3> - -<p>Post-commit tests validate that Beam works correctly in broad variety of -scenarios. The tests catch errors that are hard to predict in the design and -implementation stages</p> - -<p>However, we often write a test to verify a specific scenario. In this situation, -it is usually possible to implement the test as a unit test or a component test. -You can add your unit tests or component tests to the pre-commit test suite, and -the pre-commit test results give you faster code health feedback during the -development stage, when a bug is cheap to fix.</p> - - </div> - </div> - <!-- - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. See accompanying LICENSE file. ---> - -<footer class="footer"> - <div class="footer__contained"> - <div class="footer__cols"> - <div class="footer__cols__col"> - <div class="footer__cols__col__logo"> - <img src="/images/beam_logo_circle.svg" class="footer__logo" alt="Beam logo"> - </div> - <div class="footer__cols__col__logo"> - <img src="/images/apache_logo_circle.svg" class="footer__logo" alt="Apache logo"> - </div> - </div> - <div class="footer__cols__col footer__cols__col--md"> - <div class="footer__cols__col__title">Start</div> - <div class="footer__cols__col__link"><a href="/get-started/beam-overview/">Overview</a></div> - <div class="footer__cols__col__link"><a href="/get-started/quickstart-java/">Quickstart (Java)</a></div> - <div class="footer__cols__col__link"><a href="/get-started/quickstart-py/">Quickstart (Python)</a></div> - <div class="footer__cols__col__link"><a href="/get-started/quickstart-go/">Quickstart (Go)</a></div> - <div class="footer__cols__col__link"><a href="/get-started/downloads/">Downloads</a></div> - </div> - <div class="footer__cols__col footer__cols__col--md"> - <div class="footer__cols__col__title">Docs</div> - <div class="footer__cols__col__link"><a href="/documentation/programming-guide/">Concepts</a></div> - <div class="footer__cols__col__link"><a href="/documentation/pipelines/design-your-pipeline/">Pipelines</a></div> - <div class="footer__cols__col__link"><a href="/documentation/runners/capability-matrix/">Runners</a></div> - </div> - <div class="footer__cols__col footer__cols__col--md"> - <div class="footer__cols__col__title">Community</div> - <div class="footer__cols__col__link"><a href="/contribute/">Contribute</a></div> - <div class="footer__cols__col__link"><a href="https://projects.apache.org/committee.html?beam" target="_blank">Team<img src="/images/external-link-icon.png" - width="14" height="14" - alt="External link."></a></div> - <div class="footer__cols__col__link"><a href="/contribute/presentation-materials/">Media</a></div> - </div> - <div class="footer__cols__col footer__cols__col--md"> - <div class="footer__cols__col__title">Resources</div> - <div class="footer__cols__col__link"><a href="/blog/">Blog</a></div> - <div class="footer__cols__col__link"><a href="/get-started/support/">Support</a></div> - <div class="footer__cols__col__link"><a href="https://github.com/apache/beam">GitHub</a></div> - </div> - </div> - </div> - <div class="footer__bottom"> - © - <a href="http://www.apache.org">The Apache Software Foundation</a> - | <a href="/privacy_policy">Privacy Policy</a> - | <a href="/feed.xml">RSS Feed</a> - <br><br> - Apache Beam, Apache, Beam, the Beam logo, and the Apache feather logo are - either registered trademarks or trademarks of The Apache Software - Foundation. All other products or name brands are trademarks of their - respective holders, including The Apache Software Foundation. - </div> -</footer> - - </body> +<html lang="en-US"> +<meta charset="utf-8"> +<title>Redirecting…</title> +<link rel="canonical" href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide"> +<meta http-equiv="refresh" content="0; url=https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide"> +<h1>Redirecting…</h1> +<a href="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide">Click here if you are not redirected.</a> +<script>location="https://cwiki.apache.org/confluence/display/BEAM/Contribution+Testing+Guide"</script> </html>