This guide will teach you how to clone and set up the DXPR Maven test automation project for local development and testing. You will have a Java runtime environment with Maven and TestNG framework configured when successfully setting the environment up.

 

Prerequisites

  1. Refer to the machine setup documentation before proceeding with this guide.
  2. Make sure that you already set up the DXPR Builder project on your machine.

 

Clone and setup DXPR Maven

  1. Clone the DXPR Maven repository: git clone [email protected]:dxpr/dxpr_maven.git.
  2. Open the project directory in your favorite text editor.
  3. Copy the .env.example file and rename it to be .env
  4. Open the .env file and set the DXPR_ACCESS_TOKEN=[access_token]variable and save the file. You can get your token from the downloads page at dxpr.com in the JSON Web Token tab​​​.
  5. You can now start developing the maven project and changing files in your preferred editor. The recommended Java code editor is the Intellij IDEA community edition. Once you changed any file and want to run the tests, proceed to the next steps.
  6. Ensure that you followed the second prerequisite before proceeding and that the QA demo website is up and running at http://drupal.docker.localhost:8000/.
  7. In a separate terminal tab make sure you are at the DXPR maven project root directory, then run
    ./scripts/qa-demo.test.sh
    This command starts a selenium grid and a standalone chromium node to run tests on. After the command executes, it will open a terminal instance inside a maven container where you have a Java run time environment.
  8. In this terminal instance inside the maven container, you will need to run this command only once per clone
    ./scripts/maven.properties.install.sh
    This will configure some environmental variables essential for running the Java application. 
  9. Now, you can start executing maven commands as if you would do in a java runtime environment. To run a TestNG test suite, we will use the mvn command, run
    ./scripts/qa-demo.wait.sh $DEMO_HOST mvn test -DsuiteXmlFile=$TEST_SUITE
    Let's explain what this command is doing:
  • ./scripts/qa-demo.wait.sh: This script is just waiting until the QA demo website is ready for handling connections.
  • $DEMO_HOST: This variable is a parameter passed to the wait script that resolves to the QA demo website hostname.
  • mvn test -DsuiteXmlFile=$TEST_SUITE: This is how you would normally run a test suite using the mvn command specifying the test suite file name via the variable $TEST_SUITE. 

After executing this command, you will find that the maven project starts building, and then after successfully building, it starts running the tests. Running all of the tests may take a substantial amount of time. So, execute and switch to another task until it finishes executing.

How to terminate the maven container terminal instance

If there is a process running inside the maven terminal, hit ctrl+c first. If not, just type exit and press Enter, this will exit the terminal session inside the maven container. It's always a good step to clean up the environment by running this command
./scripts/test.dev.cleanup.sh
This will stop and remove all used containers and networks. You may also need to stop the QA demo website that you started before opening the maven terminal session. Refer to the setup of the DXPR Builder project guide on how to properly stop it.

Troubleshooting

  • If you get an error when trying to run the tests, make sure that the QA demo is up and ready for handling connections.
  • If the QA demo is up and running but you still get errors, terminate the maven container terminal instance and re-run this command
    ./scripts/qa-demo.test.sh
    This will reopen the maven container terminal instance and you can start running the tests again.
  • If you still have trouble, make sure the QA demo website is functioning as expected. If you think it is broken or has an issue, you can refer to the DXPR Builder project guide and reinstall the website following the troubleshooting section.