@wirestate/core 0.6.0

package/test-utils.d.ts

@@ -0,0 +1,108 @@
+import { Container as Container$1, Newable, ServiceIdentifier } from 'inversify';
+import { I as IInjectableDescriptor } from './lib.js';
+
+/**
+ * Options for {@link mockBindService}.
+ */
+interface IMockBindServiceOptions {
+    /**
+     * Whether to skip the activation lifecycle for the service.
+     * If true, `OnActivated` and `OnDeactivation` hooks will not be triggered.
+     */
+    skipLifecycle?: boolean;
+}
+/**
+ * Binds a service class to the IoC container for testing purposes.
+ * This utility uses {@link bindService} internally to ensure the service is correctly registered
+ * with the appropriate scope and metadata.
+ *
+ * @param container - the IoC container to bind the service to
+ * @param ServiceClass - the service class to bind
+ * @param options - optional binding configuration
+ * @returns void
+ */
+declare function mockBindService<T extends object>(container: Container$1, ServiceClass: Newable<T>, options?: IMockBindServiceOptions): void;
+
+/**
+ * Options for {@link mockBindEntry}.
+ */
+interface IMockBindEntryOptions {
+    /**
+     * Whether to skip the activation lifecycle for the entry.
+     * If true, `OnActivated` and `OnDeactivation` hooks will not be triggered.
+     * Note: This only applies when the entry is a service class or an instance binding.
+     */
+    skipLifecycle?: boolean;
+}
+/**
+ * Binds a service entry to the IoC container for testing purposes.
+ * This utility uses {@link bindEntry} internally.
+ * It supports both service classes and injectable descriptors (constants, dynamic values, etc.).
+ *
+ * @param container - the IoC container to bind the entry to
+ * @param entry - the service class or injectable descriptor to bind
+ * @param options - optional binding configuration
+ * @returns void
+ */
+declare function mockBindEntry<T extends object>(container: Container$1, entry: Newable<T> | IInjectableDescriptor, options?: IMockBindEntryOptions): void;
+
+/**
+ * Unbinds a service from the IoC container.
+ * This is useful in tests to reset or override specific service registrations.
+ *
+ * @param container - the IoC container to unbind the service from
+ * @param ServiceClass - the service class to unbind
+ */
+declare function mockUnbindService<T extends object>(container: Container$1, ServiceClass: Newable<T>): void;
+
+/**
+ * Options for {@link mockContainer}.
+ */
+interface IMockContainerOptions {
+    /**
+     * List of services or injectable descriptors to bind to the container.
+     */
+    entries?: Array<Newable<object> | IInjectableDescriptor>;
+    /**
+     * List of injection identifiers to immediately activate after binding.
+     * All identifiers must correspond to entries provided in the `services` list.
+     */
+    activate?: Array<ServiceIdentifier>;
+    /**
+     * Whether to skip the activation lifecycle for all bound services.
+     * If true, `OnActivated` and `OnDeactivation` hooks will not be triggered.
+     */
+    skipLifecycle?: boolean;
+}
+/**
+ * Creates and configures a mock IoC container for testing.
+ * This utility initializes a new container and binds the provided services or descriptors using {@link mockBindEntry}.
+ * It also supports optional immediate activation of services.
+ *
+ * @param options - configuration options for the mock container
+ * @returns a configured InversifyJS {@link Container}
+ *
+ * @throws {WirestateError} if an identifier in `activate` is not found in `services`
+ */
+declare function mockContainer(options?: IMockContainerOptions): Container$1;
+
+/**
+ * Options for {@link mockService}.
+ */
+interface IMockServiceOptions {
+    /**
+     * If true, skips the lifecycle hooks (e.g., OnActivated) during service binding and instantiation.
+     */
+    skipLifecycle?: boolean;
+}
+/**
+ * Mocks a service by binding it to an IoC container and returning its instance.
+ *
+ * @param service - the service class to mock
+ * @param container - the IoC container to use, defaults to a new {@link mockContainer}
+ * @param options - additional options for mocking
+ * @returns the instantiated service instance
+ */
+declare function mockService<T extends object>(service: Newable<T>, container?: Container, options?: IMockServiceOptions): T;
+
+export { mockBindEntry, mockBindService, mockContainer, mockService, mockUnbindService };