Merge pull request openwallet-foundation#880 from nodlesh/feature-remote-agent

Feature: Remote Agent support in OATH

Author: nodlesh

README.md

@@ -74,6 +74,8 @@ The following diagram provides an overview of the architecture of the AATH.
 - The `./manage` script also supports running the services needed by the tests, such as a [von-network](https://github.com/bcgov/von-network) Indy instance, an [Indy tails service](https://github.com/bcgov/indy-tails-server), a universal resolver and a `did:orb` instance.
   - Environment variables can also be used to configure a test run to use public services, such as the BCovrin test Indy instance. You'll find examples of using environment variables to use those services in various documentation files in this repo.
 - A special Test Agent called `mobile` can be used in the `Bob` role to test mobile wallet apps on phones. See [this document](./MOBILE_AGENT_TESTING.md) for details.
+- OATH has the ability to include remote agents in other/external environments into an interop test run. 
+This allows the verification of agents unmanaged by the test harness with other agents. See [this document](./REMOTE_AGENT_TESTING.md) for more details on the `remote` option. 
 
 ## Aries Agent Test Harness Terminology
 

REMOTE_AGENT_TESTING.md

@@ -0,0 +1,82 @@
+# Remote Agent Testing in OATH
+
+OWL Agent Test Harness is a powerful tool for running verifiable credential and decentralized identity interoperability tests. It supports a variety of agent configurations, including running agents locally that are test harness managed, or remotely, unmanaged by the test harness. This guide covers the **remote** option, allowing you to execute interoperability tests with agents running on remote servers in development, test, staging, or production environments, communicating with other remote agents or test harness managed agents.
+
+## Prerequisites
+
+Before using the `remote` option, make sure you have:
+
+- A running remote instance of an agent you want to connect to and test with.
+- The agent(s) controller has implemented the test api (backchannel api) for the protocols desired to be tested.
+- OATH is cloned and set up locally or on a machine with network access to your remote agent(s).
+- The remote agent(s) are configured with the same ledgers or tails server that OATH is configured with.
+- Valid configuration URLs for remote agents, including public endpoints to the test api in the agent controller.
+
+## Command Structure
+
+When running the test harness with remote agents, the basic command structure for setting remote agents is as follows:
+
+```bash
+./manage run -a remote --aep <acme_endpoint> -b remote --bep <bob_endpoint> -f remote --fep <faber_endpoint> -m remote --mep <mallory_endpoint> 
+```
+
+For any of the agent flags, `-a`, `-b`, `-f`, `-m`, if the agent is set to `remote` then the test harness will look for the long option of `--aep`, `--bep`, `--fep`, and `-mep` for the endpoint of that particular remote agent. 
+
+#### Long Options for Remote Endpoints
+
+- --aep: ACME agent’s remote endpoint URL (e.g., http://remote-acme.com).
+- --bep: BOB agent’s remote endpoint URL.
+- --fep: FABER agent’s remote endpoint URL.
+- --mep: MALLORY agent’s remote endpoint URL.
+
+#### Example Command
+```bash
+LEDGER_URL_CONFIG=http://test.bcovrin.vonx.io \
+TAILS_SERVER_URL_CONFIG=https://tails.vonx.io \
+./manage run \
+  -a remote --aep http://remote-acme.com \
+  -b acapy-main -f acapy-main -m acapy-main \
+  -t @T002-RFC0160
+```
+This example command will test a remote agent in the role if Acme, an issuer/verifier in conjuction with test harness managed acapy agents playing the other roles of Bob, Faber, and Mallory.
+
+Any combination of remote and test harness managed agents is testable, including all remote if one is so inclined.
+
+#### Local Example
+
+To verify and see the remote implementation in the test harness working locally, you will need to run one of the test harness agents outside of the OATH docker network. Then use that agent as a remote agent. 
+
+Build the local agents:
+```bash
+./manage build -a acapy-main
+```
+
+Run a remote agent locally:
+```bash
+./start-remote-agent-demo.sh
+```
+
+Run the tests:
+```bash
+LEDGER_URL_CONFIG=http://test.bcovrin.vonx.io TAILS_SERVER_URL_CONFIG=https://tails.vonx.io ./manage run -a acapy-main -b remote --bep http://0.0.0.0:9031 -f acapy-main -m acapy-main -t @T002-RFC0160
+```
+
+Shutdown the remote agent
+```bash
+./end-remote-agent-demo.sh
+```
+
+
+#### Handling Errors
+
+If you encounter any issues while using the remote option, check the following:
+
+- Endpoint URLs and Ports: Ensure the URLs and ports specified are correct and accessible from your local machine or environment the test harness is running in.
+- Agent Configuration: Make sure the agents on the remote server are properly configured and running.
+- Logs: Check the remote agents log in conjuction with the other agents logs for hints on what could be causing the errors. 
+
+## Conclusion
+
+The remote option in the Test Harness allows you to test verifiable credential interactions with agents running in remote environments. This flexibility essentially allows you to verify that your agent(s) can successfully interop with other agents for the implemented protocols. 
+
+For any extra troubleshooting please consult with the [OWL maintainers on Discord](https://discord.com/channels/1022962884864643214/1214965981470924911).

end-remote-agent-demo.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# set -x
+
+echo Stopping remote agent:
+docker stop fred_agent
+echo Removing remote agent:
+docker rm fred_agent