Skip to content
This repository has been archived by the owner on Feb 12, 2022. It is now read-only.

Latest commit

 

History

History
122 lines (102 loc) · 10.1 KB

README.md

File metadata and controls

122 lines (102 loc) · 10.1 KB
Raw

Build Status ApexUnit

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

Pre-Requisites

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 "username=*yourusername@yourdomain.com*" -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

Required parameters:

  • -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.

Optional Parameters:

  • -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)

Sample command:

mvn compile exec:java -Dexec.mainClass="com.sforce.cd.apexUnit.ApexUnitRunner" -Dexec.args=" -org.login.url https://na14.salesforce.com -org.username yourusername@salesforce.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

#Addional options

Use src/main/resources/config.properties to set the below parameters.

  1. API_VERSION(Default value: 37.0) : The Partner API version in use for the org.

  2. 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

How to contribute or track Bug/Issue for ApexUnit?

https://github.com/forcedotcom/ApexUnit/wiki/Contribution-and-Bug-Issue-tracking

Questions/Feedback?

https://github.com/forcedotcom/ApexUnit/wiki/Contact-info