@salesforce/core

What is @salesforce/core?

@salesforce/core is a powerful npm package designed to facilitate interaction with Salesforce's APIs and services. It provides a set of tools and utilities for managing Salesforce authentication, configuration, and API requests, making it easier for developers to build and manage Salesforce applications.

What are @salesforce/core's main functionalities?

Authentication

This feature allows you to authenticate to a Salesforce org using a username. The code sample demonstrates how to create an AuthInfo object and establish a connection to Salesforce.

const { AuthInfo } = require('@salesforce/core');

async function authenticate() {
  const authInfo = await AuthInfo.create({ username: 'your-username' });
  const connection = await authInfo.getConnection();
  console.log('Authenticated to Salesforce:', connection.instanceUrl);
}
authenticate();

Configuration Management

This feature provides tools for managing and retrieving Salesforce configuration settings. The code sample shows how to create a ConfigAggregator and retrieve the current configuration.

const { ConfigAggregator } = require('@salesforce/core');

async function getConfig() {
  const configAggregator = await ConfigAggregator.create();
  const config = configAggregator.getConfig();
  console.log('Salesforce Configuration:', config);
}
getConfig();

API Requests

This feature allows you to make API requests to Salesforce. The code sample demonstrates how to create a connection and perform a SOQL query to retrieve data from Salesforce.

const { Connection } = require('@salesforce/core');

async function querySalesforce() {
  const connection = await Connection.create({ authInfo: await AuthInfo.create({ username: 'your-username' }) });
  const result = await connection.query('SELECT Id, Name FROM Account');
  console.log('Query Result:', result.records);
}
querySalesforce();

Other packages similar to @salesforce/core

jsforce

Jsforce is a popular library for interacting with Salesforce APIs. It provides a comprehensive set of features for authentication, CRUD operations, and more. Compared to @salesforce/core, jsforce offers a more extensive set of functionalities and is widely used in the Salesforce developer community.

nforce

Nforce is another library for working with Salesforce APIs. It focuses on providing a simple and intuitive interface for performing CRUD operations and managing authentication. While it may not be as feature-rich as @salesforce/core, it is known for its ease of use and simplicity.

README

Description

The @salesforce/core library provides client-side management of Salesforce DX projects, org authentication, connections to Salesforce APIs, and other utilities. Much of the core functionality that powers the Salesforcedx plug-ins comes from this library. You can use this functionality in your plug-ins, too.

Usage

See the API documentation.

Contributing

If you are interested in contributing, please take a look at the CONTRIBUTING guide.

Related Docs and Repositories

• @salesforce/command - Contains base Salesforce CLI command, SfdxCommand.
• @salesforce/plugin-generator - The generator plug-in for building plug-ins for Salesforce CLI.

Using TestSetup

The Salesforce DX Core Library provides a unit testing utility to help with mocking and sand-boxing core components. This feature allows unit tests to execute without needing to make API calls to salesforce.com.

Mocking AuthInfo

Here you can mock authorization for a Salesforce scratch org.

import { strictEqual } from 'assert';
import { MockTestOrgData, testSetup } from '@salesforce/core/lib/testSetup';
import { AuthInfo } from '@salesforce/core';

const $$ = testSetup();

describe('Mocking Auth data', () => {
  it('example', async () => {
    const testData = new MockTestOrgData();
    $$.setConfigStubContents('AuthInfoConfig', {
      contents: await testData.getConfig()
    });
    const auth: AuthInfo = await AuthInfo.create({ username: testData.username });
    strictEqual(auth.getUsername(), testData.username);
  });
});

After having a valid AuthInfo object you can then create fake connections to a Salesforce.com scratch org. This allows for writing tests that can validate result responses for SOQL queries and REST endpoints.

import { AuthInfo, Connection, SfdxError } from '@salesforce/core';
import { MockTestOrgData, testSetup } from '@salesforce/core/lib/testSetup';
import { AnyJson, ensureJsonMap, JsonMap } from '@salesforce/ts-types';
import { ensureString } from '@salesforce/ts-types';
import { deepStrictEqual } from 'assert';
import { QueryResult } from 'jsforce';

const $$ = testSetup();

describe('Mocking a force server call', () => {
  it('example', async () => {
    const records: AnyJson = { records: ['123456', '234567'] };
    const testData = new MockTestOrgData();
    $$.setConfigStubContents('AuthInfoConfig', {
      contents: await testData.getConfig()
    });
    $$.fakeConnectionRequest = (request: AnyJson): Promise<AnyJson> => {
      const _request: JsonMap = ensureJsonMap(request);
      if (request && ensureString(_request.url).includes('Account')) {
        return Promise.resolve(records);
      } else {
        return Promise.reject(new SfdxError(`Unexpected request: ${_request.url}`));
      }
    };
    const connection: Connection = await Connection.create({
      authInfo: await AuthInfo.create({ username: testData.username })
    });
    const result: QueryResult<{}> = await connection.query('select Id From Account');
    deepStrictEqual(result, records);
  });
});

Using the Built-in Sinon Sandboxes

sfdx-core uses Sinon as its underlying mocking system. If you're unfamiliar with Sinon and it's sandboxing concept you can find more information here: https://sinonjs.org/ Sinon stubs and spys must be cleaned up after test invocations. To ease the use of Sinon with sfdx core we've exposed our sandbox in TestSetup. After adding your own stubs and/or spys they will automatically be cleaned up after each test using mocha's afterEach method.

import { strictEqual } from 'assert';

import { testSetup } from '@salesforce/core/lib/testSetup';
import * as os from 'os';

const $$ = testSetup();

describe('Using the built in Sinon sandbox.', () => {
  it('example', async () => {
    const unsupportedOS = 'LEO';
    $$.SANDBOX.stub(os, 'platform').returns(unsupportedOS);
    strictEqual(os.platform(), unsupportedOS);
  });
});

Testing Expected Failures

It's important to have negative tests that ensure proper error handling. With shouldThrow it's easy to test for expected async rejections.

import { SfdxError } from '@salesforce/core';
import { shouldThrow } from '@salesforce/core/lib/testSetup';
import { strictEqual } from 'assert';

class TestObject {
  public static async method() {
    throw new SfdxError('Error', 'ExpectedError');
  }
}

describe('Testing for expected errors', () => {
  it('example', async () => {
    try {
      await shouldThrow(TestObject.method());
    } catch (e) {
      strictEqual(e.name, 'ExpectedError');
    }
  });
});

Testing Log Lines

It's also useful to check expected values and content from log lines. TestSetup configures the sfdx-core logger to use an in memory LogLine storage structure. These can be easily accessed from tests.

import { Logger, LogLine } from '@salesforce/core';
import { testSetup } from '@salesforce/core/lib/testSetup';
import { strictEqual } from 'assert';

const $$ = testSetup();

const TEST_STRING = 'foo was here';

class TestObject {
  constructor(private logger: Logger) {
    this.logger = logger.child('TestObject');
  }

  public method() {
    this.logger.error(TEST_STRING);
  }
}

describe('Testing log lines', () => {
  it('example', async () => {
    const obj: TestObject = new TestObject($$.TEST_LOGGER);
    obj.method();
    const records: LogLine[] = $$.TEST_LOGGER.getBufferedRecords();
    strictEqual(records.length, 1);
    strictEqual(records[0].msg, TEST_STRING);
  });
});