Bridge has an EC2 machine for manually running integ tests. The reasons we want an EC2 machine is because running it on a laptop takes too much CPU and memory, which slows down integ tests and prevents doing any other work on that laptop.

This is a temporary solution specifically intended to workaround Jenkins being defunct. There is long-term unscheduled work to find a proper CI/CD solution to replace this. That work is not covered in this document.

Setup Integ Test Machine

These are instructions for how to set up the Integ Test EC2 machine. You shouldn’t have to follow these instructions, unless for whatever reason that EC2 machine needs to be replaced.

1. Log into AWS and navigate to the EC2 dashboard.

2. Click Instances on the left nav bar, then click Launch Instances on the top right. Create a host with the following:

   • Name: Something descriptive like bridge-integ-test

   • AMI: Amazon Linux 2023

   • Architecture: 64-bit (Arm) - We want Arm so we can use AWS’s newer (cheaper) hardware types.

   • Instance Type: t4g.medium - We chose medium because the old Jenkins machine was a medium. We might be able to get away with a small, but the difference is ~$25/mo vs $12.5/mo.

   • Key Pair: bridge-integ-test.pem

   • VPC: vpc-e9335a92 (bridge-aux)

   • Auto-assign public IP: Enable

   • Firewall (security groups): Select existing security group → bridge-aux-VpnSecurityGroup-8CNS9SY6YHNY

3. Once the new instance is up and running, SSH into the Integ Test Machine as per the instructions below.

4. Bridge Server and Worker require Java 8. Install Amazon’s Java 8 JDK (Corretto) by running sudo yum install java-1.8.0-amazon-corretto-devel.

5. Install Git, using sudo yum install git.

6. Install Maven, using sudo yum install maven-amazon-corretto8.

7. In your home directory, create .aws/config with the following content:

   [default] region=us-east-1

8. In your home directory, create a git directory. In that directory, run git clone https://github.com/Sage-Bionetworks/BridgeIntegrationTests.git and git clone https://github.com/Sage-Bionetworks/BridgeWorkerIntegrationTests.git. Since these are public repos and we are doing read-only, we don’t need login credentials.

9. In your home directory, create the file bridge-sdk.properties with the following content:

   env = develop app.identifier = api

10. Go to LastPass and search for bridge-integ-test bridge-sdk-test.properties. Copy this file to the home directory in the Integ Test Machine. (The easiest way to do this is to use vi on the Integ Test Machine and then copy-paste the file into vi.)

11. Do the same for bridge-integ-test BridgeWorker-test.conf.

12. Back in your home directory, create a log directory. This will be where our integ test logs are going.

SSHing into the Integ Test Machine

1. Log into AWS and navigate to the EC2 dashboard.

2. Click on Instances in the left nav bar, and select the bridge-integ-test instance. Note the Public IPv4 DNS (should be something like ec2-3-92-255-6.compute-1.amazonaws.com).

3. Go to LastPass and download bridge-integ-test.pem. Make sure to chmod 600 bridge-integ-test.pem to ensure permissions are being set correctly.

4. On your laptop, open (or create) .ssh/configwith the following. There can be multiple entries if this file already exists. Substitute the host name you copied down above.

   Host bridge-integ-test HostName ec2-3-92-255-6.compute-1.amazonaws.com IdentityFile ~/bridge-integ-test.pem User ec2-user

5. Log into Sage VPN.

6. Now you can simply run ssh bridge-integ-test.

Running Integ Tests

1. SSH into the Integ Test Machine as per above.

2. Edit bridge-sdk.properties, bridge-sdk-test.properties, and BridgeWorker-test.conf. For Worker Integ Tests, you’ll need to update all 3 files. For Server Integ Tests, you only need to update the first 2.

   • The simplest way is to use vi.

   • In bridge-sdk.properties, at the top of the file is the env property. Set this to develop or staging or production accordingly.

   • In BridgeWorker-test.conf, at the top of the file is the bridge.env property. Set this to dev or uat accordingly. (Note, Worker Integ Tests don’t run Note, this is different from bridge-sdk.properties. Both are needed for Worker Integ Tests.)

   • Note: bridge-sdk-test.properties doesn’t have an env property.

   • Also, uncomment the properties for env you want to test. Comment out the properties for the envs you aren’t testing.

3. cd into the directory of the test you want to run (git/BridgeIntegrationTests or git/BridgeWorkerIntegrationTests).

4. git pull to update the integ tests. git log --oneline to verify that the changes you pulled are the ones you expected.

5. Run mvn -U clean test -e &> ~/log/server-dev-yyyy-mm-dd-hhmm.log &.

   • IMPORTANT: If running production tests, run this instead: mvn -U clean test -DjunitCategory=integrationSmokeTests -e &> ~/log/server-prod-yyyy-mm-dd-hhmm.log &. Some tests cannot be run in production, and this ensures that only our smoke tests are run. (Worker Integ Tests do not run at all in Production.)

     • Note: UploadTest testRedriveUploadSmallBatch() and testRedriveUploadLargeBatch() don’t succeed in Prod. This never succeeded in Prod, because it uses Superadmin API, and we don’t have Superadmin credentials in our Integ Test Machine. We should change this to not run in Prod.

   • The -U makes sure we update all packages in our Maven package cache. Running without this flag has led to weird dependency issues in the past.

   • clean ensures we have a clean workspace before running tests.

   • -e also produces error messages.

   • &> sends both stdout and stderr to the specified file.

   • Name the log file according to your stack (server or worker), env (dev, uat, or prod), and set the timestamp accordingly. This is to disambiguate between test runs.

   • & runs Maven in a separate process, so that if the SSH session dies, Maven still continues to run our integ tests.

Server tests take about 37 min in Dev and Staging, 8 min for Prod. Worker tests take about 15 minutes.