Test Connectors in App Xchange

This topic provides information on testing endpoints for a newly developed connector on the platform. It assumes that you are already familiar with App Xchange and have read the following sections of the help documentation: 

• Getting Started

• Connectivity

• Flows

• Jobs

• Data Explorer

To test a connector in App Xchange, you need a workspace with an active and working connection to the external system for which your connector is built.

See the Testing a Connector Locally section of the SDK for local testing, which should be completed before deployment.

Test a Cache Writer (Data Reader)

Cache writers or data readers read and replicate data from a connected system. When testing, you must perform the following verifications.

1. Confirm the replicated data is in an accurate state concerning value equality and formatting.

2. Confirm all the data representing this object is present when read from the connected system. Consider the following questions.

• Should empty properties be written as null or not written at all?

• Does the connected application allow for custom fields or fields to be renamed? Are those written correctly when present?

• Are any fields sent conditionally based on the values of other properties? If so, you must test all variations.

3. Confirm all read types are handled correctly. This includes:

   • Adding a new record.

   • Updating an existing record.

   • Deleting an existing record.

Verify a Cache Writer

Use this test plan to ensure all necessary scenarios have been tested. Follow these steps to verify a cache writer:

1. Run the cache writer once to verify a complete write of the data in the connected system. For information about how to create and run a service, see Jobs.

• In the Job History, the count expected is the same as the logs and that there are no errors.

• The objects display as expected in the Data Cache Explorer.

2. Confirm that the cache writer picks up new objects.

• Add a new object in the connected system (after the initial cache write).

• The object displays correctly in the job history logs.

• The object displays correctly when viewing the record in the Data Cache Explorer.

3. Confirm that the cache writer picks up changes to existing objects.

• Update an existing object in the connected system. Verify that it is detected as an update in the cache writer and verify the change in the Data Cache Explorer.

• If a change in the connected system can affect others, verify that the change is detected in all systems.

4. Confirm that the cache writer removes deleted objects.

• Delete an existing object (or the new one you created above).

• Verify the object is deleted in the logs.

• Verify the object is no longer present in the Data Cache Explorer.

Test an Action Processor

Action processors write data to a connected system. To run an action processor, use the Connector Action flow step. Afterward, test the action output by verifying the following details. These checks should be run for every new action processor added to a connector.

• The action outputs look correct in the run history.

• The logs look correct in Job History > Not Scheduled.

• The object displays correctly in the Data Explorer.

• Any changes are reflected correctly in the connected system.

Action processors can handle many different action types. Perform these additional checks for each different type of action processor.

1. Adds (Adding one or more objects into the connected system, will fail if an object matching the key exists):

• Verify all variants of key value references used by the action correctly detect matches in the connected system either create a new object successfully or fail gracefully if that is the expected result.

• Verify that defaulting logic works correctly when submitting an object with only the minimum required fields filled (minimum data set).

• Verify that all properties are sent correctly when filling out all possible fields (maximum data set).

• Verify the functionality of any custom validation or defaulting logic that was written into the action processor (rather than being handled by the connected system’s API).

2. Changes (Updating one or more objects in the connected system, will fail if no object matching the key exists in the connected system):

• Verify all variants of key value references used by the action correctly detect matches in the connected system and either successfully update the referenced object or fail gracefully when no object matches the provided key.

• Verify that defaulting logic works correctly when submitting an object with only the minimum required fields filled (minimum data set).

• Verify that all properties are sent correctly when filling out all possible fields (maximum data set).

• Verify the functionality of any custom validation or defaulting logic that was written into the action processor (rather than being handled by the connected system’s API).

3. Upserts (A hybrid action that can be used for both add and change actions (will add rather than fail if no object in the connected system matching the key exists):

• Verify all variants of key value references used by the action correctly detect matches in the connected system. and either update an existing object or add a new one depending on whether an existing object matching the key existed prior to running the action.

• Verify that defaulting logic works correctly when submitting an object with only the minimum required fields filled (minimum data set).

• Verify that all properties are sent correctly when filling out all possible fields (maximum data set).

• Verify the functionality of any custom validation or defaulting logic that was written into the action processor (rather than being handled by the connected system’s API).

• For upserts, the above tests need to be run for both adding new objects and updating existing objects.

4. Deletes (Removes the object matching the provided key values from the connected system):

• Verify all variants of key value references used by the action correctly detect matches in the connected system.

5. Refresh Cache (Runs the cache writer from within in a flow rather than from a scheduled run of the service):

• Verify that the cache writer runs correctly - perform all checks referenced in the Testing Cache Writers (Data Readers) section of this page.

Print the checklist using your computer's print options.

Automate Testing with Flows

Whenever you modify an Action Processor or Cache Writer, you should run the Test an Action Processor steps again. This is especially important when updating endpoints that are already in use. To help reduce the time needed to regression test changes to existing endpoints, much of the above can be automated using the following pattern in flow:

1. Use the Connector Action step to run the Action Processor. Seed this step with data and logic as necessary to allow it to be rerun (on demand or a schedule) without changes and successfully execute each time.

2. Use a Lookup flow step to look up the record by its key value in the cache. Expect exactly one object matching the key to be present. This also provides testing of the cache writer, as this object gets written to the cache from the connected system after insertion. In other words, this is a representation of the object as it exists in the connected system.

3. Use an Assertion Step to test various expectations about the object’s data state that should be true. It is recommended to test every property.