github.com/redhat-appstudio/e2e-tests@v0.0.0-20240520140907-9709f6f59323/docs/Installation.md

# RHTAP Installation locally and Openshift CI

The following guide will walk through the necessary instruction about driving an installation of RHTAP locally or in Openshift CI.

## RHTAP in dev mode


### Requirements

Requirements for installing RHTAP in E2E mode:

* An OpenShift 4.12 or higher Environment (If you are using CRC/OpenShift Local please also review [optional-codeready-containers-post-bootstrap-configuration](https://github.com/redhat-appstudio/infra-deployments/blob/main/docs/development/deployment.md#optional-openshift-local-post-bootstrap-configuration))
* A machine from which to run the install (usually your laptop) with required tools:
  * A properly setup Go workspace using **Go 1.19 is required**
  * The OpenShift Command Line Tool (oc) **Use the version corresponding to the Openshift version**
  * [yq]((https://github.com/mikefarah/yq))
  * jq
  * git
* Tokens
  * Github Token with the following permissions
    * `repo`
    * `delete_repo`
    * `workflow`
  * Valid quay token where to push RHTAP components images generated by the e2e framework

### Installation

1. Before deploying RHTAP in E2E mode you need to login to your OpenShift cluster with OpenShift Command Line Tool as `admin` (by default  `kubeadmin`):

   ```bash
    oc login -u <user> -p <password> --server=<oc_api_url>
   ```

2. Export required (and recommended) environment variables from [default.env](../default.env). Copy the file (`cp default.env user.env`), edit the required variables and source it (`source user.env`).

3. Install dependencies:

``` bash
# Install dependencies
$ go mod tidy
# or go mod tidy -compat=1.21
```

4. By default the installation script will use the `redhat-appstudio-qe` GitHub organization for pushing changes to `infra-deployments` repository.

**It is recommended to use your fork of [infra-deployments repo](https://github.com/redhat-appstudio/infra-deployments) in your GitHub org instead** - you can change the GitHub organization with environment variable `export MY_GITHUB_ORG=<name-of-your-github-org>`.

<details>
<summary><h4>Advanced installation guidelines</h4></summary>
<h5>GitHub Application for Pipelines as Code<h5>
<p>

   Some tests could require you have a Github App created in order to test Component builds via Pipelines as Code.
Such tests are [rhtap-demo](https://github.com/redhat-appstudio/e2e-tests/blob/main/tests/rhtap-demo/rhtap-demo.go), [build](https://github.com/redhat-appstudio/e2e-tests/blob/main/tests/build/build.go), and [status-reporting-to-pullrequest](https://github.com/redhat-appstudio/e2e-tests/blob/main/tests/integration-service/status-reporting-to-pullrequest.go).

In this case, before you bootstrap a cluster, make sure you [created a Github App for your GitHub account](https://github.com/settings/apps). Fill in following details:
</p>
<ul><li> <b>GitHub App name</b>: unique app name</li> </ul>
<ul><li> <b>Homepage URL</b>: some dummy URL (like https://example.com)</li></ul>
<ul> <li> <b>Webhook</b>: mark as active and put some dummy URL to the <b>Webhook URL</b> field</li></ul>
<ul> <li> <b>Permissions</b> and <b>Subscribe to events</b>: refer to <a href="https://pipelinesascode.com/docs/install/github_apps/#setup-manually">the guide in PaC documentation</a></li></ul>
<ul> <li> <b>Where can this GitHub App be installed></b>: Any account</li> </ul>

<p></p>

Hit create, make a note of the <b>App ID</b> and navigate to the <b>Private keys</b> section where you generate a private key that gets downloaded automatically. Then export following environment variables (or if you're using .env file, update values of following variables):

```bash
export E2E_PAC_GITHUB_APP_ID='<YOUR_APP_ID>'

export E2E_PAC_GITHUB_APP_PRIVATE_KEY=$(base64 < /PATH/TO/YOUR/DOWNLOADED/PRIVATE_KEY.pem)
```

<p>
Navigate back to <a href="https://github.com/settings/apps">your GitHub App</a>, select Install App and select your GitHub org (the one that you're using in `MY_GITHUB_ORG` env var). Feel free to install it to all repositories of that organization or the forked repositories currently used by <a href="(https://github.com/redhat-appstudio/e2e-tests/blob/main/tests/rhtap-demo/rhtap-demo.go)">rhtap-demo</a> and <a href="(https://github.com/redhat-appstudio/e2e-tests/blob/main/tests/build/build.go">build tests</a>
</p>

</details>

For bootstrapping a cluster, run the following command:

   ```bash
      make local/cluster/prepare
   ```

More information about how to deploy RHTAP
are in the [infra-deployments](https://github.com/redhat-appstudio/infra-deployments) repository.

### Building and running the e2e tests

Most of the tests could require you to have specific container image repo's created (if you're using your own container image org/user account (`QUAY_E2E_ORGANIZATION`) or your own GitHub organization (`MY_GITHUB_ORG`).
In that case, before you run the test, make sure you have created
* `test-images` repo in quay.io, i.e. `quay.io/<QUAY_E2E_ORGANIZATION>/test-images` and make it **public** (this repo will be used for pushing container images produced by tests)
  * also make sure that the docker config, that is encoded in the value of `QUAY_TOKEN` environment variable, contains a correct credentials required to push to `test-images` repo. And make sure the robot account or user account has the **write** permissions set for `test-images` repo which is required by the tests to push the generated artifacts.
* fork following GitHub repositories to your org (specified in `MY_GITHUB_ORG` env var)
  * https://github.com/redhat-appstudio-qe/devfile-sample-hello-world (for running build-service tests)
  * https://github.com/redhat-appstudio-qe/hacbs-test-project (for rhtap-demo test)
  * https://github.com/redhat-appstudio-qe/strategy-configs (for rhtap-demo test)
  * https://github.com/redhat-appstudio-qe/hacbs-test-project-integration (for status-reporting-to-pullrequest test)

Note: All Environments used in all e2e-tests are in [default.env](../default.env) file. In case you need to run a specific tests, not all environments are necessary to be defined.

You can use the following make target to build and run the tests:
   ```bash
      make local/test/e2e
   ```

Or build and run the tests without scripts:
1. Install dependencies and build the tests:

   ``` bash
   # Install dependencies
   $ go mod tidy
   # Create `e2e-appstudio` binary in bin folder. Please add the binary to the path or just execute `./bin/e2e-appstudio`
   $ make build
   ```

2. Run the e2e tests:
The `e2e-appstudio` command is the root command that executes all test functionality. To obtain all available flags for the binary please use `--help` flags. All ginkgo flags and go tests are available in `e2e-appstudio` binary.


   ```bash
      `./bin/e2e-appstudio`
   ```
Note: The binary must be updated by running `make build` every time there are new changes in the tests.

The instructions for every test suite can be found in the [tests folder](tests), e.g. [has Readme.md](tests/rhtap-demo/README.md).
You can also specify which tests you want to run using [labels](docs/LabelsNaming.md) or [Ginkgo Focus](docs/DeveloperFocus.md).


## RHTAP in Openshift CI and branch pairing

The e2e tests are executed against almost all AppStudio repositories.

Sometimes when we have changes in AppStudio we are introducing some breaking changes and the e2e will fail. To prevent this the e2e framework installation in openshift-ci support a new feature of pairing the PR opened against an AppStudio repository with a corresponding PR opened against e2e-tests (based on branch names). Before the e2e framework will be executed in openshift-ci, the logic automatically tries to pair a PR opened in some repo with a branch of the same name that
potentially could exists in the developer's fork of the e2e repository

For example, if a developer with GH account `cooljohn` opens a PR (for application-service repo) from a branch `new-feature`, then the logic checks if there is a PR open in e2e-tests from the `new-feature` branch in the `cooljohn/e2e-tests` fork. If such a PR is found, the CI will install the e2e framework from that branch.

Once the service PR passes CI with its pairing and is merged, the next step is to get the references in infra-deployments updated.
Many services have automation to create PRs in infra-deployments to update their component to the latest version.
However, this recently merged latest version will likely need the still unmerged e2e-tests update.
The solution is to manually create a PR to infra-deployments that bumps the component version with the *same* branch name.
This will allow the infra-deployments CI to run with your branch of e2e-tests, allowing the CI to pass.
Finally, once the infra-deployments CI passes and PR merges, you should be able to rerun your e2e-tests PR and have it pass and merge.

To continue on the previous example, once the application-service PR merges, `cooljohn` should open a pull request to infra-deployments using the branch `new-feature`
to bump the application-service version to the one recently created by the application-service PR merging. This lets the infra-deployments CI run with the required
e2e-tests changes from `cooljohn`'s fork.

Pairing PRs is handled automatically by running this command from a root directory of this repository:

```bash
   make ci/test/e2e
```