Documentation/dev-e2e-tests.txt

= Gerrit Code Review - End to end load tests

This document provides a description of a Gerrit load test scenario implemented using the
link:https://gatling.io/[Gatling] framework.

Similar scenarios have been successfully used to compare performance of different Gerrit versions
or study the Gerrit response under different load profiles.

== What is Gatling?

Gatling is a load testing tool which provides out of the box support for the HTTP protocol.
Documentation on how to write an HTTP load test can be found
link:https://gatling.io/docs/current/http/http_protocol/[here].

However, in the scenario we are proposing, we are leveraging the
link:https://github.com/GerritForge/gatling-git[Gatling Git extension] to run tests at Git
protocol level.

Gatling is written in Scala, but the abstraction provided by the Gatling DSL makes the scenarios
implementation easy even without any Scala knowledge. The
link:https://gitenterprise.me/2019/12/20/stress-your-gerrit-with-gatling/[Stress your Gerrit with Gatling]
blog post has more introductory information.

Examples of scenarios can be found in the `e2e-tests` directory. The files in that directory
should be formatted using the mainstream
link:https://plugins.jetbrains.com/plugin/1347-scala[Scala plugin for IntelliJ]. The latter is not
mandatory but preferred for `sbt` and Scala IDE purposes in this project.

== How to build the tests

An link:https://www.scala-sbt.org/download.html[sbt-based installation] of
link:https://www.scala-lang.org/download/[Scala] is required.

The `scalaVersion` used by `sbt` once installed is defined in the `build.sbt` file. That specific
version of Scala is automatically used by `sbt` while building:

----
sbt compile
----

The following warning, if present when executing `sbt` commands, can be removed by creating the
link:https://www.scala-sbt.org/1.x/docs/Using-Sonatype.html#step+3%3A+Credentials[related credentials file]
locally. Dummy values for `user` and `password` in that file can be used initially.

----
[warn] Credentials file ~/.sbt/sonatype_credentials does not exist
----

Every `sbt` command can include an optional log level
link:https://www.scala-sbt.org/1.x/docs/Howto-Logging.html#Change+the+logging+level+globally[argument].
Below, `[info]` logs are no longer shown:

----
sbt --warn compile
----

=== How to build using Docker

----
docker build . -t e2e-tests
----

== How to set-up

=== SSH keys

If you are running SSH commands, the private keys of the users used for testing need to go in
`/tmp/ssh-keys`. The keys need to be generated this way (JSch won't validate them
link:https://stackoverflow.com/questions/53134212/invalid-privatekey-when-using-jsch[otherwise]):

----
mkdir /tmp/ssh-keys
ssh-keygen -m PEM -t rsa -C "test@mail.com" -f /tmp/ssh-keys/id_rsa
----

The public key in `/tmp/ssh-keys/id_rsa.pub` has to be added to the test user(s) `SSH Keys` in
Gerrit. Now, the host from which the latter runs may need public key scanning to become known.
This applies to the local user that runs the forthcoming `sbt` testing commands. An example
assuming `localhost` follows:

----
ssh-keyscan -t rsa -p 29418 localhost > ~/.ssh/known_hosts
----

=== Input file

The `CloneUsingBothProtocols` scenario is fed with the data coming from the
`src/test/resources/data/CloneUsingBothProtocols.json` file. Such a file contains the commands and
repository used during the load 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.

----
[
  {
    "url": "ssh://admin@localhost:29418/loadtest-repo",
    "cmd": "clone"
  },
  {
    "url": "http://localhost:8080/loadtest-repo",
    "cmd": "clone"
  }
]
----

Valid commands are:

* `fetch`
* `pull`
* `push`
* `clone`

The example above assumes that the `loadtest-repo` project exists in the Gerrit under test.

== How to run tests

Run all tests:
----
sbt "gatling:test"
----

Run a single test:
----
sbt "gatling:testOnly com.google.gerrit.scenarios.CloneUsingBothProtocols"
----

Generate the last report:
----
sbt "gatling:lastReport"
----

The `src/test/resources/logback.xml` file
link:http://logback.qos.ch/manual/configuration.html[configures] Gatling's logging level.

=== How to run using Docker

----
docker run -it e2e-tests -s com.google.gerrit.scenarios.CloneUsingBothProtocols
----

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------

[scala]: