@itwin/core-backend/lib/esm/internal/HubMock.d.ts

iTwin.js backend components

import { GuidString } from "@itwin/core-bentley";
import { ChangesetFileProps, ChangesetIndex, ChangesetProps, ChangesetRange, IModelVersion, LocalDirName } from "@itwin/core-common";
import { AcquireNewBriefcaseIdArg, BriefcaseDbArg, BriefcaseIdArg, ChangesetArg, CreateNewIModelProps, DownloadChangesetArg, DownloadChangesetRangeArg, IModelIdArg, IModelNameArg, LockMap, LockProps, V2CheckpointAccessProps } from "../BackendHubAccess";
import { CheckpointProps } from "../CheckpointManager";
import { LocalHub } from "../LocalHub";
/**
 * Mocks iModelHub for testing creating Briefcases, downloading checkpoints, and simulating multiple users pushing and pulling changesets, etc.
 *
 * Generally, tests for apis that *create or modify* iModels can and should be mocked. Otherwise they:
 * - create tremendous load on the test servers when they run on programmer's desktops and in CI jobs
 * - waste network and data center resources (i.e. $$$s),
 * - interfere with other tests running on the same or other systems, and
 * - (far worse) are the source of test flakiness outside of the api being tested.
 *
 * This class can be used to create tests that do not require authentication, are synchronous,
 * are guaranteed to be self-contained (i.e. do not interfere with other tests running at the same time or later), and do not fail for reasons outside
 * of the control of the test itself. As a bonus, in addition to making tests more reliable, mocking IModelHub generally makes tests run *much* faster.
 *
 * On the other hand, tests that expect to find an existing iModels, checkpoints, changesets, etc. in IModelHub cannot be mocked. In that case, those tests
 * should be careful to NOT modify the data, since doing so causes interference with other tests running simultaneously. These tests should be limited to
 * low level testing of the core apis only.
 *
 * To initialize HubMock, call [[startup]] at the beginning of your test, usually in `describe.before`. Thereafter, all access to iModelHub for an iModel will be
 * directed to a [[LocalHub]] - your test code does not change. After the test(s) complete, call [[shutdown]] (usually in `describe.after`) to stop mocking IModelHub and clean
 * up any resources used by the test(s). If you want to mock a single test, call [[startup]] as the first line and [[shutdown]] as the last. If you wish to run the
 * test against a "real" IModelHub, you can simply comment off the call [[startup]], though in that case you should make sure the name of your
 * iModel is unique so your test won't collide with other tests (iModel name uniqueness is not necessary for mocked tests.)
 *
 * Mocked tests must always start by creating a new iModel via [[IModelHost[_hubAccess].createNewIModel]] with a `version0` iModel.
 * They use mock (aka "bogus") credentials for `AccessTokens`, which is fine since [[HubMock]] never accesses resources outside the current
 * computer.
 *
 * @note Only one HubMock at a time, *running in a single process*, may be active. The comments above about multiple simultaneous tests refer to tests
 * running on different computers, or on a single computer in multiple processes. All of those scenarios are problematic without mocking.
 *
 * @internal
 */
export declare class HubMock {
    private static mockRoot;
    private static hubs;
    private static _saveHubAccess;
    private static _iTwinId;
    /** Determine whether a test us currently being run under HubMock */
    static get isValid(): boolean;
    static get iTwinId(): string;
    /**
     * Begin mocking IModelHub access. After this call, all access to IModelHub will be directed to a [[LocalHub]].
     * @param mockName a unique name (e.g. "MyTest") for this HubMock to disambiguate tests when more than one is simultaneously active.
     * It is used to create a private directory used by the HubMock for a test. That directory is removed when [[shutdown]] is called.
     */
    static startup(mockName: LocalDirName, outputDir: string): void;
    /** Stop a HubMock that was previously started with [[startup]]
     * @note this function throws an exception if any of the iModels used during the tests are left open.
     */
    static shutdown(): void;
    static findLocalHub(iModelId: GuidString): LocalHub;
    /** create a [[LocalHub]] for an iModel.  */
    static createNewIModel(arg: CreateNewIModelProps): Promise<GuidString>;
    /** remove the [[LocalHub]] for an iModel */
    static destroy(iModelId: GuidString): void;
    /** All methods below are mocks of the [[BackendHubAccess]] interface */
    static getChangesetFromNamedVersion(arg: IModelIdArg & {
        versionName: string;
    }): Promise<ChangesetProps>;
    private static changesetIndexFromArg;
    static getChangesetFromVersion(arg: IModelIdArg & {
        version: IModelVersion;
    }): Promise<ChangesetProps>;
    static getLatestChangeset(arg: IModelIdArg): Promise<ChangesetProps>;
    private static getAccessToken;
    static getMyBriefcaseIds(arg: IModelIdArg): Promise<number[]>;
    static acquireNewBriefcaseId(arg: AcquireNewBriefcaseIdArg): Promise<number>;
    /** Release a briefcaseId. After this call it is illegal to generate changesets for the released briefcaseId. */
    static releaseBriefcase(arg: BriefcaseIdArg): Promise<void>;
    static downloadChangeset(arg: DownloadChangesetArg): Promise<ChangesetFileProps>;
    static downloadChangesets(arg: DownloadChangesetRangeArg): Promise<ChangesetFileProps[]>;
    static queryChangeset(arg: ChangesetArg): Promise<ChangesetProps>;
    static queryChangesets(arg: IModelIdArg & {
        range?: ChangesetRange;
    }): Promise<ChangesetProps[]>;
    static pushChangeset(arg: IModelIdArg & {
        changesetProps: ChangesetFileProps;
    }): Promise<ChangesetIndex>;
    static queryV2Checkpoint(arg: CheckpointProps): Promise<V2CheckpointAccessProps | undefined>;
    static releaseAllLocks(arg: BriefcaseDbArg): Promise<void>;
    static queryAllLocks(_arg: BriefcaseDbArg): Promise<LockProps[]>;
    static acquireLocks(arg: BriefcaseDbArg, locks: LockMap): Promise<void>;
    static queryIModelByName(arg: IModelNameArg): Promise<GuidString | undefined>;
    static deleteIModel(arg: IModelIdArg & {
        iTwinId: GuidString;
    }): Promise<void>;
    private static mockProgressReporting;
}
//# sourceMappingURL=HubMock.d.ts.map