Manual compare and deploy

When deploying or validating a package to Salesforce using Gearset, you're able to specify which Apex test classes you want Salesforce to execute as part of validating the package.

When you choose this option, Gearset will list all of the available test classes that are contained in the target org or in the package itself.

Here, because my package included the Apex class named MyClass, Gearset suggests that I probably want to run MyClass_T. It has based this on the _T suffix, which is one of a few patterns used to suggest tests based on naming convention.

The feature to automatically detect relevant tests is actively being developed, with the name-based suggestions being the most recent update. If you encounter any situations where we aren't suggesting a test that you would have expected, please let us know via the in-app chat and we'll make improvements where possible.

Continuous integration jobs

It's also possible to use the suggested tests feature when setting up a CI job.

With a manual compare and deploy, you're in a position to amend the suggestions, adding extra tests and removing those you're not interested in running.

When it comes to CI runs, there's no manual selection of tests, so it's important to know how the suggested tests are chosen. This will enable you to maximize the chances of running all the relevant tests and achieving acceptable code coverage.

When is a test class suggested?

A test class will be suggested if one or more of the following criteria are met:

It is included in the package itself.
It matches the naming convention.
It references a class contained in the package.

* ( if you select matching naming conventions plus tests referencing changes it will include any tests from dependent Apex classes)

Let's look at these criteria one by one.

Test class included in the package

If you're changing an existing test or deploying a new one as part of your package, then Gearset will include these in the suggestions.

Matches the naming convention

In practical terms, making sure that the test class matches the naming convention is one of the easiest ways to ensure that a test class will be suggested.

If MyClass is included in the package, the naming convention will include any tests with the following names:

MyClass_Test
MyClass_Tests
MyClassTest
MyClassTests
MyClass_T

These matches are done case-insensitively, e.g. we'll include MyClassTEST.

These naming conventions apply to Apex classes and Apex triggers. So, for example, if MyTrigger is included in the package, then having a test named MyTriggerTests will ensure that the test will be suggested.

References a class in the package

When Gearset needs to provide test suggestions, it makes a call to the Salesforce API and requests a list of all Apex classes and their associated symbol tables. These tables are used to determine if there are any test classes in the org that have a reference to one of the Apex classes being deployed.

Known issues and limitations

Changing an Apex Trigger won't cause any tests to be suggested. We suggest that you follow the standard pattern of having a helper/utility class that contains all of the logic, then call that from the trigger. The trigger then doesn't change once it's deployed.

e.g.,
Trigger calls methods in TriggerHelper
TriggerHelper is tested by TriggerHelperTests
The testing is performed indirectly by using inserts/updates/etc.
Changes to the functionality are made in TriggerHelper
Trigger is never changed

In order for Gearset to know that TriggerHelper is tested by TriggerHelperTests, a single reference to TriggerHelper needs to be made somewhere within TriggerHelperTests. That can simply be a field in the class. For example:
```
public class TriggerHelperTests {
    TriggerHelper referenceForDependencyTracking;
    ... exercise Trigger by appropriate inserts/updates/etc. ...
}
```
If Salesforce is already compiling Apex when Gearset requests the symbol tables, it will return null. This occasionally results in no tests being suggested, which in turn would mean 0% code coverage and a failed validation.

To mitigate the issue, Gearset retries a number of times (currently 10). There is an increased delay between each try, to avoid any regularly timed compilations that might be happening in the org.

There is no workaround should we reach the end of the retries, but the naming convention test will still apply, as we do receive the class names even when we don't receive the symbol tables.
We only take account of direct references between the test file and the class it is testing. If you have situations where you expect the inclusion of class A to cause test class C to be run when C only interacts with A through one or more intermediate classes, then a reference to A would need to be added to C.

Example
1. MyClass is the only class included in a deployment.
2. IntermediateClass uses MyClass.
3. IntermediateClassTests are tests that target IntermediateClass.

Future improvements

Gearset development is guided by our customers, so please let us know if you have any suggestions about how we could improve this feature.