# Deployment & Testing Guide

Quick reference for deploying the Salesforce Composite Envelope Builder to your org and running tests.

> **Shell Note:** Commands below show both **Bash/WSL** and **PowerShell** variants for Windows Terminal. Choose the one that matches your environment. The `sf` CLI commands are identical across both shells.

---

## Quick Start (Recommended)

### Deploy + Test in One Script

**Bash/WSL:**
```bash
cd /home/paulh/.openclaw/workspace/projects/salesforce-composite-envelope-builder/composite-envelope-builder
bash deploy-to-dev-org.sh
```

**PowerShell (Windows Terminal):**
```powershell
cd "$env:USERPROFILE\.openclaw\workspace\projects\salesforce-composite-envelope-builder\composite-envelope-builder"
bash deploy-to-dev-org.sh
# Or if you prefer native PowerShell (not WSL):
# .\deploy-to-dev-org.sh  (requires WSL bash available)
```

This script handles:
- ✅ Org authorization (opens browser login)
- ✅ Code deployment
- ✅ Unit test execution with code coverage
- ✅ Human-readable results

---

## Manual Commands

### 1. Authorize Your Org (First Time Only)

**Bash/WSL:**
```bash
# For Developer Edition
sf org login web --alias dev-org --instance-url https://login.salesforce.com

# For Sandbox
sf org login web --alias sandbox-org --instance-url https://test.salesforce.com
```

**PowerShell (Windows Terminal):**
```powershell
# For Developer Edition
sf org login web --alias dev-org --instance-url https://login.salesforce.com

# For Sandbox
sf org login web --alias sandbox-org --instance-url https://test.salesforce.com
```

You'll be redirected to Salesforce login. Once authorized, the org alias is saved for future deploys.

---

### 2. Deploy Code

**Bash/WSL:**
```bash
cd /home/paulh/.openclaw/workspace/projects/salesforce-composite-envelope-builder/composite-envelope-builder
sf project deploy start --target-org dev-org
```

**PowerShell (Windows Terminal):**
```powershell
cd "$env:USERPROFILE\.openclaw\workspace\projects\salesforce-composite-envelope-builder\composite-envelope-builder"
sf project deploy start --target-org dev-org
```

**Options:**
- `--target-org dev-org` — Use the authorized org alias (replace with your alias if different)
- `--wait 10` — Wait up to 10 minutes for deployment to complete

---

### 3. Run Tests

**Run ALL unit tests with code coverage:**

Bash/WSL:
```bash
sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

PowerShell:
```powershell
sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

---

**Run ONLY the new handler tests:**

Bash/WSL:
```bash
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --wait 10 --result-format human --target-org dev-org
```

PowerShell:
```powershell
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --wait 10 --result-format human --target-org dev-org
```

---

**Run specific test methods:**

Bash/WSL:
```bash
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --method-names testValidateRequest_Success --wait 10 --result-format human --target-org dev-org
```

PowerShell:
```powershell
sf apex run test --class-names DocusignEnvelopeRequestHandlerTest --method-names testValidateRequest_Success --wait 10 --result-format human --target-org dev-org
```

---

**Run ALL tests with JSON output (for parsing):**

Bash/WSL:
```bash
sf apex run test --wait 10 --result-format json --code-coverage --target-org dev-org > test-results.json
```

PowerShell:
```powershell
sf apex run test --wait 10 --result-format json --code-coverage --target-org dev-org | Out-File -FilePath test-results.json
```

---

## Complete Deploy + Test in One Command

**Bash/WSL:**
```bash
cd /home/paulh/.openclaw/workspace/projects/salesforce-composite-envelope-builder/composite-envelope-builder && \
sf project deploy start --target-org dev-org && \
sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

**PowerShell (Windows Terminal):**
```powershell
cd "$env:USERPROFILE\.openclaw\workspace\projects\salesforce-composite-envelope-builder\composite-envelope-builder"; `
sf project deploy start --target-org dev-org; `
sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

**Alternative PowerShell (using semicolons):**
```powershell
cd "$env:USERPROFILE\.openclaw\workspace\projects\salesforce-composite-envelope-builder\composite-envelope-builder"; sf project deploy start --target-org dev-org; sf apex run test --wait 10 --result-format human --code-coverage --target-org dev-org
```

---

## Understanding Test Results

Sample output:
```
Apex Tests
═════════════════════════════════════════════════════════════════

Test Results Summary  [Included Code Coverage]
═════════════════════════════════════════════════════════════════
Outcome: Passed
Tests Ran: 39
Passes: 39
Failures: 0
Skipped: 0
Pass Rate: 100%
Apex Code Coverage: 92%
```

**Key metrics:**
- **Pass Rate** — Percentage of tests that passed (should be 100%)
- **Apex Code Coverage** — Percentage of code executed by tests (should be >80%)
- **Failures** — If > 0, review the failed test names and error messages below

---

## Post-Deployment Setup

After successful deployment, configure your Salesforce org:

### 1. Create Docusign Configuration Custom Setting

1. Log into your Salesforce org
2. Go to **Setup** → **Custom Settings**
3. Click **Manage** next to **Docusign Configuration**
4. Click **New**
5. Fill in:
   - **Account Id:** `{your Docusign sandbox account ID}`
   - **Base URL:** `callout:DocusignAPI`
6. Click **Save**

### 2. Create Named Credential for Docusign API

1. Go to **Setup** → **Named Credentials**
2. Click **New Named Credential**
3. Fill in:
   - **Name:** `DocusignAPI`
   - **Label:** `Docusign API`
   - **URL:** `https://demo.docusign.net/restapi/v2.1`
   - **Identity Type:** Named Principal
   - **Authentication Protocol:** OAuth 2.0
   - **Authentication Provider:** DocusignOAuthProvider (if available)
4. Click **Save**

### 3. Update Your Screen Flow

1. Go to **Flow Builder**
2. Create or edit your Screen Flow
3. Add an **Action** to the flow:
   - Action: **Send Composite Docusign Envelope**
   - Input Variables:
     - **Template IDs** — Comma-separated Docusign template IDs
     - **Salesforce Record ID** — {!Record.Id}
     - **Language** — en or es
     - **Email Subject** — Optional custom subject
4. Output Variables:
   - **Envelope ID** — Unique Docusign envelope ID
   - **Success** — Boolean (true/false)
   - **Error Message** — Error details if creation failed
5. Save and test the flow

---

## Troubleshooting

### Authorization Issues

**Bash/WSL:**
```bash
# If auth fails, try manual URL method:
sf org login web --alias dev-org --instance-url https://login.salesforce.com --json

# Copy the 'url' value and paste into your browser
```

**PowerShell:**
```powershell
# If auth fails, try manual URL method:
sf org login web --alias dev-org --instance-url https://login.salesforce.com --json

# Copy the 'url' value from the output and paste into your browser
```

---

### Deployment Errors

**Bash/WSL:**
```bash
# Check what's in your org
sf project list metadata --target-org dev-org

# Validate without deploying
sf project validate deploy --target-org dev-org
```

**PowerShell:**
```powershell
# Check what's in your org
sf project list metadata --target-org dev-org

# Validate without deploying
sf project validate deploy --target-org dev-org
```

---

### Test Failures

**Bash/WSL:**
```bash
# Run tests with verbose output
sf apex run test --target-org dev-org --result-format human --code-coverage -v
```

**PowerShell:**
```powershell
# Run tests with verbose output
sf apex run test --target-org dev-org --result-format human --code-coverage -v
```

---

## Reference: Classes Deployed

**Apex Classes:**
- `DocusignCompositeEnvelopeBuilder` — Main invocable class (Flows)
- `DocusignEnvelopeRequestHandler` — Request validation & envelope building (reusable)
- `DocusignAPIService` — Docusign REST API wrapper
- `DocusignCredentials` — Custom settings singleton

**Test Classes:**
- `DocusignCompositeEnvelopeBuilderTest` — Tests for main invocable
- `DocusignEnvelopeRequestHandlerTest` — Tests for request handler (10 test methods)
- `DocusignAPIServiceTest` — Tests for API service
- `DocusignCredentialsTest` — Tests for credentials

**Custom Settings:**
- `Docusign_Configuration__c` — Stores Account ID and Base URL

---

## Next Steps After Successful Deploy

1. ✅ Verify all tests pass
2. ✅ Create Docusign Configuration in Salesforce
3. ✅ Set up Named Credential
4. ✅ Create a test Screen Flow
5. ✅ Test with real Docusign templates
6. ✅ Deploy to Production (when ready)

---

For more details, see:
- `docs/deployment-guide.md` — Detailed deployment instructions
- `docs/api-reference.md` — API reference
- `docs/design.md` — Architecture & design decisions