Test Connectors in App Xchange

This page is  intended to provide information on testing endpoints for your connector. It assumes that you are already familiar with App Xchange and have read the following sections of the help documentation: 

• Getting Started 

• Accounts and Workspaces 

• Connectivity 

• Flows 

• Jobs 

• Data Explorer 

To perform your testing in the App Xchange UI, you will need to have an account with a workspace that has 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.

Test a Cache Writer (Data Readers)

Cache Writers / Data Readers read and replicate data from a connected system. When testing, you need to verify: 

1. Data Accuracy - the replicated data is in an accurate state with respect to:

   • Value equality

   • Formatting

2. Data Completeness - all the data representing this object is present when read from the connected system.

Some things to consider:

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

• Does the connected application allow for custom fields or the renaming of fields? Are those written correctly when present?

• Are there any fields that are sent conditionally based on the values of other properties? If so, you’ll need to test all variations.

3. All read types are handled correctly. You should test: 

   • Adding a new record

   • Updating an existing record

   • Deleting an existing record

A typical test plan is used to ensure all necessary scenarios have been tested. Verify a cache writer includes: 

1. Running 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 the About Jobs documentation. 

• 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. Testing 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. Testing that the cache writer picks up changes to existing objects.

• Update an existing object in the connected system and 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 change is also detected as expected

4. Testing 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, create a flow that includes a step that runs your action via the Connector Action step.

 Afterward, test that the action output by verifying:

• 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

These checks should be run for every new Action Processor added to a Connector.

Action Processors can handle a variety of different action types - here’s a list of the different variants and what needs to be checked for each:

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 (An action that effectively runs the cache writer but is initiated 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

6. For all of the above, verify: 

• 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

Print the checklist using your computer's print options.

Automate Testing with Flows

When making changes to an Action Processor or Cache Writer, you should run the above 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 on a schedule) without changes and successfully execute each time.

2. Use a Lookup 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, so 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. Ideally you would test every property.