1 | /// <reference types="node" />
|
2 | import * as sinonType from 'sinon';
|
3 | import { AnyJson, JsonMap, Optional } from '@salesforce/ts-types';
|
4 | import { EventEmitter } from 'events';
|
5 | import { ConfigContents } from './config/configStore';
|
6 | import { Logger } from './logger';
|
7 | import { SfdxError } from './sfdxError';
|
8 | import { CometClient, CometSubscription, StreamingExtension } from './status/streamingClient';
|
9 | /**
|
10 | * Different parts of the system that are mocked out. They can be restored for
|
11 | * individual tests. Test's stubs should always go on the DEFAULT which is exposed
|
12 | * on the TestContext.
|
13 | */
|
14 | export interface SandboxTypes {
|
15 | DEFAULT: any;
|
16 | CRYPTO: any;
|
17 | CONFIG: any;
|
18 | CONNECTION: any;
|
19 | }
|
20 | /**
|
21 | * Different hooks into {@link ConfigFile} used for testing instead of doing file IO.
|
22 | */
|
23 | export interface ConfigStub {
|
24 | /**
|
25 | * readFn A function that controls all aspect of {@link ConfigFile.read}. For example, it won't set the contents
|
26 | * unless explicitly done. Only use this if you know what you are doing. Use retrieveContents
|
27 | * instead.
|
28 | */
|
29 | readFn?: () => Promise<ConfigContents>;
|
30 | /**
|
31 | * A function that controls all aspects of {@link ConfigFile.write}. For example, it won't read the contents unless
|
32 | * explicitly done. Only use this if you know what you are doing. Use updateContents instead.
|
33 | */
|
34 | writeFn?: () => Promise<void>;
|
35 | /**
|
36 | * The contents that are used when @{link ConfigFile.read} unless retrieveContents is set. This will also contain the
|
37 | * new config when @{link ConfigFile.write} is called. This will persist through config instances,
|
38 | * such as {@link Alias.update} and {@link Alias.fetch}.
|
39 | */
|
40 | contents?: ConfigContents;
|
41 | /**
|
42 | * A function to conditionally read based on the config instance. The `this` value will be the config instance.
|
43 | */
|
44 | retrieveContents?: () => Promise<JsonMap>;
|
45 | /**
|
46 | * A function to conditionally set based on the config instance. The `this` value will be the config instance.
|
47 | */
|
48 | updateContents?: () => Promise<JsonMap>;
|
49 | }
|
50 | /**
|
51 | * Different configuration options when running before each
|
52 | */
|
53 | export interface TestContext {
|
54 | /**
|
55 | * The default sandbox is cleared out before each test run.
|
56 | *
|
57 | * **See** [sinon sandbox]{@link http://sinonjs.org/releases/v1.17.7/sandbox/}.
|
58 | */
|
59 | SANDBOX: sinonType.SinonSandbox;
|
60 | /**
|
61 | * An object of different sandboxes. Used when
|
62 | * needing to restore parts of the system for customized testing.
|
63 | */
|
64 | SANDBOXES: SandboxTypes;
|
65 | /**
|
66 | * The test logger that is used when {@link Logger.child} is used anywhere. It uses memory logging.
|
67 | */
|
68 | TEST_LOGGER: Logger;
|
69 | /**
|
70 | * id A unique id for the test run.
|
71 | */
|
72 | id: string;
|
73 | /**
|
74 | * A function that returns unique strings.
|
75 | */
|
76 | uniqid: () => string;
|
77 | /**
|
78 | * An object used in tests that interact with config files.
|
79 | */
|
80 | configStubs: {
|
81 | [configName: string]: Optional<ConfigStub>;
|
82 | AuthInfoConfig?: ConfigStub;
|
83 | Aliases?: ConfigStub;
|
84 | SfdxProjectJson?: ConfigStub;
|
85 | SfdxConfig?: ConfigStub;
|
86 | };
|
87 | /**
|
88 | * A function used when resolving the local path.
|
89 | * @param uid Unique id.
|
90 | */
|
91 | localPathRetriever: (uid: string) => Promise<string>;
|
92 | /**
|
93 | * A function used when resolving the global path.
|
94 | * @param uid Unique id.
|
95 | */
|
96 | globalPathRetriever: (uid: string) => Promise<string>;
|
97 | /**
|
98 | * A function used for resolving paths. Calls localPathRetriever and globalPathRetriever.
|
99 | * @param isGlobal `true` if the config is global.
|
100 | * @param uid user id.
|
101 | */
|
102 | rootPathRetriever: (isGlobal: boolean, uid?: string) => Promise<string>;
|
103 | /**
|
104 | * Used to mock http request to Salesforce.
|
105 | * @param request An HttpRequest.
|
106 | * @param options Additional options.
|
107 | *
|
108 | * **See** {@link Connection.request}
|
109 | */
|
110 | fakeConnectionRequest: (request: AnyJson, options?: AnyJson) => Promise<AnyJson>;
|
111 | /**
|
112 | * Gets a config stub contents by name.
|
113 | * @param name The name of the config.
|
114 | * @param group If the config supports groups.
|
115 | */
|
116 | getConfigStubContents(name: string, group?: string): ConfigContents;
|
117 | /**
|
118 | * Sets a config stub contents by name
|
119 | * @param name The name of the config stub.
|
120 | * @param value The actual stub contents. The Mock data.
|
121 | */
|
122 | setConfigStubContents(name: string, value: ConfigContents): void;
|
123 | }
|
124 | /**
|
125 | * Use to mock out different pieces of sfdx-core to make testing easier. This will mock out
|
126 | * logging to a file, config file reading and writing, local and global path resolution, and
|
127 | * *http request using connection (soon)*.
|
128 | *
|
129 | * ```
|
130 | * // In a mocha tests
|
131 | * import testSetup from '@salesforce/core/lib/testSetup';
|
132 | *
|
133 | * const $$ = testSetup();
|
134 | *
|
135 | * describe(() => {
|
136 | * it('test', () => {
|
137 | * // Stub out your own method
|
138 | * $$.SANDBOX.stub(MyClass.prototype, 'myMethod').returnsFake(() => {});
|
139 | *
|
140 | * // Set the contents that is used when aliases are read. Same for all config files.
|
141 | * $$.configStubs.Aliases = { contents: { 'myTestAlias': 'user@company.com' } };
|
142 | *
|
143 | * // Will use the contents set above.
|
144 | * const username = Aliases.fetch('myTestAlias');
|
145 | * expect(username).to.equal('user@company.com');
|
146 | * });
|
147 | * });
|
148 | * ```
|
149 | */
|
150 | export declare const testSetup: (sinon?: any) => TestContext;
|
151 | /**
|
152 | * A pre-canned error for try/catch testing.
|
153 | *
|
154 | * **See** {@link shouldThrow}
|
155 | */
|
156 | export declare const unexpectedResult: SfdxError;
|
157 | /**
|
158 | * Use for this testing pattern:
|
159 | * ```
|
160 | * try {
|
161 | * await call()
|
162 | * assert.fail('this should never happen');
|
163 | * } catch (e) {
|
164 | * ...
|
165 | * }
|
166 | *
|
167 | * Just do this
|
168 | *
|
169 | * try {
|
170 | * await shouldThrow(call()); // If this succeeds unexpectedResultError is thrown.
|
171 | * } catch(e) {
|
172 | * ...
|
173 | * }
|
174 | * ```
|
175 | * @param f The async function that is expected to throw.
|
176 | */
|
177 | export declare function shouldThrow(f: Promise<unknown>): Promise<never>;
|
178 | /**
|
179 | * A helper to determine if a subscription will use callback or errorback.
|
180 | * Enable errback to simulate a subscription failure.
|
181 | */
|
182 | export declare enum StreamingMockSubscriptionCall {
|
183 | CALLBACK = 0,
|
184 | ERRORBACK = 1
|
185 | }
|
186 | /**
|
187 | * Additional subscription options for the StreamingMock.
|
188 | */
|
189 | export interface StreamingMockCometSubscriptionOptions {
|
190 | /**
|
191 | * Target URL.
|
192 | */
|
193 | url: string;
|
194 | /**
|
195 | * Simple id to associate with this instance.
|
196 | */
|
197 | id: string;
|
198 | /**
|
199 | * What is the subscription outcome a successful callback or an error?.
|
200 | */
|
201 | subscriptionCall: StreamingMockSubscriptionCall;
|
202 | /**
|
203 | * If it's an error that states what that error should be.
|
204 | */
|
205 | subscriptionErrbackError?: SfdxError;
|
206 | /**
|
207 | * A list of messages to playback for the client. One message per process tick.
|
208 | */
|
209 | messagePlaylist?: JsonMap[];
|
210 | }
|
211 | /**
|
212 | * Simulates a comet subscription to a streaming channel.
|
213 | */
|
214 | export declare class StreamingMockCometSubscription extends EventEmitter implements CometSubscription {
|
215 | static SUBSCRIPTION_COMPLETE: string;
|
216 | static SUBSCRIPTION_FAILED: string;
|
217 | private options;
|
218 | constructor(options: StreamingMockCometSubscriptionOptions);
|
219 | /**
|
220 | * Sets up a streaming subscription callback to occur after the setTimeout event loop phase.
|
221 | * @param callback The function to invoke.
|
222 | */
|
223 | callback(callback: () => void): void;
|
224 | /**
|
225 | * Sets up a streaming subscription errback to occur after the setTimeout event loop phase.
|
226 | * @param callback The function to invoke.
|
227 | */
|
228 | errback(callback: (error: Error) => void): void;
|
229 | }
|
230 | /**
|
231 | * Simulates a comet client. To the core streaming client this mocks the internal comet impl.
|
232 | * The uses setTimeout(0ms) event loop phase just so the client can simulate actual streaming without the response
|
233 | * latency.
|
234 | */
|
235 | export declare class StreamingMockCometClient extends CometClient {
|
236 | private readonly options;
|
237 | /**
|
238 | * Constructor
|
239 | * @param {StreamingMockCometSubscriptionOptions} options Extends the StreamingClient options.
|
240 | */
|
241 | constructor(options: StreamingMockCometSubscriptionOptions);
|
242 | /**
|
243 | * Fake addExtension. Does nothing.
|
244 | */
|
245 | addExtension(extension: StreamingExtension): void;
|
246 | /**
|
247 | * Fake disable. Does nothing.
|
248 | */
|
249 | disable(label: string): void;
|
250 | /**
|
251 | * Fake handshake that invoke callback after the setTimeout event phase.
|
252 | * @param callback The function to invoke.
|
253 | */
|
254 | handshake(callback: () => void): void;
|
255 | /**
|
256 | * Fake setHeader. Does nothing,
|
257 | */
|
258 | setHeader(name: string, value: string): void;
|
259 | /**
|
260 | * Fake subscription that completed after the setTimout event phase.
|
261 | * @param channel The streaming channel.
|
262 | * @param callback The function to invoke after the subscription completes.
|
263 | */
|
264 | subscribe(channel: string, callback: (message: JsonMap) => void): CometSubscription;
|
265 | /**
|
266 | * Fake disconnect. Does Nothing.
|
267 | */
|
268 | disconnect(): Promise<void>;
|
269 | }
|
270 | /**
|
271 | * Mock class for OrgData.
|
272 | */
|
273 | export declare class MockTestOrgData {
|
274 | testId: string;
|
275 | alias?: string;
|
276 | username: string;
|
277 | devHubUsername?: string;
|
278 | orgId: string;
|
279 | loginUrl: string;
|
280 | instanceUrl: string;
|
281 | clientId: string;
|
282 | clientSecret: string;
|
283 | authcode: string;
|
284 | accessToken: string;
|
285 | refreshToken: string;
|
286 | userId: string;
|
287 | constructor(id?: string);
|
288 | createDevHubUsername(username: string): void;
|
289 | makeDevHub(): void;
|
290 | createUser(user: string): MockTestOrgData;
|
291 | getMockUserInfo(): JsonMap;
|
292 | getConfig(): Promise<ConfigContents>;
|
293 | }
|