What is ApexUnit?
ApexUnit is a continuous integration tool for the Force.com platform that executes Apex tests and fetches code coverage results.
ApexUnit comprises of two major components:
- An xUnit based testing framework for the Force.com platform
- Extensive code coverage metrics with actionable detail for specified Apex classes
Key Features of ApexUnit
Please refer https://github.com/forcedotcom/ApexUnit/wiki to learn more about the key features of ApexUnit and its usage
- Java 1.6 or later
- Maven 3.0.3 or later (latest version is recommended)
- OAuth setup for the org to retrieve the Client ID and Client Secret using a Connected App
- Please verify the oauth setup for the org by executing the following command:
curl -v <Salesforce_Org_URL>/services/oauth2/token -d "grant_type=password" -d "client_id=*CLIENT_ID_GOES_HERE*" -d "client_secret= *CLIENT_SECRET_GOES_HERE*" -d "firstname.lastname@example.org*" -d "password= *your_password_goes_here+*"
*The above command should provide you the access_token in a JSON formatted response. If you are running this command from an IP address that is outside of the trusted IP range specified by your connected app, you must append a security token to your password.
- If your password contains special characters, you must pass in a URL encoded version of your password. Note that this only needs to be done for the curl command and not the maven command
How to build and execute ApexUnit
- Clone the project onto your local system using the command:
git clone https://github.com/forcedotcom/ApexUnit.git
This would create a local copy of the project for you.
- (Optional) Open the project in an IDE (Eclipse, IntelliJ, etc.)
- There are two ways you can select test classes to execute and select classes you wish to examine the code coverage of
- regex - identify and provide regex for the test class names that you want to execute in the "-regex.for.selecting.test.classes.to.execute" parameter. Example: if you want to execute the tests: My_Apex_controller_Test, My_Apex_builder_Test and My_Apex_validator_Test, identify the regex as "My_Apex_*Test". Pass the parameter "-regex.for.selecting.test.classes.to.execute My_Apex*_Test" in the mvn command.
- Similarly, you can provide regex for the classes for which you want to examine the code coverage of by using "-regex.for.selecting.source.classes.for.code.coverage.computation My_Apex_*_Class" in the mvn command.
- Manifest files - Lists of tests can be read from Manifest files. Create a manifest file such as ManifestFile_Unit_Tests.txt in the "src/main/resources" directory of your project. Add test class names to execute in the manifest file. Specify this manifest file in the mvn command like "-manifest.files.with.test.class.names.to.execute ManifestFile_Unit_Tests.txt".
- Similarly, add the class names for which you want to exercise code coverage in a manifest file such as ClasssManifestFile.txt in "src/main/resources" directory of your project and specify this manifest file in the mvn command like "-manifest.files.with.source.class.names.for.code.coverage.computation ClassManifestFile.txt".
- Note that multiple regexes and manifest files can be specified using comma seperation(without spaces). Example: "-regex.for.selecting.test.classes.to.execute This_Is_Regex1*,*Few_Test,Another_*_regex -manifest.files.with.source.class.names.for.code.coverage.computation ClassManifestFile.txt,MoreClassesManifestFile.txt"
- Go to your project directory (the directory containing pom.xml) in your commandline and execute the following command:
mvn compile exec:java -Dexec.mainClass="com.sforce.cd.apexUnit.ApexUnitRunner" -Dexec.args="-org.login.url $Salesforce_org_url -org.username $username -org.password $password -org.client.id $client_id -org.client.secret $client_secret -org.wide.code.coverage.threshold $Org_Wide_Code_Coverage_Percentage_Threshold -team.code.coverage.threshold $team_Code_Coverage_Percentage_Threshold -regex.for.selecting.source.classes.for.code.coverage.computation $regex_For_Apex_Classes_To_Compute_Code_Coverage -regex.for.selecting.test.classes.to.execute $regex_For_Apex_Test_Classes_To_Execute -manifest.files.with.test.class.names.to.execute $manifest_Files_For_Apex_Test_Classes_To_Execute -manifest.files.with.source.class.names.for.code.coverage.computation $manifest_Files_For_Apex_Source_Classes_to_compute_code_coverage -max.test.execution.time.threshold $max_time_threshold_for_test_execution_to_abort" -proxy.host $prox_host -proxy.port $proxy_port
Please replace all $xyz with the values specific to your environment/project
- -org.login.url : Login URL for the org (for example, https://na14.salesforce.com)
- -org.username : Username for the org
- -org.password : Password corresponding to the username for the org
- -org.client.id : Client ID associated with the org.
- -org.client.secret : Client Secret associated with the org.
- -org.wide.code.coverage.threshold (default value: 75) : Org wide minimum code coverage required to meet the code coverage standards
- -team.code.coverage.threshold (default value: 75) : Team wide minimum code coverage required to meet the code coverage standards
- -regex.for.selecting.source.classes.for.code.coverage.computation : The source regex used by the team for the apex source classes. All classes beginning with this parameter in the org will be used to compute team code coverage
- -regex.for.selecting.test.classes.to.execute : The test regex used by the team for the apex test classes. All tests beginning with this parameter in the org will be selected to run
- -manifest.files.with.test.class.names.to.execute : Manifest files containing the list of test classes to be executed
- -manifest.files.with.source.class.names.for.code.coverage.computation : Manifest files containing the list of Apex classes for which code coverage is to be computed
- -max.test.execution.time.threshold : Maximum execution time(in minutes) for a test before it gets aborted
- -proxy.host : Proxy host for external access
- -proxy.port : Proxy port for external access
- -help : Displays options available for running this application
Note: You must provide either of the (-regex.for.selecting.source.classes.for.code.coverage.computation OR -manifest.files.with.source.class.names.for.code.coverage.computation) AND either of -(regex.for.selecting.test.classes.to.execute OR -manifest.files.with.test.class.names.to.execute)
mvn compile exec:java -Dexec.mainClass="com.sforce.cd.apexUnit.ApexUnitRunner" -Dexec.args=" -org.login.url https://na14.salesforce.com -org.username email@example.com -org.password yourpassword-org.wide.code.coverage.threshold 75 -team.code.coverage.threshold 80 -org.client.id CLIENT_ID_FROM_CONNECTED_APP -org.client.secret CLIENT_SECRET_FROM_CONNECTED_APP -regex.for.selecting.test.classes.to.execute your_regular_exp1_for_test_classes,your_regular_exp2_for_test_classes -regex.for.selecting.source.classes.for.code.coverage.computation your_regular_exp1_for_source_classes,your_regular_exp2_for_source_classes -manifest.files.with.test.class.names.to.execute ManifestFile.txt -manifest.files.with.source.class.names.for.code.coverage.computation ClassManifestFile.txt -max.test.execution.time.threshold 10 -proxy.host your.proxy-if-required.net -proxy.port 8080"
Note: Multiple comma separated manifest files and regexes can be provided. Please do not include spaces while providing multiple regex or manifest files.
On successful completion - the command should indicate that your build succeeded and should generate two report files - ApexUnitReport.xml (This is the test report in JUnit format) and Report/ApexUnitReport.html (This is the code coverage report in html format)
Using Manifest files and Regexes
You can populate class names in the Manifest file and/or provide regular expressions(regexes) Please refer https://github.com/forcedotcom/ApexUnit/wiki/Manifest-file-vs-regex for the usecases where manifest file(s) and regex(es) option can be used
Use src/main/resources/config.properties to set the below parameters.
API_VERSION(Default value: 37.0) : The Partner API version in use for the org.
MAX_TIME_OUT_IN_MS(Default value : 1200000 ==> 20 minutes) : Time out setting for the session, Once timeout occurs, session renewer module is invoked which renews the session. Helpful when you face a connection exception during query executions.
Integrating with CI pipeline
CI engines like Jenkins(https://jenkins-ci.org/) can be used to seamlessly integrate ApexUnit with CI pipelines. Please find the details here: https://github.com/forcedotcom/ApexUnit/wiki/Integrating-with-CI-pipeline