Add note duplicate test execution with @suite

Users are surprised to see that their tests are executed twice[1]. This
is the natural consequence of using a test engine to define a suite.

We can at least let them know in the documentation.

1. #4327

Author: mpkorstanje

documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc

@@ -1,8 +1,8 @@
 [[junit-platform-suite-engine]]
 === JUnit Platform Suite Engine
 
-The JUnit Platform supports the declarative definition and execution of suites of tests
-from _any_ test engine using the JUnit Platform.
+The Suite Engine supports the declarative selection and execution of tests from
+_any_ test engine using the JUnit Platform.
 
 [[junit-platform-suite-engine-setup]]
 ==== Setup
@@ -48,6 +48,13 @@ NOTE: There are numerous configuration options for discovering and filtering tes
 test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full
 list of supported annotations and further details.
 
+.Duplicate test execution
+NOTE: Tests in a suite are executed in addition to the tests executed by every other test
+engine, so it is possible to for the same test to be executed twice. A common solution is
+to use a naming pattern. Name all suites `*Suite` and all tests `*Test` and configure your
+build tool to only include the former. Alternatively, consider
+<<running-tests-tags, using tags>> to select specific groups of tests.
+
 ==== @BeforeSuite and @AfterSuite
 
 `@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a

junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/Suite.java

@@ -26,7 +26,7 @@
  * {@code @Suite} marks a class as a test suite on the JUnit Platform.
  *
  * <p>Selector and filter annotations are used to control the contents of the
- * suite. Additionally configuration can be passed to the suite via the
+ * suite. Additionally, configuration can be passed to the suite via the
  * configuration annotations.
  *
  * <p>When the {@link IncludeClassNamePatterns @IncludeClassNamePatterns}
@@ -44,6 +44,12 @@
  * annotation disables the latter as a source of parameters so that only explicit
  * configuration parameters are taken into account.
  *
+ * <p>Note: Tests in a suite are executed in addition to the tests executed by every
+ * other test engine, so it is possible to for the same test to be executed twice. A
+ * common solution is to use a naming pattern. Name all suites {@code *Suite} and all
+ * tests {@code *Test} and configure your build tool to only include the former.
+ * Alternatively, consider using tags to select specific groups of tests.
+ *
  * @since 1.8
  * @see Select
  * @see SelectClasses