> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/salesforce-apex

Test and deploy APEX applications to Salesforce. This is a wrapper around the circleci/salesforce-sfdx orb which provides commonly used defaults - It's recommend to use the sfdx orb alongside this one if you require more flexibility.


## Commands

### mdapi-deploy

'Deploy MDAPI data.'


| Parameter | Type | Default | Description |
|---|---|---|---|
| `checkonly` | boolean | false | Validate deploy, but don't save to org. |
| `deploy-dir` | string |  | Deploy directory containing metadata. |
| `deploy-zip` | string |  | Deploy zip file containing metadata. |
| `scratch-alias` | string |  | The alias of the scratch Org. |
| `wait-time` | integer | -1 | Maximum amount of time to complete deployment. |

### scratch-down

Removes a scratch organization.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `scratch-alias` | string |  | The alias of the scratch Org. |

### scratch-up

Creates a scratch organization and opens it in the default browser (if available). Also provides a link to open the organization in your own browser.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `overrides` | string |  | Overrides for scratch organization. |
| `scratch-alias` | string |  | The alias of the scratch Org. |
| `scratch-config` | string |  | The scratch JSON definition. |

### setup

Install CLI and autheticate with SFDC using CLI orb. This assumes some defaults, and requires the SFDX_JWT_KEY and SFDX_CONSUMER_KEY enviornment variables to be set to function. If you need more control over authentication with Salesforce, consider using the sfdx Orb's auth command directly.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `defaultusername` | string |  | Username for an organization that all commands will run against. |
| `version` | string |  | CLI version to install. Leave blank for latest. |

### source-push

Pushes the APEX application to the scratch org and sets up mock data & permission sets.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `force` | boolean | false | Force overwriting scratch org and deploy even if warnings are present. |
| `permset` | string |  | Permissions set to assign to the user for the organization. |
| `sample-data` | string |  | Path to sample data for the organization. |
| `scratch-alias` | string |  | The name of the scratch Org, can either be the alias or target username. |

### test

Run unit tests for an APEX application with improved code coverage. Automatically stores the test results under the "Artifacts" and "Test Results" tabs.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `result-format` | string | junit | Format results should be returned as - defaults to junit, can be one of human, tap, junit or json. |
| `scratch-alias` | string |  | The alias of the scratch Org. |
| `test-result-output` | string | /tmp/apex-test-results | Directory to save test results to. |
| `wait-time` | integer | 10 | Maximum amount of time to complete tests. |

## Jobs

### scratch-deploy-and-test

An opinionated automation job for deploying your salesforce application to a scratch organization, executing apex unit testing, and finally removing the scratch org. Check this job's source for the full list of commands ran.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cli-version` | string |  | By default, the latest version of the standalone CLI will be installed. To install via npm, supply a version tag such as "latest" or "6". |
| `defaultusername` | string |  | The username for an org that all commands run against by default. |
| `deploydir` | string |  | The root of the directory tree that contains the files to deploy. The root must contain a valid package.xml file describing the entities in the directory structure. |
| `mdapi-wait-time` | integer | -1 | Maximum amount of time to complete mdapi deployment. |
| `permset` | string |  | Assign a pre-defined permission set to the default user. Learn more: https://help.salesforce.com/articleView?id=perm_sets_create.htm&type=5 |
| `sampledata-path` | string |  | Path location to sample data json file. Example: ./data/sample-data-plan.json |
| `scratch-alias` | string |  | Sets an alias for the scratch org to ensure commands are run against the correct org. |
| `scratch-def` | string |  | Full path to scratch org definition json file. Example:'./config/project-scratch-def.json' |
| `tag` | string | 12.6 | Version tag for the SFDX executor. |
| `test-wait-time` | integer | 10 | Maximum amount of time to complete tests. |

## Examples

### scratch-deploy-and-test

Simple example showing how to install the CLI, authenticate and test against a scratch org.


```yaml
orbs:
  apex: circleci/salesforce-apex@x.y
version: 2.1
workflows:
  deploy_test:
    jobs:
      - apex/scratch-deploy-and-test:
          defaultusername: circleci
          deploydir: ./src
          permset: circleci
          sampledata-path: ./sampledata
          scratch-alias: circleci
          scratch-def: ./config/project-scratch-def.json
```

### setup-environment

Example showing how to set up the CLI and authenticate with SFDC with the Apex Orb.


```yaml
jobs:
  install_autheticate:
    docker:
      - image: cimg/node:12.6
    steps:
      - apex/setup:
          defaultusername: sample@email.com
orbs:
  apex: circleci/salesforce-apex@x.y
version: 2.1
workflows:
  basic_test:
    jobs:
      - install_authenticate
```