@rindo/core 2.17.0 → 2.17.2-0

package/testing/mocks.d.ts

@@ -1,7 +1,32 @@
-import type { BuildCtx, Cache, CompilerCtx, CompilerSystem, Config, Module } from '@rindo/core/internal';
+import type { BuildCtx, Cache, CompilerCtx, CompilerSystem, Config, LoadConfigInit, ValidatedConfig, Module, UnvalidatedConfig } from '@rindo/core/internal';
 import { TestingSystem } from './testing-sys';
 import { TestingLogger } from './testing-logger';
-export declare function mockConfig(sys?: CompilerSystem): Config;
+/**
+ * Creates a mock instance of an internal, validated Rindo configuration object
+ * @param sys an optional compiler system to associate with the config. If one is not provided, one will be created for
+ * the caller
+ * @returns the mock Rindo configuration
+ */
+export declare function mockValidatedConfig(sys?: CompilerSystem): ValidatedConfig;
+/**
+ * Creates a mock instance of a Rindo configuration entity. The mocked configuration has no guarantees around the
+ * types/validity of its data.
+ * @param sys an optional compiler system to associate with the config. If one is not provided, one will be created for
+ * the caller
+ * @returns the mock Rindo configuration
+ */
+export declare function mockConfig(sys?: CompilerSystem): UnvalidatedConfig;
+/**
+ * Creates a configuration object used to bootstrap a Rindo task invocation
+ *
+ * Several fields are intentionally undefined for this entity. While it would be trivial to stub them out, this mock
+ * generation function operates under the assumption that entities like loggers and compiler system abstractions will
+ * be shared by multiple entities in a test suite, who should provide those entities to this function
+ *
+ * @param overrides the properties on the default entity to manually override
+ * @returns the default configuration initialization object, with any overrides applied
+ */
+export declare const mockLoadConfigInit: (overrides?: Partial<LoadConfigInit>) => LoadConfigInit;
 export declare function mockCompilerCtx(config?: Config): CompilerCtx;
 export declare function mockBuildCtx(config?: Config, compilerCtx?: CompilerCtx): BuildCtx;
 export declare function mockCache(config?: Config, compilerCtx?: CompilerCtx): Cache;

package/testing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rindo/core/testing",
-  "version": "2.17.0",
+  "version": "2.17.2-0",
   "description": "Rindo testing suite.",
   "main": "./index.js",
   "types": "./index.d.ts",

package/testing/puppeteer/puppeteer-browser.d.ts

@@ -1,6 +1,6 @@
-import type { Config } from '@rindo/core/internal';
+import type { ValidatedConfig } from '@rindo/core/internal';
 import type * as puppeteer from 'puppeteer';
-export declare function startPuppeteerBrowser(config: Config): Promise<puppeteer.Browser>;
+export declare function startPuppeteerBrowser(config: ValidatedConfig): Promise<puppeteer.Browser>;
 export declare function connectBrowser(): Promise<any>;
 export declare function disconnectBrowser(browser: puppeteer.Browser): Promise<void>;
 export declare function newBrowserPage(browser: puppeteer.Browser): Promise<puppeteer.Page>;

package/testing/testing-utils.d.ts

@@ -1,6 +1,78 @@
+/// <reference types="jest" />
 import type * as d from '@rindo/core/internal';
 export declare function shuffleArray(array: any[]): any[];
-export declare function expectFiles(fs: d.InMemoryFileSystem, filePaths: string[]): void;
-export declare function doNotExpectFiles(fs: d.InMemoryFileSystem, filePaths: string[]): void;
+/**
+ * Testing utility to validate the existence of some provided file paths using a specific file system
+ *
+ * @param fs the file system to use to validate the existence of some files
+ * @param filePaths the paths to validate
+ * @throws when one or more of the provided file paths cannot be found
+ */
+export declare function expectFilesExist(fs: d.InMemoryFileSystem, filePaths: string[]): void;
+/**
+ * Testing utility to validate the non-existence of some provided file paths using a specific file system
+ *
+ * @param fs the file system to use to validate the non-existence of some files
+ * @param filePaths the paths to validate
+ * @throws when one or more of the provided file paths is found
+ */
+export declare function expectFilesDoNotExist(fs: d.InMemoryFileSystem, filePaths: string[]): void;
 export declare function getAppScriptUrl(config: d.Config, browserUrl: string): string;
 export declare function getAppStyleUrl(config: d.Config, browserUrl: string): string;
+/**
+ * Utility for silencing `console` functions in tests.
+ *
+ * When this function is first called it grabs a reference to the `log`,
+ * `error`, and `warn` functions on `console` and then returns a per-test setup
+ * function which sets up a fresh set of mocks (via `jest.fn()`) and then
+ * assigns them to each of these functions. This setup function will return a
+ * reference to each of the three mock functions so tests can make assertions
+ * about their calls and so on.
+ *
+ * Because references to the original `.log`, `.error`, and `.warn` functions
+ * exist in closure within the function, it can use an `afterAll` call to clean
+ * up after itself and ensure that the original implementations are restored
+ * after the test suite finishes.
+ *
+ * An example of using this to silence log statements in a single test could look
+ * like this:
+ *
+ * ```ts
+ * describe("my-test-suite", () => {
+ *   const setupConsoleMocks = setupConsoleMocker()
+ *
+ *   it("should log a message", () => {
+ *     const { logMock } = setupConsoleMocks();
+ *     myFunctionWhichLogs(foo, bar);
+ *     expect(logMock).toBeCalledWith('my log message');
+ *   })
+ * })
+ * ```
+ *
+ * @returns a per-test mock setup function
+ */
+export declare function setupConsoleMocker(): ConsoleMocker;
+interface ConsoleMocker {
+    (): {
+        logMock: jest.Mock<typeof console.log>;
+        warnMock: jest.Mock<typeof console.warn>;
+        errorMock: jest.Mock<typeof console.error>;
+    };
+}
+/**
+ * the callback that `withSilentWarn` expects to receive. Basically receives a mock
+ * as its argument and returns a `Promise`, the value of which is returns by `withSilentWarn`
+ * as well.
+ */
+declare type SilentWarnFunc<T> = (mock: jest.Mock<typeof console.warn>) => Promise<T>;
+/**
+ * Wrap a single callback with a silent `console.warn`. The callback passed in
+ * receives the mocking function as an argument, so you can easily make assertions
+ * that it is called if necessary.
+ *
+ * @param cb a callback which `withSilentWarn` will call after replacing `console.warn`
+ * with a mock.
+ * @returns a Promise wrapping the return value of the callback
+ */
+export declare function withSilentWarn<T>(cb: SilentWarnFunc<T>): Promise<T>;
+export {};

package/testing/testing.d.ts

@@ -1,2 +1,2 @@
-import type { Config, Testing } from '@rindo/core/internal';
-export declare const createTesting: (config: Config) => Promise<Testing>;
+import type { ValidatedConfig, Testing } from '@rindo/core/internal';
+export declare const createTesting: (config: ValidatedConfig) => Promise<Testing>;