Merge branch 'stable-3.0' into stable-3.1 * stable-3.0: e2e-tests: Clarify replication_delay usage in documentation e2e-tests: Clarify the documented purpose of uppercase keys in json file NoteDbMigrator: Improve log message when saving ref updates e2e-tests: Move plugin list documentation to own section for readability e2e-tests: Formalize power_factor documentation section for readability NoteDbMigrator: fix formatting Change-Id: Ie33db10f7e2a9ab6b17329d609b4d3b323627a81
diff --git a/Documentation/dev-e2e-tests.txt b/Documentation/dev-e2e-tests.txt index ae109ba..3826da4 100644 --- a/Documentation/dev-e2e-tests.txt +++ b/Documentation/dev-e2e-tests.txt
@@ -124,7 +124,8 @@ file contains the commands and repository used during the e2e test. That file currently looks like below. This scenario serves as a simple example with no actual load in it. It can be used to test or validate the local setup. More complex scenarios can be further developed, under the -`com.google.gerrit.scenarios` package. The uppercase keywords are discussed further below. +`com.google.gerrit.scenarios` package. The uppercase keywords are set through +link:#_environment_properties[environment properties]. ---- [ @@ -171,14 +172,40 @@ * `-Dcom.google.gerrit.scenarios.ssh_port=29418` * `-Dcom.google.gerrit.scenarios.http_port=8080` * `-Dcom.google.gerrit.scenarios.http_scheme=http` -* `-Dcom.google.gerrit.scenarios.replication_delay=15` Above, the properties can be set with values matching specific deployment topologies under test. -The example values shown above are the currently coded default ones. For example, the `http` scheme -above could be replaced with `https`. The `replication_delay` property matches replication plugin's -configuration with the same name. The framework may support differing or more properties over time. +The name of the property corresponds to the uppercase keyword found in the json file. For example, +`hostname` above will set the value of `HOSTNAME` in the link:#_input_file[aforementioned example]. -Plugin or otherwise non-core scenarios may do so just as well. The core java package +The example values shown above are the currently coded default ones. For example, the `http` scheme +above could be replaced with `https`. The framework may support differing or more properties over time. + +==== Replication delay + +The `replication_delay` property allows test scenario steps to wait for that many seconds, prior to +expecting a done replication. Its default is `15` seconds and can be set using another value: + +* `-Dcom.google.gerrit.scenarios.replication_delay=15` + +There is a short time buffer added to this property. Now, the replication starts after replication +plugin's own `replicationDelay`, in seconds, and typically takes some more seconds to complete. +That whole replication time depends on the system under test. Therefore, this property here should +be set to a value high enough, so that the test checks for a done replication at the right time. + +==== Automatic properties + +The link:#_input_file[example keywords] also include `_PROJECT`, prefixed with an underscore, which +means that its value gets automatically generated by the scenario. Any property setting for it is +therefore not applicable. Its usage differs from the non-prefixed `PROJECT` keyword, in that sense. +Using the latter instead in json files requires setting this `JAVA_OPTS` property: + +* `-Dcom.google.gerrit.scenarios.project=myOwnTestRepoProjectName` + +Other automatic keys may be used and implemented, always prefixed with an underscore that tells so. + +==== Plugin scenarios + +Plugin or otherwise non-core scenarios can also use such properties. The core java package `com.google.gerrit.scenarios` from the example above has to be replaced with the one under which those scenario classes are. Such extending scenarios can also add extension-specific properties. Examples of this can be found in these Gerrit plugins test code: @@ -188,9 +215,7 @@ * `link:https://gerrit.googlesource.com/plugins/multi-site[multi-site]` * `link:https://gerrit.googlesource.com/plugins/rename-project[rename-project]` -Further above, the `_PROJECT` keyword is prefixed with an underscore, which means that its value -gets automatically generated by the scenario. Any property setting for it is therefore not -applicable. Its usage differs from the non-prefixed `PROJECT` keyword, in that sense. +==== Power factor The following core property can be optionally set depending on the runtime environment. The test environments used as reference for scenarios development assume its default value, `1.0`. For