Playforce

Playforce is a lightweight Node.js library for accessing the Salesforce REST API

It is built with a focus on strong typing, developer ergonomics, and Playwright test automation.

Designed for seamless use with the Playwright test framework.

Playforce is a licensed product, but has a Free tier available for unlimited use.

See Get Playforce for more information

Feature Summary

Playforce is a strongly-typed utility library for interacting with Salesforce objects in a robust and developer-friendly way. Key features include:

• OAuth2-based Authentication
  Simple integration with Salesforce services using secure, standards-based auth.

• Strong Typing
  Full TypeScript support for Salesforce objects like Contact, Lead, etc.

• Salesforce Object Type Generation
  Automatically generate strongly-typed object definition files from your Salesforce schema.

• Intelligent Queries
  Use SOQL, direct field references, and conditional logic to retrieve data.

• Robust CRUD Operations
  Seamless create, read, update, and delete operations for standard and custom objects.

• Wait-for-condition Variants
  Built-in polling logic to wait for data consistency in asynchronous environments.

• Negative Case Handling
  Helper methods and assertions for testing invalid or unexpected behaviors.

• Developer Experience Focus
  Clean API, clear naming conventions, and first-class TypeScript integration.

Setup Playforce

1. Installation

npm install playforce

2. Obtain your Playforce License

Playforce is a licensed product, but has a Free tier available for unlimited use.

Go to Get Playforce to get your Free site license.

4. Set Environment Variables

Configure the required environment variables either directly in your shell or by adding them to a .env file in your project root (if your setup supports it).

| Variable | Description | Required | |-----------------------------|---------------------------------------|------------| | SALESFORCE_TOKEN_URL | The OAuth token endpoint URL | Yes | | SALESFORCE_CONSUMER_KEY | Your Salesforce OAuth client ID | Yes | | SALESFORCE_CONSUMER_SECRET | Your Salesforce OAuth client secret | Yes | | SALESFORCE_API_VERSION | Optional override. Default will be what Salesforce returns | No | | PLAYFORCE_LICENSE | Your Playforce license from Get Playforce | Yes |

To create the necessary OAuth credentials, see the Create a Connected App section in the Salesforce Agent API Getting Started Guide.

Go to Get Playforce for more setup information.

4. Create Playwright Global Setup

Create a file named global-setup.ts in your project root and add the following code:

// global-setup.ts
import { FullConfig } from "@playwright/test";
import { getSalesforceToken } from "playforce";

export default async function globalSetup(config: FullConfig) {
  await getSalesforceToken();  
}

In your playwright.config.ts, add the following to include the global setup script:

export default defineConfig({
  globalSetup: ['./global-setup'],
  // ... other settings
});

Generating Salesforce Object Interfaces for Strong Typing

To generate TypeScript interfaces from Salesforce object metadata, create the following Playwright test spec file and run it as a Playwright 'test':

// tests/get-salesforce-objects.spec
import test from "@playwright/test";
import { generateSalesforceObjects } from 'playforce';

test.describe('Generate Salesforce Object Typed Interfaces & API files', () => {
  test('Generate Salesforce Object Typed Interfaces & API files', async ({}, testInfo) => {

    const objects = [
      'Account',
      'Case',
      'Contact',
      'Custom_Object__c',
      'Project__c',
    ];  

    //This will generate your typed interface files and APIs in /requests/
    await Playforce.generateSalesforceObjects(objects, testInfo.config.rootDir)
    
  });
});

Coding Examples

const newContactData: Contact = {
  LastName: "Last Name",
  FirstName: "First Name",
  Email: email,
};

let contact = await SalesforceRequests.Contact.createAndGetObject(newContactData);

contact = await SalesforceRequests.Contact.getObjectById(contact.Id);
contact = await SalesforceRequests.Contact.getObjectByField(Contact.Email, email);
contact = await SalesforceRequests.Contact.getObjectWhenField(Contact.Email, email)
contact = await SalesforceRequests.Contact.getObjectByWhere(`email = '${email}'`);
contact = await SalesforceRequests.Contact.getObjectWhenWhere(`email = '${email}'`);

contact = await SalesforceRequests.Contact.getThisObjectWhenField(contact, Contact.Email, contact.Email);
contact = await SalesforceRequests.Contact.getThisObjectWhenFieldNOTNull(contact, Contact.Email);
contact = await SalesforceRequests.Contact.getThisObjectWhenFieldNull(contact, Contact.Fax);
contact = await SalesforceRequests.Contact.getThisObjectWhenFieldNOTEqualsValue(contact, Contact.Email, '[email protected]');

contact = await SalesforceRequests.Contact.updateAndGetObject(contact.Id, updateContactData);

await SalesforceRequests.Contact.getObjectArrayByField(Contact.Email, contact.Email);
await SalesforceRequests.Contact.getObjectArrayByWhere(`email = '${email}'`);

await SalesforceRequests.Contact.ensureNoObjectExistsById("NOTANEXISTINGID");
await SalesforceRequests.Contact.ensureNoObjectExistsByField(Contact.Email, '[email protected]');
await SalesforceRequests.Contact.ensureNoObjectExistsByWhere(`email = '[email protected]'`);

await SalesforceRequests.Contact.deleteObjectById(contact.Id);