1. Create src/test/e2e directory in your project.

2. Run npm init in that directory. This will generate a package.json file.

3. Run npm install cypress --save-dev to install Cypress as a development dependency.

4. Run npx cypress open to start the Cypress application. It will notice that this is the first startup and add some example tests.

5. Run npm install cypress-multi-reporters mocha mochawesome --save-dev to install Mochawesome as a test reporter. Testcontainers-cypress will use that to parse the results of the Cypress tests.

6. Update cypress.json as follows:

   {
     "baseUrl": "http://localhost:8080",
     "reporter": "cypress-multi-reporters",
     "reporterOptions": {
       "configFile": "reporter-config.json"
     }
   }

7. Create a reporter-config.json file (next to cypress.json) and ensure it contains:

   {
     "reporterEnabled": "spec, mochawesome",
     "mochawesomeReporterOptions": {
       "reportDir": "cypress/reports/mochawesome",
       "overwrite": false,
       "html": false,
       "json": true
     }
   }

Maven

<dependency>
    <groupId>io.github.wimdeblauwe</groupId>
    <artifactId>testcontainers-cypress</artifactId>
    <version>${tc-cypress.version}</version>
    <scope>test</scope>
</dependency>

<project>
    <build>
        ...
        <testResources>
            <testResource>
                <directory>src/test/resources</directory>
            </testResource>
            <testResource>
                <directory>src/test/e2e</directory>
                <targetPath>e2e</targetPath>
            </testResource>
        </testResources>
    </build>
</project>

Gradle

testImplementation 'io.github.wimdeblauwe:testcontainers-cypress:${tc-cypress.version}'

processTestResources {
    from("src/test/e2e") {
        exclude 'node_modules'
        into("e2e")
    }
}

MochawesomeGatherTestResultsStrategy gradleTestResultStrategy = new MochawesomeGatherTestResultsStrategy(
    FileSystems.getDefault().getPath("build", "resources", "test", "e2e", "cypress", "reports", "mochawesome"));

new CypressContainer()
     .withGatherTestResultsStrategy(gradleTestResultStrategy)

The library is not tied to Spring Boot, but I will use the example of a @SpringBootTest to explain how to use it.

Suppose you have a Spring Boot application that has server-side rendered templates using Thymeleaf, and you want to write some UI tests using Cypress. We want to drive all this from a JUnit based test, so we do the following:

1. Have Spring Boot start the complete application in a test. This is easy using the @SpringBootTest annotation on a JUnit test.

2. Expose the web port that was opened towards Testcontainers so that Cypress that is running in a Docker container can access our started web application.

3. Start the Docker container to run the Cypress tests.

4. Wait for the tests to be done and report the results to JUnit.

Start by writing the following JUnit test:

1. Have Spring Boot start the full application on a random port.

2. Tell Spring Boot to not configure a test database, Because we use a real database (via Testcontainers obviously :-) ).

3. Have Spring inject the random port that was used when starting the application.

4. Ensures that the container will be able to access the Spring Boot application that is started via @SpringBootTest

5. Create the CypressContainer and pass in the port so the base URL that Cypress will use is correct.

6. Wait on the tests and get the results.

7. Check if there have been failures in Cypress. If so, fail the test.

If you are using JUnit 5, then you can use a @TestFactory annotated method so that it looks like there is a JUnit test for each of the Cypress tests.

1. Use the @TestFactory annotated as opposed to the @Test method

2. Use the CypressTestResults to generate DynamicTest and DynamicContainer instances

If the Cypress tests look like this:

Then running the JUnit test will show this in the IDE:

This makes it a lot easier to see which Cypress test has failed.