Testing DSpace 7 Pull Requests

Why test DSpace Pull Requests?

One of the larger challenges to fixing a bug or improving/adding a new feature is end user testing. This activity is often reliant on other developers, but can be helped along by those in non-technical roles.  As a general policy, DSpace Committers require at least two reviewers/testers (from different institutions) for every Pull Request.  While this policy helps ensure all new code is stable, it can result in an accidental "bottle-neck" or roadblock if a secondary reviewer/tester cannot be located quickly.

While we do require automated tests for every new Pull Request, automated tests are not always able to accurately replicate normal user behavior.

Therefore, when more people are able to get involved in testing new code, the result is more stable & bug-free code.  Additionally, it increases the speed at which new code can be accepted – allowing us to get more features/fixes in each release of the software.

Getting Started

Required Software

In order to get started with testing DSpace Pull Requests (PRs), you need the following setup on your machine.

1. You need a GitHub login.  This lets you add a comment to any PR you test, letting developers know if you found problems or if all your tests were successful.
2. Install GitHub CLI.  This makes it easier to "checkout" (i.e. download) the PR code so you can test it.
3. Install Docker Desktop. This is the easiest way to get a DSpace backend installed locally for testing new (frontend or backend) PRs.
   1. NOTE: Docker recently changed their service agreement, but Docker remains free for personal use or non-commercial open source projects like DSpace.

   2. NOTE for Windows 10: Docker Desktop can sometimes become a bit "memory hungry" when it is running.  It's best to either disable the "Start Docker Desktop when you log in" setting (so that you only run it when needed).  Or, if you are using the default WSL2 backend, you can create a ".wslconfig" file in your user directory and limit the amount of memory you let Docker use (at least 4-6GB is recommended if you can spare it):

      .wslconfig

      [wsl2]
      memory=6GB

Installing the Backend (on Docker)

1. First, clone the backend codebase using GitHub CLI (gh).  This downloads all the code from GitHub to a directory named "DSpace". 

   # Run from command-line where ever you want the "DSpace" directory of code to be created.
   gh repo clone DSpace/DSpace
   
   # Once downloaded, change into that directory
   cd DSpace

2. Using Docker, pull down the latest backend images from DockerHub. This downloads all the prebuilt Docker images so you don't need to rebuild them locally.

   # This command should be run from the "DSpace" code directory
   docker-compose -f docker-compose.yml -f docker-compose-cli.yml pull

3. Using Docker, start the Backend on Docker & automatically install our Entities Test Data 

   # First start the backend with the test data
   docker-compose -p d7 -f docker-compose.yml -f dspace/src/main/docker-compose/db.entities.yml up -d
   
   # Run "logs -f" to watch the logs for everything to start up.  Or, just wait a few minutes until http://localhost:8080/server/ responds.
   docker-compose -p d7 -f docker-compose.yml -f dspace/src/main/docker-compose/db.entities.yml logs -f
   # (Click Ctrl+C to exit logs view)
   
   # Finally, download the test data assestore (of files) and install it, reindexing all content
   docker-compose -p d7 -f docker-compose-cli.yml -f dspace/src/main/docker-compose/cli.assetstore.yml run dspace-cli

4. DONE! At this point, you should be able to go to http://localhost:8080/server/ and see a backend similar to https://api7.dspace.org/server/
   1. You should also see some test data in that backend. For example, clicking on the "collections" endpoint should return some Collections: http://localhost:8080/server/#http://localhost:8080/server/api/core/collections

Installing the Frontend (on Docker)

1. First, clone the frontend codebase using GitHub CLI (gh).  This downloads all the code from GitHub to a directory named "dspace-angular".  You may wish to run this command from the same parent directory where you cloned the backend (just to keep these two folders next to one another). 

   # Run from command-line where ever you want the "dspace-angular" directory of code to be created.
   gh repo clone DSpace/dspace-angular
   
   # Once downloaded, change into that directory
   cd dspace-angular

2. Using Docker, pull down the latest frontend images from DockerHub. This downloads all the prebuilt Docker images so you don't need to rebuild them locally.

   # This command should be run from the "dspace-angular" code directory
   docker-compose -f docker/docker-compose.yml pull

3. Using Docker, start the frontend/UI: 

   docker-compose -p d7 -f docker/docker-compose.yml up -d
   
   # Optionally run "logs -f" to watch the logs for everything to start up.
   docker-compose -p d7 -f docker/docker-compose.yml logs -f
   # (Click Ctrl+C to exit logs view)

4. DONE! In a few minutes, the User Interface should be available at http://localhost:4000/   It should automatically be pointed at your Backend (also running on Docker)!
   1. Test it out by logging in using one of the demo accounts!  Login: dspacedemo+admin@gmail.com , Password: dspace

Testing a Frontend PR

Based on the setup above, here's how to test a new User Interface / Frontend Pull Request in the "dspace-angular" project: https://github.com/DSpace/dspace-angular/pulls

1. First, if your Frontend is currently running in Docker, let's stop it

   # Move into your "dspace-angular" directory where the frontend code is
   cd dspace-angular
   
   # Shutdown your frontend Docker containers (Note: your backend will still be running. That's OK)
   docker-compose -p d7 -f docker/docker-compose.yml down

2. Find the number of the Pull Request you want to test (it'll be the "#[number]" displayed after the PR name, or the end of the PR's URL).  Checkout the code from that PR using it's number: 

   # This would checkout https://github.com/DSpace/dspace-angular/pull/1383 for testing
   gh pr checkout 1383

3. Now, rebuild your frontend based on that PR's code:

   docker-compose -f docker/docker-compose.yml build

4. Once it's done, restart the frontend:

   docker-compose -p d7 -f docker/docker-compose.yml up -d

5. Now test the User Interface to see if the changes made in that PR look to work properly.  The PR's description should describe how to test it and what you should see.
   1. If you notice any odd behavior, check for errors in the UI using your browser's DevTools. See Troubleshoot an error#FindingtheErrorMessageintheUserInterface
   2. Based on what you find, add a comment to the PR. If it works, congratulate the developer. If it doesn't, let them know the error you saw (and what you clicked on when that error occurred).

Testing a Backend PR

Some frontend bugs or features also require backend changes.  Here's how to install those backend PR changes.  Yes, you can even test a backend PR and frontend PR at the same time by following the instructions in both "Testing a Frontend PR" and "Testing a Backend PR".

1. First, if your Backend is currently running in Docker, let's stop it

   # Move into your "DSpace" directory where the backend code is
   cd DSpace
   
   # Shutdown your backend Docker containers (Note: your frontend will still be running. That's OK)
   docker-compose -p d7 down

2. Find the number of the Pull Request you want to test (it'll be the "#[number]" displayed after the PR name, or the end of the PR's URL).  Checkout the code from that PR using it's number: 

   # This would checkout https://github.com/DSpace/DSpace/pull/8007 for testing
   gh pr checkout 8007

3. Now, rebuild your backend based on that PR's code:

   docker-compose -f docker-compose.yml -f docker-compose-cli.yml build

4. Once it's done, restart the backend:

   docker-compose -p d7 up -d

5. Now test the User Interface to see if the changes made in that PR look to work properly.  If there was a corresponding UI PR, make sure you also follow the instructions in "Testing a Frontend PR" to install that PR as well.
   1. If you notice any odd behavior, check for errors in the UI using your browser's DevTools. See Troubleshoot an error#FindingtheErrorMessageintheUserInterface
   2. Based on what you find, add a comment to the PR. If it works, congratulate the developer. If it doesn't, let them know the error you saw (and what you clicked on when that error occurred).