Running tests

Running tests

Introduction

JHipster comes with an extensive set of tests, and each generated application has:

• Unit tests using JUnit 5{:target="_blank" rel="noopener"}.
• Integration tests using the Spring Test Context framework.
• UI tests with Jest{:target="_blank" rel="noopener"}.
• Architecture tests with ArchUnit{:target="_blank" rel="noopener"}.

Optionally, JHipster can also generate:

• Performance tests with Gatling{:target="_blank" rel="noopener"}.
• Behaviour-driven tests with Cucumber{:target="_blank" rel="noopener"}.
• Angular/React/Vue integration tests with Cypress{:target="_blank" rel="noopener"} or Protractor{:target="_blank" rel="noopener"}.

We have two goals in generating those tests:

• Help every JHipster user to follow best practices, as we believe tests are a very useful part of every application
• Validate that what is being generated is correct. So even if you don't plan to use those tests at all, doing ./mvnw clean verify and npm test after generating your application is a good way of knowing if everything is fine. You are then free to ignore those tests if you think that testing is a waste of time!

All those tests will be generated in the standard Maven src/test folder.

Integration tests

Integration tests are done with the Spring Test Context framework, and are located in the src/test/java folder. JHipster will launch a specific Spring test context, which will be re-used along all tests, as:

• Your Spring beans should be stateless and thread-safe, and thus can be re-used across your different tests suites.
• Launching only one Spring context for all tests is a lot faster than launching a new Spring context for each test.

This Spring test context will use a specific test database to run its tests:

• If you use an SQL database, JHipster will launch an in-memory H2 instance in order to use a temporary database for its integration tests. Alternatively, by using the testcontainers profile, JHipster will launch a containerized version of the production database using Testcontainers{:target="_blank" rel="noopener"}. Either way, Liquibase will be run automatically, and will generate the database schema.
• If you use Cassandra, JHipster will launch a containerized version of Cassandra with Docker using Testcontainers{:target="_blank" rel="noopener"}.
• If you use MongoDB, JHipster will launch an in-memory MongoDB instance using de.flapdoodle.embed.mongo{:target="_blank" rel="noopener"}.
• If you use Elasticsearch, JHipster will launch an in-memory Elasticsearch instance using Spring Data Elasticsearch.
• If you use Couchbase, JHipster will launch a containerized version of Couchbase with Docker using Couchbase Testcontainers{:target="_blank" rel="noopener"}.
• If you use Neo4j, JHipster will launch a containerized version of Neo4j with Docker using Neo4j Testcontainers{:target="_blank" rel="noopener"}.

Those tests can be run directly in your IDE, by right-clicking on each test class, or by running ./mvnw clean verify (or ./gradlew test integrationTest if you use Gradle).

Limitations: if the generated entities have validation enabled, JHipster is not enable to generate the correct values depending on the validation rules. Those rules can be so complex, for example if a Regex pattern is used, that this not possible. In this case, the tests will fail validation, and the default values used in the test will need to changed manually, so they can pass the validation rules.

UI tests

UI tests come in two flavors with JHipster: unit tests with Jest, and integration tests with Protractor. Only Jest is provided by default, but if you want to have a good test coverage of your application, we recommend that you use both tools together.

Jest

UI unit tests are located in the src/test/javascript/spec folder. They use Jest{:target="_blank" rel="noopener"}.

Those tests will mock up the access to the application's REST endpoints, so you can test your UI layer without having to launch the Java back-end.

• Those tests can be run using npm test.
• Tip: if you want to focus on a single test change the module description from describe('...', function() { to fdescribe('...', function() { and Jest will run this test only.

Cypress/Protractor

UI integration tests are done with Cypress{:target="_blank" rel="noopener"} or Protractor{:target="_blank" rel="noopener"}, and are located in the src/test/javascript/e2e folder.

Those tests will launch a Web browser and use the application like a real user would do, so you need to have a real application running, with its database set-up.

Those tests can be run using npm run e2e.

Architecture tests

Architecture tests, which enforce certain constrainsts and best practices are done with ArchUnit{:target="_blank" rel="noopener"}. You can write your own rules to check custom constraints for your architecture at build time following the official documentation{:target="_blank" rel="noopener"}.

Performance tests

Performance tests are done with Gatling{:target="_blank" rel="noopener"}, and are located in the src/test/gatling folder. They are generated for each entity, and allows to test each of them with a lot of concurrent user requests.

To run Gatling tests, you must

1. Download Gatling{:target="_blank" rel="noopener"}
2. Extract it and add the location to your PATH
3. cd into src/test/gatling and run gatling.sh or gatling.bat depending on your OS

Warning! At the moment, those tests do not take into account the validation rules you may have enforced on your entities. Also tests for creating entities that have a required relationship with another entity will fail out of the box. You will anyway need to change those tests, according to your business rules, so here are few tips to improve your tests:

• On your running application, go to the Administration > Logs screen, and put org.springframework in debug mode. You will see the validation errors, for example.
• Use the application normally and open the Chrome console log: you will be able to see the REST requests with all their parameters, including the HTTP headers.

For running Gatling tests on a microservice application, you have to:

• Run a registry
• Run a gateway
• Run the microservice application
• Then, you can run Gatling tests

Using Maven/Gradle to run Gatling

We do not generate Maven or Gradle configuration to run Gatling tests as this might cause some classpath issues with other plugins (mainly because of the use of Scala). Nevertheless you can leverage the offical Maven plugin{:target="_blank" rel="noopener"} or Gradle plugin{:target="_blank" rel="noopener"} to execute the Gatling tests.

Using Maven

You need to change pom.xml:

1. Add Gatling dependency with test scope
2. Add Gatling plugin
3. Adapt plugin configuration to JHipster layout and naming conventions

...
<dependency>
  <groupId>io.gatling.highcharts</groupId>
  <artifactId>gatling-charts-highcharts</artifactId>
  <version>3.5.0</version>
  <scope>test</scope>
</dependency>
<!-- jhipster-needle-maven-add-dependency -->
...
<plugin>
  <groupId>io.gatling</groupId>
  <artifactId>gatling-maven-plugin</artifactId>
  <version>3.1.1</version>
  <configuration>
    <runMultipleSimulations>true</runMultipleSimulations>
    <resourcesFolder>${project.basedir}/src/test/gatling/conf</resourcesFolder>
    <simulationsFolder>${project.basedir}/src/test/gatling/user-files/simulations</simulationsFolder>
  </configuration>
</plugin>
<!-- jhipster-needle-maven-add-plugin -->
...

You can execute all Gatling tests with ./mvnw gatling:test.

Using Gradle

You need to change build.gradle:

1. Add the Gatling plugin to the plugin section
2. Adapt source sets to the JHipster layout
3. Adapt the included simulations to the JHipster naming conventions

In case you are using the reactive option you might need to make sure the Spring Boot-managed Netty version does not interfere with the one needed by Gatling{:target="_blank" rel="noopener"}.

plugins {
    ...
    id "io.spring.nohttp"
    // Add the Gatling plugin, please check for the latest version here https://plugins.gradle.org/plugin/io.gatling.gradle 
    id 'io.gatling.gradle' version "3.5.0" 
    //jhipster-needle-gradle-plugins - JHipster will add additional gradle plugins here
}

...
// adapt the source sets to the JHipster specific layout
sourceSets {
   gatling {
    scala.srcDirs = ["src/test/gatling/user-files/simulations"]
    resources.srcDirs = ["src/test/gatling/conf"]
  }
} 

gatling {
    simulations = { include "**/*Test*.scala" }
}
...

You can execute all Gatling tests with ./gradlew gatlingRun.

Behaviour-driven development (BDD)

Behaviour-driven development (BDD) is available using Cucumber{:target="_blank" rel="noopener"}, with its JVM implementation{:target="_blank" rel="noopener"}.

Gherkin{:target="_blank" rel="noopener"} features will have to be written in your src/test/features directory.