@salesforce/core 4.0.0 → 4.0.1

package/lib/testSetup.d.ts

@@ -1,24 +1,27 @@
 /// <reference types="node" />
 import { EventEmitter } from 'events';
-import * as sinonType from 'sinon';
+import { SinonSandbox, SinonStatic, SinonStub } from 'sinon';
 import { AnyJson, JsonMap, Optional } from '@salesforce/ts-types';
 import { ConfigContents } from './config/configStore';
+import { Connection } from './org/connection';
 import { Logger } from './logger';
-import { SfdxError } from './sfdxError';
+import { SfError } from './sfError';
 import { CometClient, CometSubscription, Message, StreamingExtension } from './status/streamingClient';
-import { SfOrg } from './globalInfo';
+import { AuthFields, SandboxFields } from './org';
+import { AliasGroup } from './config/aliasesConfig';
 /**
  * Different parts of the system that are mocked out. They can be restored for
  * individual tests. Test's stubs should always go on the DEFAULT which is exposed
  * on the TestContext.
  */
 export interface SandboxTypes {
-    DEFAULT: sinon.SinonSandbox;
-    CRYPTO: sinon.SinonSandbox;
-    CONFIG: sinon.SinonSandbox;
-    PROJECT: sinon.SinonSandbox;
-    CONNECTION: sinon.SinonSandbox;
-    FS: sinonType.SinonSandbox;
+    DEFAULT: SinonSandbox;
+    CRYPTO: SinonSandbox;
+    CONFIG: SinonSandbox;
+    PROJECT: SinonSandbox;
+    CONNECTION: SinonSandbox;
+    FS: SinonSandbox;
+    ORGS: SinonSandbox;
 }
 /**
  * Different hooks into {@link ConfigFile} used for testing instead of doing file IO.
@@ -52,15 +55,15 @@ export interface ConfigStub {
     updateContents?: () => Promise<JsonMap>;
 }
 /**
- * Different configuration options when running before each
+ * Instantiate a @salesforce/core test context.
  */
-export interface TestContext {
+export declare class TestContext {
     /**
      * The default sandbox is cleared out before each test run.
      *
-     * **See** [sinon sandbox]{@link http://sinonjs.org/releases/v1.17.7/sandbox/}.
+     * **See** [sinon sandbox]{@link https://sinonjs.org/releases/v14/sandbox/}.
      */
-    SANDBOX: sinonType.SinonSandbox;
+    SANDBOX: SinonSandbox;
     /**
      * An object of different sandboxes. Used when
      * needing to restore parts of the system for customized testing.
@@ -74,58 +77,69 @@ export interface TestContext {
      * id A unique id for the test run.
      */
     id: string;
-    /**
-     * A function that returns unique strings.
-     */
-    uniqid: () => string;
     /**
      * An object used in tests that interact with config files.
      */
     configStubs: {
         [configName: string]: Optional<ConfigStub>;
-        GlobalInfo?: ConfigStub;
-        Aliases?: ConfigStub;
-        SfdxProjectJson?: ConfigStub;
-        SfdxConfig?: ConfigStub;
+        AliasesConfig?: ConfigStub;
+        AuthInfoConfig?: ConfigStub;
+        Config?: ConfigStub;
+        SfProjectJson?: ConfigStub;
+        TokensConfig?: ConfigStub;
+        OrgUsersConfig?: ConfigStub;
     };
+    /**
+     * A record of stubs created during instantiation.
+     */
+    stubs: Record<string, SinonStub>;
+    constructor(options?: {
+        sinon?: SinonStatic;
+        sandbox?: SinonSandbox;
+        setup?: boolean;
+    });
+    /**
+     * Generate unique string.
+     */
+    uniqid(): string;
     /**
      * A function used when resolving the local path. Calls localPathResolverSync by default.
      *
      * @param uid Unique id.
      */
-    localPathRetriever: (uid: string) => Promise<string>;
+    localPathRetriever(uid: string): Promise<string>;
     /**
      * A function used when resolving the local path.
      *
      * @param uid Unique id.
      */
-    localPathRetrieverSync: (uid: string) => string;
+    localPathRetrieverSync(uid: string): string;
     /**
      * A function used when resolving the global path. Calls globalPathResolverSync by default.
      *
      * @param uid Unique id.
      */
-    globalPathRetriever: (uid: string) => Promise<string>;
+    globalPathRetriever(uid: string): Promise<string>;
     /**
      * A function used when resolving the global path.
      *
      * @param uid Unique id.
      */
-    globalPathRetrieverSync: (uid: string) => string;
+    globalPathRetrieverSync(uid: string): string;
     /**
      * A function used for resolving paths. Calls localPathRetriever and globalPathRetriever.
      *
      * @param isGlobal `true` if the config is global.
      * @param uid user id.
      */
-    rootPathRetriever: (isGlobal: boolean, uid?: string) => Promise<string>;
+    rootPathRetriever(isGlobal: boolean, uid?: string): Promise<string>;
     /**
      * A function used for resolving paths. Calls localPathRetrieverSync and globalPathRetrieverSync.
      *
      * @param isGlobal `true` if the config is global.
      * @param uid user id.
      */
-    rootPathRetrieverSync: (isGlobal: boolean, uid?: string) => string;
+    rootPathRetrieverSync(isGlobal: boolean, uid?: string): string;
     /**
      * Used to mock http request to Salesforce.
      *
@@ -134,7 +148,7 @@ export interface TestContext {
      *
      * **See** {@link Connection.request}
      */
-    fakeConnectionRequest: (request: AnyJson, options?: AnyJson) => Promise<AnyJson>;
+    fakeConnectionRequest(request: AnyJson, options?: AnyJson): Promise<AnyJson>;
     /**
      * Gets a config stub contents by name.
      *
@@ -149,8 +163,62 @@ export interface TestContext {
      * @param value The actual stub contents. The Mock data.
      */
     setConfigStubContents(name: string, value: ConfigContents): void;
-    inProject(inProject: boolean): 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 user authorizations.
+     *
+     * @param users The users to stub.
+     * The key is the username of the admin user and it must be included in the users array in order to obtain the orgId key for the remaining users.
+     * The admin user is excluded from the users array.
+     *
+     */
+    stubUsers(users: Record<string, MockTestOrgData[]>): void;
+    /**
+     * Stub salesforce sandbox authorizations.
+     */
+    stubSandboxes(...sandboxes: 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>): Promise<void>;
+    /**
+     * Stub the tokens in the global token config file.
+     */
+    stubTokens(tokens: Record<string, string>): void;
+    restore(): void;
+    init(): void;
+    /**
+     * Add beforeEach and afterEach hooks to init the stubs and restore them.
+     * This is called automatically when the class is instantiated unless the setup option is set to false.
+     */
+    setup(): void;
+    private requireSinon;
 }
+/**
+ * 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
@@ -163,16 +231,16 @@ export interface TestContext {
  * const $$ = instantiateContext();
  *
  * beforeEach(() => {
- *   stubContext($$);
+ *   $$.init()
  * });
  *
  * afterEach(() => {
- *   restoreContext($$);
+ *   $$.restore();
  * });
  * ```
  * @param sinon
  */
-export declare const instantiateContext: (sinon?: any) => TestContext;
+export declare const instantiateContext: (sinon?: SinonStatic) => TestContext;
 /**
  * Stub a @salesforce/core test context. This will mock out logging to a file, config file reading and writing,
  * local and global path resolution, and http request using connection (soon)*.
@@ -188,16 +256,16 @@ export declare const instantiateContext: (sinon?: any) => TestContext;
  * const $$ = instantiateContext();
  *
  * beforeEach(() => {
- *   stubContext($$);
+ *   $$.init()
  * });
  *
  * afterEach(() => {
- *   restoreContext($$);
+ *   $$.restore();
  * });
  * ```
  * @param testContext
  */
-export declare const stubContext: (testContext: TestContext) => void;
+export declare const stubContext: (testContext: TestContext) => Record<string, SinonStub>;
 /**
  * Restore a @salesforce/core test context. This is automatically stubbed in the global beforeEach created by
  * `const $$ = testSetup()` but is useful if you don't want to have a global stub of @salesforce/core and you
@@ -208,57 +276,28 @@ export declare const stubContext: (testContext: TestContext) => void;
  * const $$ = instantiateContext();
  *
  * beforeEach(() => {
- *   stubContext($$);
+ *   $$.init()
  * });
  *
  * afterEach(() => {
- *   restoreContext($$);
+ *   $$.restore();
  * });
  * ```
  * @param testContext
  */
 export declare const restoreContext: (testContext: TestContext) => void;
-/**
- * Use to mock out different pieces of sfdx-core to make testing easier. This will mock out
- * logging to a file, config file reading and writing, local and global path resolution, and
- * *http request using connection (soon)*.
- *
- * **Note:** The testSetup should be outside of the describe. If you need to stub per test, use
- * `instantiateContext`, `stubContext`, and `restoreContext`.
- * ```
- * // In a mocha tests
- * import testSetup from '@salesforce/core/lib/testSetup';
- *
- * const $$ = testSetup();
- *
- * describe(() => {
- *  it('test', () => {
- *    // Stub out your own method
- *    $$.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' } };
- *
- *    // Will use the contents set above.
- *    const username = Aliases.fetch('myTestAlias');
- *    expect(username).to.equal('user@company.com');
- *  });
- * });
- * ```
- */
-export declare const testSetup: (sinon?: any) => TestContext;
 /**
  * A pre-canned error for try/catch testing.
  *
  * **See** {@link shouldThrow}
  */
-export declare const unexpectedResult: SfdxError;
+export declare const unexpectedResult: SfError;
 /**
  * Use for this testing pattern:
  * ```
  *  try {
  *      await call()
- *      assert.fail('this should never happen');
+ *      assert.fail("this should never happen");
  *  } catch (e) {
  *  ...
  *  }
@@ -274,7 +313,29 @@ export declare const unexpectedResult: SfdxError;
  *
  * @param f The async function that is expected to throw.
  */
-export declare function shouldThrow(f: Promise<unknown>): Promise<never>;
+export declare function shouldThrow(f: Promise<unknown>, message?: string): Promise<never>;
+/**
+ * Use for this testing pattern:
+ * ```
+ *  try {
+ *      call()
+ *      assert.fail("this should never happen");
+ *  } catch (e) {
+ *  ...
+ *  }
+ *
+ *  Just do this
+ *
+ *  try {
+ *      shouldThrowSync(call); // If this succeeds unexpectedResultError is thrown.
+ *  } catch(e) {
+ *  ...
+ *  }
+ * ```
+ *
+ * @param f The function that is expected to throw.
+ */
+export declare function shouldThrowSync(f: () => unknown, message?: string): never;
 /**
  * A helper to determine if a subscription will use callback or errorback.
  * Enable errback to simulate a subscription failure.
@@ -302,7 +363,7 @@ export interface StreamingMockCometSubscriptionOptions {
     /**
      * If it's an error that states what that error should be.
      */
-    subscriptionErrbackError?: SfdxError;
+    subscriptionErrbackError?: SfError;
     /**
      * A list of messages to playback for the client. One message per process tick.
      */
@@ -372,12 +433,32 @@ export declare class StreamingMockCometClient extends CometClient {
      */
     disconnect(): Promise<void>;
 }
+type MockUserInfo = {
+    Id: string;
+    Username: string;
+    LastName: string;
+    Alias: string;
+    Configs: string[] | undefined;
+    TimeZoneSidKey: string;
+    LocaleSidKey: string;
+    EmailEncodingKey: string;
+    ProfileId: string;
+    LanguageLocaleKey: string;
+    Email: string;
+};
 /**
- * Mock class for OrgData.
+ * Mock class for Salesforce Orgs.
+ *
+ * @example
+ * ```
+ * const testOrg = new MockTestOrgData();
+ * await $$.stubAuths(testOrg)
+ * ```
  */
 export declare class MockTestOrgData {
     testId: string;
-    alias?: string;
+    aliases?: string[];
+    configs?: string[];
     username: string;
     devHubUsername?: string;
     orgId: string;
@@ -387,15 +468,65 @@ export declare class MockTestOrgData {
     clientSecret: string;
     authcode: string;
     accessToken: string;
-    refreshToken: string;
+    refreshToken: string | undefined;
+    tracksSource: boolean | undefined;
     userId: string;
     redirectUri: string;
+    isDevHub?: boolean;
+    isScratchOrg?: boolean;
+    isExpired?: boolean | 'unknown';
+    password?: string;
     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;
-    getMockUserInfo(): JsonMap;
-    getConfig(): Promise<SfOrg>;
+    /**
+     * Return mock user information based on this org.
+     */
+    getMockUserInfo(): MockUserInfo;
+    /**
+     * 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;
+    prodOrgUsername: string;
+    sandboxName?: string;
+    username?: string;
+    constructor(id?: string, options?: Partial<{
+        prodOrgUsername: string;
+        name: string;
+        username: string;
+    }>);
+    /**
+     * Return the auth config file contents.
+     */
+    getConfig(): Promise<SandboxFields>;
 }
+export {};