How to Use Your Existing CI/CD Platform to Automate Your Salesforce Apex Test Execution
We’ve all been there before — your urgent Salesforce deployment is failing because an Apex test is not passing. And what’s worse — the test was not even passing before your deployment, meaning that someone else’s change is causing the test to fail.
But why has no one yet noticed that this test is failing?
The reason is because Apex test execution in Salesforce is almost always a manual task. You can either manually run Apex tests, or you can wait until someone is manually deploying changes to run them.
To make matters worse, even changes made by no-code users can cause Apex tests to start failing. Imagine a test that creates an account — what happens if a no-code user user updates a validation rule on the account object? The test can no longer create the account due to a validation rule failure, so the test can now no longer pass.
OK, so what’s the best way to handle this?
To answer this question, we have to take a step back and ask “Why is this a problem with Salesforce, and not a problem with other development platforms and languages?”.
And the answer to that question is simple — most other software development platforms and languages allow you to set up checks and gates that can catch failures early and prevent them from entering the code base. In the case of tests — it would be common for a software development team to use a CI/CD platform such as GitHub Actions, Jenkins, Azure DevOps or TeamCity to automatically run all of your tests on a nightly basis and catch failing tests early. The earlier you can catch a failing test, the more time you have to fix it.
OK, so back to the original question — what’s the best way to handle this?
The answer should be obvious — run your tests frequently, catch failures early, and fix them quickly.
In this guide, I’m going to show you how to use OrgFlow to do exactly that.
There’s a load of CI/CD platforms out there, and your company probably already utilizes at least one of them. OrgFlow is a true CI/CD tool for Salesforce that acts as the glue between Salesforce and your CI/CD platform of choice.
Sure, we could use another Salesforce DevOps tool such as Gearset, Copado, or Click Deploy to schedule test execution, but none of them give us the deep integration into your CI/CD platform of choice that OrgFlow does.
We’ll be using GitHub Actions in this guide, but the same patterns and techniques will work for any popular CI/CD platform. So long as it allows you to schedule script-based jobs, you can probably use it to run OrgFlow.
What you’ll need:
- A username and password for a Salesforce org (plus a Security Token if your org requires them)
- A GitHub account
- A license key for OrgFlow. If you don’t already have one, we offer a free trial to help you get started.
Step 1 — Configure your repository
GitHub actions run within a repository. Usually this would be the same repository that contains your code, but for the purposes of this article, let’s just create a new repository. (It’s worth pointing out that OrgFlow can commit your metadata to a repository and also deploy it from your repository to your Salesforce org, but that’s outside the scope of this article.)
Once you’ve created your new repository, we’ll add some secrets to it to store your Salesforce credentials and OrgFlow license key.
Add the following secrets:
ORGFLOW_LICENSEKEY— Your OrgFlow license keySALESFORCE_USERNAME— The username that OrgFlow should use to authenticate with your Salesforce orgSALESFORCE_PASSWORD— The password that OrgFlow should use to authenticate with your Salesforce org. If your org also requires a Security Token, then you should append this to the end of your password (e.g.<password><security-token>)
Step 2 — Add a workflow
Next, click the Actions tab and click to create a “simple” or “blank” workflow. This will open the workflow editor to allow you to create a new workflow file in your repository.
Paste in the following code:
Let’s go through that line by line to make sure we understand what it all does:
- Line 1: Set a name for the workflow.
- Lines 3–6: Define the triggers for the workflow. There’s a schedule which will automatically start the workflow at 2:30 a.m. UTC every day, and there’s a
workflow_dispatchwhich allows you to manually start the workflow. - Lines 8 & 9: Sets the permissions that allows the workflow to write the test results to the output.
- Line 11 & onwards: Defines the jobs to be executed as part of the workflow (in this case, there’s only a single job):
- Line 12: Defines a job called
run-tests. - Lines 13–18: Defines the agent that will run this job. In this case we’re asking for a Ubuntu agent that is running the
orgflow/cliDocker image. We’re also accepting the OrgFlow EULA and setting our license key here. - Line 20 & onwards: Defines the steps that this job will execute. In this case there are two:
- Lines 21–23: Defines a step called
Run Salesforce Tests. This step uses OrgFlow to run thetool:testcommand, passing your Salesforce username and password, and also setting a location for the test results to be outputted to. - Lines 24–28: Defines a step called
Publish test results. This step utilizes a third party action from the GitHub Actions Marketplace to take the test results file that the previous step created and then publish the contents of it in a human readable format to GitHub.
Now that we understand what the workflow will do, let’s commit and run it. Click the Start commit button to commit the workflow file to your repository.
Step 3 — Run the workflow
Go back to the Actions tab, select the Runs Salesforce Tests workflow from the list on the left, open the Run workflow drop down and then click the Run workflow button.
This will start your workflow. If all is well, OrgFlow will run your Salesforce tests, and then the third party action that we added will publish the test results to GitHub.
It’s worth noting that by default, OrgFlow will fail your workflow if any tests fail to pass. This behavior is configurable, but that’s out of the scope of this article. If this happens, it might look like your workflow has failed, but rest assured that it has ran all the tests and published the results as expected.
The third party action that we are using to publish the test results to GitHub will add a section to the workflow’s output with the test results:
Of course, there are a few different third party actions that can publish test results. So if you do not like the way that this action publishes them, you are free to find another and swap it out.
Troubleshooting
The most common error message you might encounter is LOGIN_MUST_USE_SECURITY_TOKEN: Invalid username, password, security token; or user locked out. Are you at a new location?. This is a message from Salesforce that means that OrgFlow is not able to authenticate to Salesforce with the credentials provided. The most common cause of this is forgetting to append your Security Token to the end of your password when setting the SALESFORCE_PASSWORD secret.
Key takeaways
OrgFlow allows you to automate your Salesforce DevOps using standard CI/CD platforms that your team is probably already using and familiar with.
In this article, we looked at automating test execution, but OrgFlow can also manage your metadata backups, deployments, and even merge metadata from one Salesforce org to another.
One of the major advantages of using standard CI/CD platforms for your Salesforce DevOps are the deep integrations and large ecosystems already available. OrgFlow doesn’t box you in to a particular web-based UI — you are free to use the best tool for your team. And using standard CI/CD tasks that are not specific to Salesforce gives you much more choice and freedom. If you don’t like the way that tests results are rendered then you can simply swap that part out for another third party action.
OrgFlow is a true git-based DevOps tool for Salesforce. We offer deep integration into almost all CI/CD platforms, and we’re currently offering a two month free trial so that you can get to grips and explore all the features that we offer.
