# Getting Started with aer

aer lets you execute Apex tests locally without waiting on a Salesforce deploy. This guide walks through a basic project and then layers in package and data dependencies so you can reuse the same workflow across your portfolio.

## Install

If you use [Homebrew](https://brew.sh/), install aer with:

```bash
brew install octoberswimmer/tap/aer
```

Otherwise, download the latest version of aer from the [releases page](https://github.com/octoberswimmer/aer-dist/releases).

## Hello World

Run anonymous Apex locally with `aer exec`:

```bash
aer exec <<APEX
Account a = new Account(Name = 'Hello World');
insert a;
Account result = [SELECT Name FROM Account WHERE Id = :a.Id];
System.debug(result.Name);
APEX
```

```text
DEBUG | Hello World
```

`aer exec` executes anonymous Apex in an in-memory environment with standard objects already available, so you can experiment with DML and SOQL without any setup or org connection.

## Quick Start: Local Apex Project

Most teams keep their code in Salesforce DX (source) format under `force-app/main/default`. The example below uses an Apex package named `ossc`, but the structure matches what you see in any SFDX project:

```text
force-app/
└── main/
    └── default/
        ├── classes/
        │   ├── Address.cls
        │   ├── Address_Test.cls
        │   ├── AgeService.cls
        │   └── ...additional Apex classes and tests
        └── objects/
            └── ShipCompliant_API__c.object
                └── fields/
                    ├── CoreService_Endpoint__c.field-meta.xml
                    ├── Password__c.field-meta.xml
                    └── Username__c.field-meta.xml
```

Run your first test sweep from the project root:

```bash
cd path/to/ossc
aer test force-app/main/default
```

`aer test` builds a schema automatically by scanning the metadata in the directories you supply. The schema lives in memory for that run, so there is nothing to clean up afterward. You can pass multiple source directories when your project splits code across several paths:

```bash
aer test force-app/main/default force-app/extra/default
```

Working with a legacy Metadata API layout? Point `aer` at the `src/` directory instead—the tooling handles both formats:

```bash
# Classic metadata format
aer test src
```

The remaining examples use `force-app/main/default` for consistency. If your project still uses the classic metadata layout, substitute `src` in each command.

## Load First-Party Packages

Many teams split shared Apex into separate repositories. If you have the source for those dependencies available locally (for example, an `oslog` logging package that sits next to your ShipCompliant project), convert them into packages once and reuse them across every test run:

```bash
cd path/to/ossc
mkdir -p packages

cd ../oslog

aer package create \
  --output ../ossc/packages/oslog.pkg \
  force-app/main/default

cd ../ossc
aer test force-app/main/default --package packages/oslog.pkg
```

- `aer package create` runs inside the `oslog` repository and scans its metadata, so the package lines up with the source code.
- Packages load straight from disk—you never need to install them in an org—which keeps integration logic intact.
- Adjust the source path (`../oslog/force-app/main/default`) to match your dependency’s layout; point to `../oslog/src` for metadata projects.
- Add more packages with additional `--package` flags or keep everything under `packages/` and point to the directory:

```bash
aer test force-app/main/default --package-dir ./packages
```

## Load Third-Party Packages

Managed packages you cannot build locally still fit into the workflow. Use `aer package mock` to snapshot the metadata from an org where the package is already installed. The example below captures the `dlrs` namespace from a sandbox and runs tests with both first-party and third-party code:

```bash
# Export the managed package once
aer package mock dlrs \
  --account your.name@example.com \
  --output packages/dlrs.pkg

# Run tests with all package dependencies
aer test force-app/main/default \
  --package packages/oslog.pkg \
  --package packages/dlrs.pkg
```

Want a deeper walkthrough? See [Mock Managed Package Classes →](/content/tools/aer/docs/mock-managed-package-classes/index.html) for a step-by-step example that stubs `oslog.Log` inside a mocked package.

When you have several `.pkg` files, place them in a shared folder and load them in bulk:

```bash
aer test force-app/main/default --package-dir ./packages
```

Each package executes in its own namespace, so components do not conflict unless two archives target the same namespace. Loading multiple packages for a single namespace is not supported today. `.pkg` files are binary, but they can still be checked into source control so your CI environment can reuse them. The `--account` flag accepts usernames from both the Force CLI and the newer `sf`/`sfdx` authentication stores—use whichever tool already has a session for your sandbox.

## Bring In Setup Data

Some tests require seed data such as `OrgWideEmailAddress` records or reference tables that are not stored in source. `aer` supports two approaches: point tests at a SQLite database that already contains the records you need, or generate that database on demand and keep it in sync with your org.

### Seed from an external SQLite snapshot

When you want to pull in records maintained outside of `aer`, use `--bootstrap-db` to copy data from another SQLite file into the test database before execution. For example, capture the `OrgWideEmailAddress` table with the `ro` CLI and hand it to `aer`:

```bash
ro -D bootstrap.db OrgWideEmailAddress

aer test force-app/main/default \
  --bootstrap-db bootstrap.db \
  --bootstrap-tables OrgWideEmailAddress
```

Leave `--bootstrap-tables` unset to copy every table from the bootstrap database, or repeat `--bootstrap-tables` for each table you want to include. The bootstrap file is read-only; `aer` copies the data into its own in-memory database and never modifies the source file.

With packages and data dialed in, `aer` delivers production-faithful Apex tests that run in seconds on your laptop. Extend the setup as your dependencies grow, check in the configuration, and the whole team—including CI—benefits from fast, dependable feedback.

## Next Steps

For more details, see the [full aer documentation](/content/tools/aer/docs/index.html).