📝 Updated the README file to include test setup information

Also moved a constant from AemInstance to TestUtils to make this more
consistent with other constants that may need to be updated as part of
the setup.

Author: rmcdouga

rest-services/it.tests/README.md

@@ -2,10 +2,38 @@
 
 This maven project contains the Integration tests that run against (and require) a real AEM instance.
 
-Some tests are tagged because they require the ream AEM instance to be configured in a specific way.  These tags are:
+The types of AEM instances that are supported are: Local AEM instance, Remote AEM instance (Windows or Linux), Containerized AEM instance (via [TestContainers](https://testcontainers.com/)).  Depending on the type of AEM instance, some changes to the source code may be required.
 
-`requiresPdfG` - Requires PDFG to be configured
+The tests make sure Aem is up and running before they start, so you can launch the AEM instance, followed immediately by the tests.  The tests will wait for AEM to come up before they run (or timeout if AEM is not running within 5 minutes of the tests being launched.)
 
-`requiresRe` - Requires a Reader Extensions credential to be configured.
+## Preparing to run the tests
 
-You can exclude these tags in order for the tests to run successfully when the AEM instance is not configured to meet these requirements.
+All tests assume that AEM has been installed and configured with the AEM Forms Add-on, FluentForms .jars have been installed, and that HTML5 Protected Mode has been turned off.  It also assumes that the `sling.properties` has been updated with the JSAFE setting per the [Adobe documentation](https://experienceleague.adobe.com/en/docs/experience-manager-65-lts/content/forms/install-aem-forms/osgi-installation/install-configure-document-services#configure-boot-delegation-for-rsa-bouncycastle-libraries).
+
+There are some tests that assume that PDFG has been installed and configured.  These are tagged with the `requiresPdfG` tag, so you 
+can configure JUnit to exclude these tests if PDFG has not been installed.
+
+There are some tests that assume that a Reader Extensions credential called `recred` has been installed and configured.  
+These are tagged with the `requiresRe` tag, so you can configure JUnit to exclude these tests if the Reader Extensions credential has not been installed.
+
+The tests also assume that the sample files are available on the machine running the AEM instance.  This is automatically true for Local AEM instances, but the sample files (under `test_containers/ff_it_files`) must be transferred manually for remote AEM instances.  On Windows machines the samples should be placed under `\Adobe\ff_it_files`.  On Linux machines, they should be under `/opt/adobe/ff_it_files`.  This follows the 4Point standard practice of installing AEM under `\Adobe\AEM_##_SP##` on Windows machines and under `/opt/adobe/AEM_##_SP##` on Linux machines.
+
+### Local AEM Instance
+This is the default scenario.   The tests assume that a properly configured instance of AEM is up and running on port 4502.
+They assume that the default username/password (`admin`/`admin`) are available.
+
+You can change any of the defaults by changing the constants in `TestUtils.java`. 
+
+### Remote AEM Instance
+You can configure the tests to run against a remote AEM instance by altering `AEM_TARGET_TYPE` in `TestUtils.java` to `AemTargetType.REMOTE_WINDOWS` or `AemTargetType.REMOTE_LINUX`.  NOTE: the tests assume that AEM has been configured as outlined above (with FluentForms, protected mode, sample files, etc.).
+
+The machine name and port of the remote instance must be set in `TestUtils.java` via the `TEST_MACHINE_NAME` and `TEST_MACHINE_PORT` constants.  If the default username/password (`admin`/`admin`) are not available, then the `TEST_USER` amd `TEST_USER_PASSWORD` constants in that file must also be updated with a valid username/password.
+
+### Containerized AEM Image (via TestContainers)
+You can configure the tests to run against AEM running in a local container image by altering `AEM_TARGET_TYPE` in `TestUtils.java` to `AemTargetType.TESTCONTAINERS`. 
+ 
+ The name of the container image must be configured via the `AEM_IMAGE_NAME` constant in `TestUtils.java`.  Since AEM is 
+ proprietary software, a pre-prepared image cannot be made available publicly, however this project contains a dockerfile (`test_containers/ff_it_test.dockerfile`) that can take a base AEM instance and copy the sample files to it.
+ See the README in that directory for more details. 
+    
+The TestContainers code assumes that the image contains an AEM instance running on port 4502.  The TestContainers code is located in the `AemInstance.java` source file. 

rest-services/it.tests/src/test/java/com/_4point/aem/docservices/rest_services/it_tests/AemInstance.java

@@ -25,20 +25,14 @@ public enum AemInstance {
 
 	private static final String LOCALHOST = "localhost";
 
-	// These tests require an AEM container image with AEM forms installed.  Since AEM is proprietary, it is not possible to obtain this
-	// through public images.  By default, this uses a private image hosted in the 4PointSolutions-PS GitHub organization.  If you are not
-	// part of that prg, you will have to supply your own image.
-//	private static final String AEM_IMAGE_NAME = "ghcr.io/4pointsolutions-ps/aem:aem65sp21";
-//	private static final String AEM_IMAGE_NAME = "aem_lts:aem65lts";
-	private static final String AEM_IMAGE_NAME = "aem_lts_it_tests:aem65lts_it_tests";
 
 	private final AemTargetType targetType;
 	private final GenericContainer<?> aemContainer;
 	private final AtomicBoolean preparedForTests = new AtomicBoolean(false);
 
 	@SuppressWarnings("resource")
 	private AemInstance(AemTargetType targetType) {
-		this(targetType, targetType == AemTargetType.TESTCONTAINERS ? new GenericContainer<>(DockerImageName.parse(AEM_IMAGE_NAME))
+		this(targetType, targetType == AemTargetType.TESTCONTAINERS ? new GenericContainer<>(DockerImageName.parse(TestUtils.AEM_IMAGE_NAME))
 																	   .withReuse(true)
 																	   .withExposedPorts(4502)
 							   : null);

rest-services/it.tests/src/test/java/com/_4point/aem/docservices/rest_services/it_tests/TestUtils.java

@@ -46,6 +46,13 @@ public class TestUtils {
 	//		* GeneratePrintedOutput test AllArgs seems to want D:\FluentForms\Forms - Need to fix tests
 	//		* Generate HTLML5 test fails because protected mode is on - Need to fix AEM image creation code to set this.
 
+	// The TESTCONTAINERS configuration requires an AEM container image with AEM forms installed.  Since AEM is proprietary, it is not possible to obtain this
+	// through public images.  By default, this uses a private image hosted in the 4PointSolutions-PS GitHub organization.  If you are not
+	// part of that prg, you will have to supply your own image.
+//	public static final String AEM_IMAGE_NAME = "ghcr.io/4pointsolutions-ps/aem:aem65sp21";
+	public static final String AEM_IMAGE_NAME = "aem_lts_it_tests:aem65lts_it_tests";
+
+	
 	private static final String SAMPLE_FORM_PDF_NAME = "SampleForm.pdf";
 	private static final String SAMPLE_FORM_XDP_NAME = "SampleForm.xdp";
 	private static final String SAMPLE_FORM_WITH_DATA_PDF_NAME = "SampleFormWithData.pdf";