Skip to main content
Version: 26.1

Back-end Java contribution guide

Landing page

Official documentation

Contribution notes on GitHub

Deployment components description​

There are two Java repositories that are part of the whole RP deployment:

  • Service API - REST API service as ReportPortal functionality provider. It also handles user authentication and authorization (previously a separate Service Authorization).
  • Service Jobs - Service with jobs to process data in the back-ground

Code conventions​

IDE Formatter​

Settings file

Steps to import:

  • Click on IDEA "Preferences"
  • Choose "Editor" section
  • Click on "Code style"
  • In "Scheme" section click on settings wheel → Import Scheme → IntelliJ IDEA code style XML

Code style​

This document is aimed at improving aspects of our existing code base and synchronizing implementation/design approaches within the team. It serves as a blueprint for now but will be continually updated and improved.

  • Code should be as simple and readable as possible.
  • Avoid unnecessary interfaces. In our case, if we aren't planning to extend functionality and can easily refactor, we should avoid creating an interface unless there is a distinct need (e.g., for testing, code auto-generation, etc.).
  • Methods and classes should be named according to their responsibilities. If a name isn't self-explanatory, provide a description.
  • Overloaded or overridden methods with the same name should perform similar operations.
  • Keep parameter order consistent across methods with the same name.
  • Parameter names should be clear and indicative of their function. For example, instead of using a generic "id", specify the entity it's related to, like "userId" or "projectId."
  • The same principle applies to return parameters.
  • It's advisable to use a suitable structure to avoid unnecessary conversions.
  • Commonly used flows (checks, structure processing, etc.) should be moved to utilities.
  • Manually working with threads should be avoided unless necessary (utilize defined TaskExecutor or create a new one).
  • Optional and Stream should be used primarily when they enhance readability. Always return Optional instead of null.
  • Avoid using two terminal operations in a Stream.

Git branch requirements​

  • Working branch names should start with the Jira-id (EPMRPP-DDD) and an optional description, e.g., PMRPP-444 or EPMRPP-443-fix-some-bugs. All Jira branches must be related to a Jira ticket.
  • All commit messages in master, develop, and release branches must start with a Jira-id as well: EPMRPP-445 Some important fix.
  • It is better to divide commits into small, logically complete parts within the branch, for clarity during code review.
  • When merging a PR into the main branch (master, develop, release), all commits should be squashed and provided with a suitable description with the Jira-id by the person who performs the merge.

For contributors who do not have access to our Jira tasks, the branch name prefix should be the GitHub issue name. It is highly recommended to create an issue that doesn't already exist and then fix it within your PR, even if it's a new function. The issue will remain there, a record of your ideas and comments from other contributors. Additionally, ReportPortal users who are not developers might prefer to look through issues rather than PRs to verify if a specific issue has been addressed in a new version of ReportPortal. This is a crucial component in maintaining a transparent, efficient test automation reporting dashboard for all users.

Open-source contribution workflow​

All features fixes should be added to develop branch only, exclusions: hot-fixes

Changes applying workflow:

  • Clone repository or fork from it
  • Checkout develop branch
  • Create branch according to name policy
  • Push branch to the remote
  • Create PR according to name policy into the develop branch of the RP repository
  • Review and merge/reject PR (squash commits in one during merge)

Dev environment setup​

Pre requirements​

  • Postgresql should be deployed
  • Service Migration should fill/update DB data
  • Binary data storage should be configured

To deploy DB with the latest schema we need the docker-compose.yml that looks like this:

version: '2.4'
services:

postgres:
image: postgres:18.6
shm_size: '512m'
environment:
POSTGRES_USER: rpuser
POSTGRES_PASSWORD: rppass
POSTGRES_DB: reportportal
volumes:
# For unix host
- ./data/postgres:/var/lib/postgresql
# For windows host
# - postgres:/var/lib/postgresql
ports:
- "5432:5432"
command:
-c checkpoint_completion_target=0.9
-c work_mem=96MB
-c wal_writer_delay=20ms
-c synchronous_commit=off
-c wal_buffers=32MB
-c min_wal_size=2GB
-c max_wal_size=4GB
healthcheck:
test: ["CMD-SHELL", "pg_isready -d $$POSTGRES_DB -U $$POSTGRES_USER"]
interval: 10s
timeout: 120s
retries: 10
restart: always

db-scripts:
image: reportportal/migrations:5.15.6
depends_on:
postgres:
condition: service_healthy
environment:
POSTGRES_SERVER: postgres
POSTGRES_PORT: 5432
POSTGRES_DB: reportportal
POSTGRES_USER: rpuser
POSTGRES_PASSWORD: rppass
restart: on-failure

How to keep DB data up-to-date​

Maintaining an up-to-date database (DB) schema is an important aspect of efficient test automation reporting tools management.

image: reportportal/migrations:6.0.0 is the released version of the migrations service. However, if any changes were made in the develop branch after the release, the migrated DB schema may be outdated. To prevent this and ensure your DB data remains current, follow the steps outlined below:

docker-compose run --rm migrations

This process leverages all SQL scripts present in the develop branch to update your locally running DB instance.

By default, filesystem storage is employed for binary data; meaning all data will be stored on your local filesystem. If you prefer to store binaries using Minio (as we do in our production), you need to deploy it as well. You can do this by adding the necessary pieces to the existing docker-compose.yml:

  minio:
image: minio/minio:RELEASE.2020-10-27T04-03-55Z
ports:
- '9000:9000'
volumes:
# For unix host
- ./data/storage:/data
# For windows host
# - minio:/data
environment:
MINIO_ACCESS_KEY: minio
MINIO_SECRET_KEY: minio123
command: server /data
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 30s
timeout: 20s
retries: 3
restart: always

Please be aware of the comments directed towards Windows - if you are developing on Windows, uncomment the sections for Windows and comment out any Linux-related sections, applicable to both Postgres and Minio. Then, add the following statement to the docker-compose.yml:

volumes:
postgres:
minio:

As the result we have the docker-compose.yml:

version: '2.4'
services:

postgres:
image: postgres:18.6
shm_size: '512m'
environment:
POSTGRES_USER: rpuser
POSTGRES_PASSWORD: rppass
POSTGRES_DB: reportportal
volumes:
# For unix host
- ./data/postgres:/var/lib/postgresql
# For windows host
# - postgres:/var/lib/postgresql
ports:
- "5432:5432"
command:
-c checkpoint_completion_target=0.9
-c work_mem=96MB
-c wal_writer_delay=20ms
-c synchronous_commit=off
-c wal_buffers=32MB
-c min_wal_size=2GB
-c max_wal_size=4GB
healthcheck:
test: ["CMD-SHELL", "pg_isready -d $$POSTGRES_DB -U $$POSTGRES_USER"]
interval: 10s
timeout: 120s
retries: 10
restart: always

db-scripts:
image: reportportal/migrations:6.0.0
depends_on:
postgres:
condition: service_healthy
environment:
POSTGRES_SERVER: postgres
POSTGRES_PORT: 5432
POSTGRES_DB: reportportal
POSTGRES_USER: rpuser
POSTGRES_PASSWORD: rppass
restart: on-failure

minio:
image: minio/minio:RELEASE.2020-10-27T04-03-55Z
ports:
- '9000:9000'
volumes:
# For unix host
- ./data/storage:/data
# For windows host
# - minio:/data
environment:
MINIO_ACCESS_KEY: minio
MINIO_SECRET_KEY: minio123
command: server /data
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 30s
timeout: 20s
retries: 3
restart: always

volumes:
postgres:
minio:

Service API​

Prior to initiating the Service API, RabbitMQ needs to be included in our deployment.

In ReportPortal, RabbitMQ serves three key functions:

  • Inter-service communication between Service API and Service Analyzer.
  • Asynchronous reporting feature.
  • User activity event publishing.

To add RabbitMQ to our deployment, the following should be incorporated into our existing docker-compose.yml:

  rabbitmq:
image: rabbitmq:4.4.0-management
ports:
- "5672:5672"
- "15672:15672"
environment:
RABBITMQ_DEFAULT_USER: "rabbitmq"
RABBITMQ_DEFAULT_PASS: "rabbitmq"
configs:
- source: rabbitmq_extra_config
target: /etc/rabbitmq/conf.d/99-extra.conf
- source: rabbitmq_enabled_plugins
target: /etc/rabbitmq/enabled_plugins
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
interval: 30s
timeout: 30s
retries: 5
start_period: 60s
restart: always

We can now begin deploying the Service API without encountering any issues. However, it's important to note that all Analyzer-related interactions (such as publishing to analyzer queues and receiving responses) will not be successful. To rectify this, we need to deploy the Service Analyzer and all its required services. To achieve this, we add the following to our docker-compose.yml:

  opensearch:
image: opensearchproject/opensearch:3.9.0
container_name: opensearch
environment:
discovery.type: single-node
plugins.security.disabled: "true"
bootstrap.memory_lock: "true"
OPENSEARCH_JAVA_OPTS: -Xms512m -Xmx512m
DISABLE_INSTALL_DEMO_CONFIG: "true"
ulimits:
memlock:
soft: -1
hard: -1
ports:
- "9200:9200"
- "9600:9600"
volumes:
- opensearch:/usr/share/opensearch/data
healthcheck:
test: ["CMD", "curl","-s" ,"-f", "http://0.0.0.0:9200/_cat/health"]
restart: always

analyzer:
image: reportportal/service-auto-analyzer:6.0.0
environment:
LOGGING_LEVEL: info
AMQP_EXCHANGE_NAME: analyzer-default
AMQP_URL: amqp://rabbitmq:rabbitmq@rabbitmq:5672
ES_HOSTS: http://opensearch:9200
# ES_USER:
# ES_PASSWORD:
# MINIO_SHORT_HOST: minio:9000
# MINIO_ACCESS_KEY: minio
# MINIO_SECRET_KEY: minio123
depends_on:
opensearch:
condition: service_started
rabbitmq:
condition: service_healthy
restart: always

As a result of these additions, your docker-compose.yml should look something like this.

To start the Service API, populate the marked values in your application.yaml file:

Service API serves both the REST API and the authorization endpoints on port 8585. Since Service Authorization was merged into Service API, the authorization endpoints are available under /api (for example, /api/sso/oauth/token) instead of /uat.

Service Jobs​

To start Service Jobs, fill in the marked values in your application.yaml file:

Service UI​

After all back-end services deployed you may want to interact with them not only using tool like Postman but use ReportPortal UI too. Once all back-end services are deployed, you may want to interface with them beyond using a tool like Postman and use ReportPortal UI. To accomplish this, follow these steps:

  • Clone or update the Service UI repository.
  • Checkout the develop branch.
  • Make changes to the dev.config.js file.

Before:

proxy: [
{
context: ['/api/', '/ui/info', '/info'],
target: process.env.PROXY_PATH,
changeOrigin: true,
bypass(req) {
// eslint-disable-next-line no-console
console.log(`proxy url: ${req.url}`);
},
},
]

After:

proxy: [
{
context: ['/api/'],
target: 'http://localhost:8585',
pathRewrite: { '^/api': '' },
changeOrigin: true,
},
]

All /api/ requests, including the authorization endpoints (/api/sso/...) that were previously served under /uat/, are sent to the locally running Service API. The /api prefix is stripped the same way the Traefik gateway does in the Docker deployment.

  • If NodeJs is not already installed, install it (version 20 is recommended).
  • From the root folder(service-ui), run Service UI using the following commands:
cd app
npm install
npm run dev
  • Open the Service UI page on localhost using port 3000 and try to login using the default credentials.

This will allow you to view your test automation dashboard and interact with the reported test results.

Development workflow​

Introduction to dependencies​

In addition to common dependencies such as spring-..., earlier versions of the Java services relied on ReportPortal libraries distributed across separate repositories (Commons DAO, Commons Model, Commons, Commons Rules, Plugin API, and Commons BOM). These libraries are now merged into the Service API codebase and are no longer consumed as remote dependencies, so the separate repositories are not used for development anymore.

As a result, changes to the data layer, REST models, common utilities, business rules validation, or the plugin API are made directly in the Service API repository, in the same branch and pull request as the rest of your change. There is no need to publish a dependency and update its version or commit hash in build.gradle.

Summary notes​

This documentation should assist you in configuring the ReportPortal local development environment and provide an understanding of the standards and conventions we adhere to.

The simplified development workflow should look as follows:

  • Always maintain the latest schema and data in your local DB instance.
  • Checkout the develop branch in the required repository.
  • Implement changes.
  • Create a branch according to the name policy.
  • Push to the remote.
  • Create a PR following the name policy.