@salesforce/core 3.21.6 → 3.22.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [3.22.0](https://github.com/forcedotcom/sfdx-core/compare/v3.21.6...v3.22.0) (2022-06-23)
+
+### Features
+
+- modify uniqid to accept length and template ([#604](https://github.com/forcedotcom/sfdx-core/issues/604)) ([1fd1b5c](https://github.com/forcedotcom/sfdx-core/commit/1fd1b5c40ab7f9b4d66eada94f3ecfa149b263b7))
+
 ### [3.21.6](https://github.com/forcedotcom/sfdx-core/compare/v3.21.5...v3.21.6) (2022-06-23)
 
 ### [3.21.5](https://github.com/forcedotcom/sfdx-core/compare/v3.21.4...v3.21.5) (2022-06-23)

package/README.md

@@ -1,9 +1,19 @@
 [![NPM](https://img.shields.io/npm/v/@salesforce/core.svg)](https://www.npmjs.com/package/@salesforce/core)
 [![CircleCI](https://circleci.com/gh/forcedotcom/sfdx-core.svg?style=svg&circle-token=2377ca31221869e9d13448313620486da80e595f)](https://circleci.com/gh/forcedotcom/sfdx-core)
 
+- [Description](#description)
+- [Usage](#usage)
+  - [Contributing](#contributing)
+- [Using TestSetup](#using-testsetup)
+  - [Mocking Authorizations](#mocking-authorizations)
+  - [Mocking Config Files](#mocking-config-files)
+  - [Using the Built-in Sinon Sandboxes](#using-the-built-in-sinon-sandboxes)
+  - [Testing Expected Failures](#testing-expected-failures)
+  - [Testing Log Lines](#testing-log-lines)
+
 # 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.
+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 Salesforce CLI plugins comes from this library. You can use this functionality in your plugins too.
 
 # Usage
 
@@ -13,16 +23,11 @@ See the [API documentation](https://forcedotcom.github.io/sfdx-core/).
 
 If you are interested in contributing, please take a look at the [CONTRIBUTING](CONTRIBUTING.md) guide.
 
-# Related Docs and Repositories
-
-- [@salesforce/command](https://github.com/forcedotcom/cli-packages/tree/main/packages/command) - Contains base Salesforce CLI command, `SfdxCommand`.
-- [@salesforce/plugin-generator](https://github.com/forcedotcom/sfdx-plugin-generate) - 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
+## Mocking Authorizations
 
 Here you can mock authorization for a Salesforce scratch org.
 
@@ -77,6 +82,43 @@ describe('Mocking a force server call', () => {
 });
 ```
 
+## Mocking Config Files
+
+You can mock the contents of various config files
+
+```typescript
+import { strictEqual } from 'assert';
+import { MockTestOrgData, testSetup } from '@salesforce/core/lib/testSetup';
+import { StateAggregator, OrgConfigProperties } from '@salesforce/core';
+
+const $$ = testSetup();
+
+describe('Mocking Aliases', () => {
+  it('example', async () => {
+    const testData = new MockTestOrgData();
+    await $$.stubAliases({ myAlias: testData.username });
+    const alias = (await StateAggregator.getInstance()).aliases.get(testData.username);
+    strictEqual(alias, 'myAlais');
+  });
+});
+
+describe('Mocking Config', () => {
+  it('example', async () => {
+    const testData = new MockTestOrgData();
+    await $$.stubConfig({ [OrgConfigProperties.TARGET_ORG]: testData.username });
+    const {value} = (await ConfigAggregator.create()).getInfo(OrgConfigProperties.TARGET_ORG);
+    strictEqual(value, testData.username);
+  });
+});
+
+describe('Mocking Arbitrary Config Files', () => {
+  it('example', async () => {
+    // MyConfigFile must extend the ConfigFile class in order for this to work properly.
+    $$.setConfigStubContents('MyConfigFile', { contents: { foo: 'bar' } });
+  });
+});
+```
+
 ## 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:
@@ -126,6 +168,30 @@ describe('Testing for expected errors', () => {
 });
 ```
 
+You can also use `shouldThrowSync` for syncrhonous functions you expect to fail
+
+```typescript
+import { SfError } from '@salesforce/core';
+import { shouldThrowSync } from '@salesforce/core/lib/testSetup';
+import { strictEqual } from 'assert';
+
+class TestObject {
+  public static method() {
+    throw new SfError('Error', 'ExpectedError');
+  }
+}
+
+describe('Testing for expected errors', () => {
+  it('example', async () => {
+    try {
+      shouldThrowSync(() => 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.
@@ -151,9 +217,9 @@ class TestObject {
 
 describe('Testing log lines', () => {
   it('example', async () => {
-    const obj: TestObject = new TestObject($$.TEST_LOGGER);
+    const obj = new TestObject($$.TEST_LOGGER);
     obj.method();
-    const records: LogLine[] = $$.TEST_LOGGER.getBufferedRecords();
+    const records = $$.TEST_LOGGER.getBufferedRecords();
     strictEqual(records.length, 1);
     strictEqual(records[0].msg, TEST_STRING);
   });

package/lib/exported.d.ts

@@ -2,8 +2,8 @@ export { OAuth2Config } from 'jsforce';
 export { ConfigFile } from './config/configFile';
 export { TTLConfig } from './config/ttlConfig';
 export { envVars, EnvironmentVariable, SUPPORTED_ENV_VARS, EnvVars } from './config/envVars';
-export { BaseConfigStore, ConfigContents, ConfigEntry, ConfigStore, ConfigValue } from './config/configStore';
-export { GlobalInfo, SfEntry, SfInfo, SfInfoKeys, SfOrg, SfOrgs, SfToken, SfTokens, StateAggregator, } from './stateAggregator';
+export { ConfigContents, ConfigEntry, ConfigStore, ConfigValue } from './config/configStore';
+export { GlobalInfo, SfInfo, SfInfoKeys, SfOrg, SfOrgs, SfToken, SfTokens, StateAggregator } from './stateAggregator';
 export { DeviceOauthService, DeviceCodeResponse, DeviceCodePollingResponse } from './deviceOauthService';
 export { OrgUsersConfig } from './config/orgUsersConfig';
 export { ConfigPropertyMeta, ConfigPropertyMetaInput, Config, SfdxPropertyKeys, SfConfigProperties, SFDX_ALLOWED_PROPERTIES, SF_ALLOWED_PROPERTIES, } from './config/config';

package/lib/exported.js

@@ -16,8 +16,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MyDomainResolver = exports.StreamingClient = exports.CometClient = exports.PollingClient = exports.SfdxError = exports.SfError = exports.SchemaValidator = exports.SchemaPrinter = exports.SfdxProjectJson = exports.SfdxProject = exports.SfProjectJson = exports.SfProject = exports.ORG_CONFIG_ALLOWED_PROPERTIES = exports.OrgConfigProperties = exports.OrgTypes = exports.SandboxEvents = exports.Org = exports.Messages = exports.Logger = exports.LoggerLevel = exports.getJwtAudienceUrl = exports.SfdcUrl = exports.WebOAuthServer = exports.Lifecycle = exports.Global = exports.Mode = exports.SFDX_HTTP_HEADERS = exports.Connection = exports.AuthRemover = exports.AuthInfo = exports.SfdxConfigAggregator = exports.ConfigAggregator = exports.SandboxRequestCache = exports.SF_ALLOWED_PROPERTIES = exports.SFDX_ALLOWED_PROPERTIES = exports.SfConfigProperties = exports.SfdxPropertyKeys = exports.Config = exports.OrgUsersConfig = exports.DeviceOauthService = exports.StateAggregator = exports.SfInfoKeys = exports.GlobalInfo = exports.BaseConfigStore = exports.EnvVars = exports.SUPPORTED_ENV_VARS = exports.EnvironmentVariable = exports.envVars = exports.TTLConfig = exports.ConfigFile = void 0;
-exports.ScratchOrgCache = exports.scratchOrgLifecycleStages = exports.scratchOrgLifecycleEventName = exports.scratchOrgResume = exports.scratchOrgCreate = exports.PermissionSetAssignment = exports.User = exports.REQUIRED_FIELDS = exports.DefaultUserFields = void 0;
+exports.DefaultUserFields = exports.MyDomainResolver = exports.StreamingClient = exports.CometClient = exports.PollingClient = exports.SfdxError = exports.SfError = exports.SchemaValidator = exports.SchemaPrinter = exports.SfdxProjectJson = exports.SfdxProject = exports.SfProjectJson = exports.SfProject = exports.ORG_CONFIG_ALLOWED_PROPERTIES = exports.OrgConfigProperties = exports.OrgTypes = exports.SandboxEvents = exports.Org = exports.Messages = exports.Logger = exports.LoggerLevel = exports.getJwtAudienceUrl = exports.SfdcUrl = exports.WebOAuthServer = exports.Lifecycle = exports.Global = exports.Mode = exports.SFDX_HTTP_HEADERS = exports.Connection = exports.AuthRemover = exports.AuthInfo = exports.SfdxConfigAggregator = exports.ConfigAggregator = exports.SandboxRequestCache = exports.SF_ALLOWED_PROPERTIES = exports.SFDX_ALLOWED_PROPERTIES = exports.SfConfigProperties = exports.SfdxPropertyKeys = exports.Config = exports.OrgUsersConfig = exports.DeviceOauthService = exports.StateAggregator = exports.SfInfoKeys = exports.GlobalInfo = exports.EnvVars = exports.SUPPORTED_ENV_VARS = exports.EnvironmentVariable = exports.envVars = exports.TTLConfig = exports.ConfigFile = void 0;
+exports.ScratchOrgCache = exports.scratchOrgLifecycleStages = exports.scratchOrgLifecycleEventName = exports.scratchOrgResume = exports.scratchOrgCreate = exports.PermissionSetAssignment = exports.User = exports.REQUIRED_FIELDS = void 0;
 const messages_1 = require("./messages");
 messages_1.Messages.importMessagesDirectory(__dirname);
 var configFile_1 = require("./config/configFile");
@@ -29,8 +29,6 @@ Object.defineProperty(exports, "envVars", { enumerable: true, get: function () {
 Object.defineProperty(exports, "EnvironmentVariable", { enumerable: true, get: function () { return envVars_1.EnvironmentVariable; } });
 Object.defineProperty(exports, "SUPPORTED_ENV_VARS", { enumerable: true, get: function () { return envVars_1.SUPPORTED_ENV_VARS; } });
 Object.defineProperty(exports, "EnvVars", { enumerable: true, get: function () { return envVars_1.EnvVars; } });
-var configStore_1 = require("./config/configStore");
-Object.defineProperty(exports, "BaseConfigStore", { enumerable: true, get: function () { return configStore_1.BaseConfigStore; } });
 var stateAggregator_1 = require("./stateAggregator");
 Object.defineProperty(exports, "GlobalInfo", { enumerable: true, get: function () { return stateAggregator_1.GlobalInfo; } });
 Object.defineProperty(exports, "SfInfoKeys", { enumerable: true, get: function () { return stateAggregator_1.SfInfoKeys; } });

package/lib/sfProject.js

@@ -68,13 +68,17 @@ class SfProjectJson extends configFile_1.ConfigFile {
         return contents;
     }
     async write(newContents) {
-        this.setContents(newContents);
+        if (newContents) {
+            this.setContents(newContents);
+        }
         this.validateKeys();
         await this.schemaValidate();
         return super.write();
     }
     writeSync(newContents) {
-        this.setContents(newContents);
+        if (newContents) {
+            this.setContents(newContents);
+        }
         this.validateKeys();
         this.schemaValidateSync();
         return super.writeSync();

package/lib/testSetup.d.ts

@@ -164,14 +164,45 @@ export interface TestContext {
      * @param value The actual stub contents. The Mock data.
      */
     setConfigStubContents(name: string, value: ConfigContents): void;
+    /**
+     * Set stubs for working in the context of a SfProject
+     */
     inProject(inProject: boolean): void;
+    /**
+     * Stub salesforce org authorizations.
+     */
     stubAuths(...orgs: MockTestOrgData[]): Promise<void>;
+    /**
+     * Stub salesforce sandbox authorizations.
+     */
     stubSandboxes(...orgs: MockTestSandboxData[]): Promise<void>;
+    /**
+     * Stub the aliases in the global aliases config file.
+     */
     stubAliases(aliases: Record<string, string>, group?: AliasGroup): void;
+    /**
+     * Stub contents in the config file.
+     */
     stubConfig(config: Record<string, string>): void;
+    /**
+     * Stub the tokens in the global token config file.
+     */
     stubTokens(tokens: Record<string, string>): void;
 }
-export declare const uniqid: () => string;
+/**
+ * A function to generate a unique id and return it in the context of a template, if supplied.
+ *
+ * A template is a string that can contain `${%s}` to be replaced with a unique id.
+ * If the template contains the "%s" placeholder, it will be replaced with the unique id otherwise the id will be appended to the template.
+ *
+ * @param options an object with the following properties:
+ * - template: a template string.
+ * - length: the length of the unique id as presented in hexadecimal.
+ */
+export declare function uniqid(options?: {
+    template?: string;
+    length?: number;
+}): string;
 /**
  * Instantiate a @salesforce/core test context. This is automatically created by `const $$ = testSetup()`
  * but is useful if you don't want to have a global stub of @salesforce/core and you want to isolate it to
@@ -258,10 +289,10 @@ export declare const restoreContext: (testContext: TestContext) => void;
  *    $$.SANDBOX.stub(MyClass.prototype, 'myMethod').returnsFake(() => {});
  *
  *    // Set the contents that is used when aliases are read. Same for all config files.
- *    $$.configStubs.Aliases = { contents: { 'myTestAlias': 'user@company.com' } };
+ *    $$.stubAliases({ 'myTestAlias': 'user@company.com' });
  *
  *    // Will use the contents set above.
- *    const username = Aliases.fetch('myTestAlias');
+ *    const username = (await StateAggregator.getInstance()).aliases.resolveUseranme('myTestAlias');
  *    expect(username).to.equal('user@company.com');
  *  });
  * });
@@ -416,7 +447,11 @@ export declare class StreamingMockCometClient extends CometClient {
     disconnect(): Promise<void>;
 }
 /**
- * Mock class for OrgData.
+ * Mock class for Salesforce Orgs.
+ *
+ * @example
+ * const testOrg = new MockTestOrgData();
+ * await $$.stubAuths(testOrg)
  */
 export declare class MockTestOrgData {
     testId: string;
@@ -441,13 +476,38 @@ export declare class MockTestOrgData {
     constructor(id?: string, options?: {
         username: string;
     });
+    /**
+     * Add devhub username to properties.
+     */
     createDevHubUsername(username: string): void;
+    /**
+     * Mark this org as a devhub.
+     */
     makeDevHub(): void;
+    /**
+     * Returns a MockTestOrgData that represents a user created in the org.
+     */
     createUser(user: string): MockTestOrgData;
+    /**
+     * Return mock user information based on this org.
+     */
     getMockUserInfo(): JsonMap;
+    /**
+     * Return the auth config file contents.
+     */
     getConfig(): Promise<AuthFields>;
+    /**
+     * Return the Connection for the org.
+     */
     getConnection(): Promise<Connection>;
 }
+/**
+ * Mock class for Salesforce Sandboxes.
+ *
+ * @example
+ * const testOrg = new MockTestSandboxData();
+ * await $$.stubSandboxes(testOrg)
+ */
 export declare class MockTestSandboxData {
     id: string;
     sandboxOrgId: string;
@@ -459,5 +519,8 @@ export declare class MockTestSandboxData {
         name: string;
         username: string;
     }>);
+    /**
+     * Return the auth config file contents.
+     */
     getConfig(): Promise<SandboxFields>;
 }

package/lib/testSetup.js

@@ -12,6 +12,7 @@ const crypto_1 = require("crypto");
 const events_1 = require("events");
 const os_1 = require("os");
 const path_1 = require("path");
+const util = require("util");
 const kit_1 = require("@salesforce/kit");
 const ts_sinon_1 = require("@salesforce/ts-sinon");
 const ts_types_1 = require("@salesforce/ts-types");
@@ -29,9 +30,28 @@ const org_1 = require("./org");
 const sandboxAccessor_1 = require("./stateAggregator/accessors/sandboxAccessor");
 const aliasesConfig_1 = require("./config/aliasesConfig");
 const global_1 = require("./global");
-const uniqid = () => {
-    return (0, crypto_1.randomBytes)(16).toString('hex');
-};
+/**
+ * A function to generate a unique id and return it in the context of a template, if supplied.
+ *
+ * A template is a string that can contain `${%s}` to be replaced with a unique id.
+ * If the template contains the "%s" placeholder, it will be replaced with the unique id otherwise the id will be appended to the template.
+ *
+ * @param options an object with the following properties:
+ * - template: a template string.
+ * - length: the length of the unique id as presented in hexadecimal.
+ */
+function uniqid(options) {
+    var _a, _b;
+    const uniqueString = (0, crypto_1.randomBytes)(Math.ceil(((_a = options === null || options === void 0 ? void 0 : options.length) !== null && _a !== void 0 ? _a : 32) / 2.0))
+        .toString('hex')
+        .slice(0, (_b = options === null || options === void 0 ? void 0 : options.length) !== null && _b !== void 0 ? _b : 32);
+    if (!(options === null || options === void 0 ? void 0 : options.template)) {
+        return uniqueString;
+    }
+    return options.template.includes('%s')
+        ? util.format(options.template, uniqueString)
+        : `${options.template}${uniqueString}`;
+}
 exports.uniqid = uniqid;
 function getTestLocalPath(uid) {
     return (0, path_1.join)((0, os_1.tmpdir)(), uid, 'sfdx_core', 'local');
@@ -39,11 +59,11 @@ function getTestLocalPath(uid) {
 function getTestGlobalPath(uid) {
     return (0, path_1.join)((0, os_1.tmpdir)(), uid, 'sfdx_core', 'global');
 }
-function retrieveRootPathSync(isGlobal, uid = (0, exports.uniqid)()) {
+function retrieveRootPathSync(isGlobal, uid = uniqid()) {
     return isGlobal ? getTestGlobalPath(uid) : getTestLocalPath(uid);
 }
 // eslint-disable-next-line @typescript-eslint/require-await
-async function retrieveRootPath(isGlobal, uid = (0, exports.uniqid)()) {
+async function retrieveRootPath(isGlobal, uid = uniqid()) {
     return retrieveRootPathSync(isGlobal, uid);
 }
 function defaultFakeConnectionRequest() {
@@ -99,8 +119,8 @@ const instantiateContext = (sinon) => {
         TEST_LOGGER: new logger_1.Logger({
             name: 'SFDX_Core_Test_Logger',
         }).useMemoryLogging(),
-        id: (0, exports.uniqid)(),
-        uniqid: exports.uniqid,
+        id: uniqid(),
+        uniqid,
         configStubs: {},
         stubs: {},
         // eslint-disable-next-line @typescript-eslint/require-await
@@ -365,10 +385,10 @@ const _testSetup = (sinon) => {
  *    $$.SANDBOX.stub(MyClass.prototype, 'myMethod').returnsFake(() => {});
  *
  *    // Set the contents that is used when aliases are read. Same for all config files.
- *    $$.configStubs.Aliases = { contents: { 'myTestAlias': 'user@company.com' } };
+ *    $$.stubAliases({ 'myTestAlias': 'user@company.com' });
  *
  *    // Will use the contents set above.
- *    const username = Aliases.fetch('myTestAlias');
+ *    const username = (await StateAggregator.getInstance()).aliases.resolveUseranme('myTestAlias');
  *    expect(username).to.equal('user@company.com');
  *  });
  * });
@@ -564,10 +584,14 @@ class StreamingMockCometClient extends streamingClient_1.CometClient {
 }
 exports.StreamingMockCometClient = StreamingMockCometClient;
 /**
- * Mock class for OrgData.
+ * Mock class for Salesforce Orgs.
+ *
+ * @example
+ * const testOrg = new MockTestOrgData();
+ * await $$.stubAuths(testOrg)
  */
 class MockTestOrgData {
-    constructor(id = (0, exports.uniqid)(), options) {
+    constructor(id = uniqid(), options) {
         this.testId = id;
         this.userId = `user_id_${this.testId}`;
         this.orgId = `${this.testId}`;
@@ -581,12 +605,21 @@ class MockTestOrgData {
         this.refreshToken = `${this.testId}/refreshToken`;
         this.redirectUri = 'http://localhost:1717/OauthRedirect';
     }
+    /**
+     * Add devhub username to properties.
+     */
     createDevHubUsername(username) {
         this.devHubUsername = username;
     }
+    /**
+     * Mark this org as a devhub.
+     */
     makeDevHub() {
         this.isDevHub = true;
     }
+    /**
+     * Returns a MockTestOrgData that represents a user created in the org.
+     */
     createUser(user) {
         const userMock = new MockTestOrgData();
         userMock.username = user;
@@ -604,6 +637,9 @@ class MockTestOrgData {
         userMock.isExpired = this.isExpired;
         return userMock;
     }
+    /**
+     * Return mock user information based on this org.
+     */
     getMockUserInfo() {
         return {
             Id: this.userId,
@@ -619,6 +655,9 @@ class MockTestOrgData {
             Email: `user_email@${this.testId}.com`,
         };
     }
+    /**
+     * Return the auth config file contents.
+     */
     async getConfig() {
         const crypto = await crypto_2.Crypto.create();
         const config = {};
@@ -644,19 +683,32 @@ class MockTestOrgData {
         config.isDevHub = this.isDevHub;
         return config;
     }
+    /**
+     * Return the Connection for the org.
+     */
     async getConnection() {
         return (await org_1.Org.create({ aliasOrUsername: this.username })).getConnection();
     }
 }
 exports.MockTestOrgData = MockTestOrgData;
+/**
+ * Mock class for Salesforce Sandboxes.
+ *
+ * @example
+ * const testOrg = new MockTestSandboxData();
+ * await $$.stubSandboxes(testOrg)
+ */
 class MockTestSandboxData {
-    constructor(id = (0, exports.uniqid)(), options) {
+    constructor(id = uniqid(), options) {
         this.id = id;
         this.sandboxOrgId = id;
         this.prodOrgUsername = (options === null || options === void 0 ? void 0 : options.prodOrgUsername) || `admin_${id}@gb.org`;
         this.sandboxName = (options === null || options === void 0 ? void 0 : options.name) || `sandbox_${id}`;
         this.username = (options === null || options === void 0 ? void 0 : options.username) || `${this.prodOrgUsername}.sandbox`;
     }
+    /**
+     * Return the auth config file contents.
+     */
     async getConfig() {
         return {
             sandboxOrgId: this.sandboxOrgId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core",
-  "version": "3.21.6",
+  "version": "3.22.0",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",