@stencil/core 2.16.1-0 → 2.17.1

package/testing/jest/jest-config.d.ts

@@ -5,7 +5,7 @@ import type { Config } from '@jest/types';
  * @param config the Stencil config to use while generating Jest CLI arguments
  * @returns the arguments to pass to the Jest CLI, wrapped in an object
  */
-export declare function buildJestArgv(config: d.Config): Config.Argv;
+export declare function buildJestArgv(config: d.ValidatedConfig): Config.Argv;
 /**
  * Generate a Jest run configuration to be used as a part of the `argv` passed to the Jest CLI when it is invoked
  * programmatically

package/testing/jest/jest-runner.d.ts

@@ -1,9 +1,10 @@
 import type * as d from '@stencil/core/internal';
-export declare function runJest(config: d.Config, env: d.E2EProcessEnv): Promise<boolean>;
+import type { ConfigFlags } from '../../cli/config-flags';
+export declare function runJest(config: d.ValidatedConfig, env: d.E2EProcessEnv): Promise<boolean>;
 /**
  * Creates a Stencil test runner
  * @returns the test runner
  */
 export declare function createTestRunner(): any;
 export declare function includeTestFile(testPath: string, env: d.E2EProcessEnv): boolean;
-export declare function getEmulateConfigs(testing: d.TestingConfig, flags: d.ConfigFlags): d.EmulateConfig[];
+export declare function getEmulateConfigs(testing: d.TestingConfig, flags: ConfigFlags): d.EmulateConfig[];

package/testing/jest/jest-screenshot.d.ts

@@ -1,2 +1,2 @@
 import type * as d from '@stencil/core/internal';
-export declare function runJestScreenshot(config: d.Config, env: d.E2EProcessEnv): Promise<boolean>;
+export declare function runJestScreenshot(config: d.ValidatedConfig, env: d.E2EProcessEnv): Promise<boolean>;

package/testing/mocks.d.ts

@@ -1,10 +1,55 @@
-import type { BuildCtx, Cache, CompilerCtx, CompilerSystem, Config } from '@stencil/core/internal';
+import type { BuildCtx, Cache, CompilerCtx, CompilerSystem, Config, LoadConfigInit, ValidatedConfig, Module, UnvalidatedConfig } from '@stencil/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 Stencil 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 Stencil configuration
+ */
+export declare function mockValidatedConfig(sys?: CompilerSystem): ValidatedConfig;
+/**
+ * Creates a mock instance of a Stencil 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 Stencil configuration
+ */
+export declare function mockConfig(sys?: CompilerSystem): UnvalidatedConfig;
+/**
+ * Creates a configuration object used to bootstrap a Stencil 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;
 export declare function mockLogger(): TestingLogger;
-export declare function mockStencilSystem(): CompilerSystem;
+/**
+ * Create a {@link CompilerSystem} entity for testing the compiler.
+ *
+ * This function acts as a thin wrapper around a {@link TestingSystem} entity creation. It exists to provide a logical
+ * place in the codebase where we might expect Stencil engineers to reach for when attempting to mock a
+ * {@link CompilerSystem} base type. Should there prove to be usage of both this function and the one it wraps,
+ * reconsider if this wrapper is necessary.
+ *
+ * @returns a System instance for testing purposes.
+ */
+export declare function mockCompilerSystem(): TestingSystem;
 export declare function mockDocument(html?: string): Document;
 export declare function mockWindow(html?: string): Window;
+/**
+ * This gives you a mock Module, an interface which is the internal compiler
+ * representation of a module. It includes a bunch of information necessary for
+ * compilation, this mock basically sets sane defaults for all those values.
+ *
+ * @param mod is an override module that you can supply to set particular values
+ * @returns a module object ready to use in tests!
+ */
+export declare const mockModule: (mod?: Partial<Module>) => Module;

package/testing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stencil/core/testing",
-  "version": "2.16.1-0",
+  "version": "2.17.1",
   "description": "Stencil testing suite.",
   "main": "./index.js",
   "types": "./index.d.ts",

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

@@ -1,6 +1,6 @@
-import type { Config } from '@stencil/core/internal';
+import type { ValidatedConfig } from '@stencil/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/test/testing-utils.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/testing/testing-utils.d.ts

@@ -1,6 +1,78 @@
+/// <reference types="jest" />
 import type * as d from '@stencil/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 '@stencil/core/internal';
-export declare const createTesting: (config: Config) => Promise<Testing>;
+import type { ValidatedConfig, Testing } from '@stencil/core/internal';
+export declare const createTesting: (config: ValidatedConfig) => Promise<Testing>;