@rocketh/test-utils 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-present Ronan Sandford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @rocketh/test-utils
+
+Test utilities for rocketh packages, providing helper functions and utilities used across rocketh's test suites.
+
+For full documentation, visit [rocketh.dev](https://rocketh.dev).
+
+For hardhat-deploy documentation, see [rocketh.dev/hardhat-deploy/](https://rocketh.dev/hardhat-deploy/).

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @rocketh/test-utils
+ *
+ * Test utilities for rocketh packages. Provides mock environments, providers,
+ * and artifacts for testing deployment scenarios.
+ */
+import type { Abi, Artifact, Environment } from '@rocketh/core/types';
+import type { EIP1193Provider } from 'eip-1193';
+/**
+ * Configuration for mock provider responses.
+ * Allows tests to specify custom return values for specific RPC methods.
+ */
+export type MockProviderConfig = {
+    /**
+     * Override responses for specific RPC methods.
+     * Can be a static value or a function that receives params and returns a value.
+     */
+    responses?: {
+        [method: string]: unknown | ((params?: unknown[]) => unknown | Promise<unknown>);
+    };
+    /**
+     * Called when an unmocked method is requested.
+     * If not provided, returns null and logs a warning.
+     */
+    onUnmockedMethod?: (method: string, params?: unknown[]) => unknown | Promise<unknown>;
+};
+/**
+ * A mock EIP-1193 provider with configurable responses.
+ */
+export type MockProvider = EIP1193Provider & {
+    /**
+     * Update the configuration for the mock provider.
+     */
+    setConfig: (config: MockProviderConfig) => void;
+    /**
+     * Update or add a specific response for an RPC method.
+     */
+    setResponse: (method: string, response: unknown | ((params?: unknown[]) => unknown | Promise<unknown>)) => void;
+    /**
+     * Get all recorded requests made to the provider.
+     */
+    getRequests: () => Array<{
+        method: string;
+        params?: unknown[];
+    }>;
+    /**
+     * Clear recorded requests.
+     */
+    clearRequests: () => void;
+    /**
+     * Add an event listener (no-op in mock).
+     */
+    on: (event: string, listener: (...args: unknown[]) => void) => MockProvider;
+    /**
+     * Remove an event listener (no-op in mock).
+     */
+    removeListener: (event: string, listener: (...args: unknown[]) => void) => MockProvider;
+};
+/**
+ * Options for creating a mock environment.
+ */
+export type MockEnvironmentOptions = {
+    /**
+     * Custom provider configuration.
+     */
+    providerConfig?: MockProviderConfig;
+    /**
+     * Custom named accounts. Defaults to deployer, user1, user2.
+     */
+    namedAccounts?: Record<string, `0x${string}`>;
+    /**
+     * Chain ID. Defaults to 31337 (localhost).
+     */
+    chainId?: number;
+    /**
+     * Chain name. Defaults to 'localhost'.
+     */
+    chainName?: string;
+    /**
+     * Tags to set on the environment.
+     */
+    tags?: Record<string, boolean>;
+};
+/**
+ * Result of creating a mock environment.
+ */
+export type MockEnvironmentResult = {
+    /**
+     * The mock environment.
+     */
+    env: Environment;
+    /**
+     * The mock provider (for inspecting/updating responses).
+     */
+    provider: MockProvider;
+    /**
+     * The deployments record (for inspecting saved deployments).
+     */
+    deployments: Record<string, unknown>;
+};
+/**
+ * Creates a mock EIP-1193 provider with configurable responses.
+ *
+ * @param config - Optional configuration for custom responses
+ * @returns A mock provider that can be used in tests
+ *
+ * @example
+ * ```typescript
+ * const provider = createMockProvider({
+ *   responses: {
+ *     eth_getCode: '0x6080...', // Return deployed code
+ *     eth_getBalance: (params) => {
+ *       const address = params?.[0];
+ *       return address === '0x123...' ? '0x0' : '0x1000';
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function createMockProvider(config?: MockProviderConfig): MockProvider;
+/**
+ * Default ABI for mock artifacts.
+ */
+declare const DEFAULT_ABI: Abi;
+/**
+ * Creates a mock artifact for testing.
+ *
+ * @param name - Contract name
+ * @param abi - Optional ABI (defaults to a simple contract with constructor and getValue)
+ * @returns A mock artifact object
+ *
+ * @example
+ * ```typescript
+ * const artifact = createMockArtifact('MyContract', [
+ *   {
+ *     type: 'constructor',
+ *     inputs: [{type: 'address', name: 'owner'}],
+ *     stateMutability: 'nonpayable',
+ *   },
+ * ]);
+ * ```
+ */
+export declare function createMockArtifact<TAbi extends Abi = typeof DEFAULT_ABI>(name: string, abi?: TAbi): Artifact<TAbi>;
+export declare function createExampleArtifact(name: string, templateNumber: number): Artifact<Abi>;
+/**
+ * Creates a mock artifact with library references.
+ *
+ * @param name - Contract name
+ * @param libraryName - Name of the library to reference
+ * @param abi - Optional ABI
+ * @returns A mock artifact with library link references
+ *
+ * @example
+ * ```typescript
+ * const artifact = createMockArtifactWithLibrary('Calculator', 'MathLib');
+ * ```
+ */
+export declare function createMockArtifactWithLibrary<TAbi extends Abi = typeof DEFAULT_ABI>(name: string, libraryName: string, abi?: TAbi): Artifact<TAbi>;
+/**
+ * Creates a mock environment for testing deployments.
+ *
+ * @param options - Optional configuration
+ * @returns An object containing the environment, provider, and deployments record
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const {env, provider} = createMockEnvironment();
+ *
+ * // With custom provider responses
+ * const {env, provider} = createMockEnvironment({
+ *   providerConfig: {
+ *     responses: {
+ *       eth_getCode: '0x6080...', // Simulate deployed contract
+ *     },
+ *   },
+ * });
+ *
+ * // Update responses during test
+ * provider.setResponse('eth_getCode', '0x'); // Reset to empty
+ * ```
+ */
+export declare function createMockEnvironment(options?: MockEnvironmentOptions): MockEnvironmentResult;
+export type { Environment } from '@rocketh/core/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,340 @@
+/**
+ * @rocketh/test-utils
+ *
+ * Test utilities for rocketh packages. Provides mock environments, providers,
+ * and artifacts for testing deployment scenarios.
+ */
+// ============================================================================
+// Mock Provider
+// ============================================================================
+/**
+ * Default RPC method responses for a mock provider.
+ * These simulate a basic EVM environment.
+ */
+function getDefaultResponses(txCounter) {
+    return {
+        eth_sendTransaction: () => {
+            txCounter.value++;
+            return `0x${'0'.repeat(63)}${txCounter.value.toString(16)}`;
+        },
+        eth_sendRawTransaction: () => {
+            txCounter.value++;
+            return `0x${'1'.repeat(63)}${txCounter.value.toString(16)}`;
+        },
+        eth_getCode: () => '0x',
+        eth_getBalance: () => '0x' + BigInt('1000000000000000000000').toString(16),
+        evm_mine: () => null,
+        eth_getTransactionReceipt: (params) => ({
+            contractAddress: ('0x' + 'a'.repeat(40)),
+            status: '0x1',
+            blockNumber: '0x1',
+            blockHash: `0x${'b'.repeat(64)}`,
+            transactionHash: params?.[0] || `0x${'c'.repeat(64)}`,
+            gasUsed: '0x5208',
+        }),
+        eth_chainId: () => '0x7a69', // 31337
+        eth_blockNumber: () => '0x1',
+        eth_gasPrice: () => '0x3b9aca00', // 1 gwei
+        eth_estimateGas: () => '0x5208', // 21000
+        eth_getTransactionCount: () => '0x0',
+    };
+}
+/**
+ * Creates a mock EIP-1193 provider with configurable responses.
+ *
+ * @param config - Optional configuration for custom responses
+ * @returns A mock provider that can be used in tests
+ *
+ * @example
+ * ```typescript
+ * const provider = createMockProvider({
+ *   responses: {
+ *     eth_getCode: '0x6080...', // Return deployed code
+ *     eth_getBalance: (params) => {
+ *       const address = params?.[0];
+ *       return address === '0x123...' ? '0x0' : '0x1000';
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createMockProvider(config = {}) {
+    const txCounter = { value: 0 };
+    const defaultResponses = getDefaultResponses(txCounter);
+    let currentConfig = { ...config };
+    const requests = [];
+    const request = async ({ method, params }) => {
+        requests.push({ method, params: params });
+        // Check custom responses first
+        const customResponse = currentConfig.responses?.[method];
+        if (customResponse !== undefined) {
+            if (typeof customResponse === 'function') {
+                return customResponse(params);
+            }
+            return customResponse;
+        }
+        // Check default responses
+        const defaultResponse = defaultResponses[method];
+        if (defaultResponse !== undefined) {
+            if (typeof defaultResponse === 'function') {
+                return defaultResponse(params);
+            }
+            return defaultResponse;
+        }
+        // Handle unmocked method
+        if (currentConfig.onUnmockedMethod) {
+            return currentConfig.onUnmockedMethod(method, params);
+        }
+        console.warn(`Unmocked provider method: ${method}`);
+        return null;
+    };
+    const provider = {
+        request: request,
+        on: () => provider, // No-op event listener
+        removeListener: () => provider, // No-op event listener removal
+        setConfig: (newConfig) => {
+            currentConfig = { ...newConfig };
+        },
+        setResponse: (method, response) => {
+            if (!currentConfig.responses) {
+                currentConfig.responses = {};
+            }
+            currentConfig.responses[method] = response;
+        },
+        getRequests: () => [...requests],
+        clearRequests: () => {
+            requests.length = 0;
+        },
+    };
+    return provider;
+}
+// ============================================================================
+// Mock Artifacts
+// ============================================================================
+/**
+ * Default ABI for mock artifacts.
+ */
+const DEFAULT_ABI = [
+    {
+        type: 'function',
+        name: 'getValue',
+        inputs: [],
+        outputs: [{ type: 'uint256' }],
+        stateMutability: 'view',
+    },
+    {
+        type: 'constructor',
+        inputs: [{ type: 'uint256', name: '_initialValue' }],
+        stateMutability: 'nonpayable',
+    },
+];
+/**
+ * Creates a mock artifact for testing.
+ *
+ * @param name - Contract name
+ * @param abi - Optional ABI (defaults to a simple contract with constructor and getValue)
+ * @returns A mock artifact object
+ *
+ * @example
+ * ```typescript
+ * const artifact = createMockArtifact('MyContract', [
+ *   {
+ *     type: 'constructor',
+ *     inputs: [{type: 'address', name: 'owner'}],
+ *     stateMutability: 'nonpayable',
+ *   },
+ * ]);
+ * ```
+ */
+export function createMockArtifact(name, abi = DEFAULT_ABI) {
+    return {
+        contractName: name,
+        abi,
+        bytecode: '0x6080604052348015600f57600080fd5b50',
+        deployedBytecode: '0x6080604052',
+        linkReferences: {},
+        metadata: JSON.stringify({ compiler: { version: '0.8.20' }, settings: { optimizer: { enabled: true } } }),
+    };
+}
+export function createExampleArtifact(name, templateNumber) {
+    const mock = createMockArtifact(name);
+    if (templateNumber == 0) {
+        mock.abi = [
+            {
+                type: 'function',
+                name: 'getValue0',
+                inputs: [],
+                outputs: [{ type: 'uint256' }],
+                stateMutability: 'view',
+            },
+            {
+                type: 'constructor',
+                inputs: [{ type: 'uint256', name: '_initialValue' }],
+                stateMutability: 'nonpayable',
+            },
+        ];
+    }
+    else if (templateNumber == 1) {
+        mock.abi = [
+            {
+                type: 'function',
+                name: 'getValue1',
+                inputs: [],
+                outputs: [{ type: 'uint256' }],
+                stateMutability: 'view',
+            },
+            {
+                type: 'constructor',
+                inputs: [{ type: 'uint256', name: '_initialValue' }],
+                stateMutability: 'nonpayable',
+            },
+        ];
+    }
+    else if (templateNumber == 2) {
+        mock.abi = [
+            {
+                type: 'function',
+                name: 'getValue2',
+                inputs: [],
+                outputs: [{ type: 'uint256' }],
+                stateMutability: 'view',
+            },
+            {
+                type: 'constructor',
+                inputs: [{ type: 'uint256', name: '_initialValue' }],
+                stateMutability: 'nonpayable',
+            },
+        ];
+    }
+    else {
+        throw new Error(`no template ${templateNumber}`);
+    }
+    return mock;
+}
+/**
+ * Creates a mock artifact with library references.
+ *
+ * @param name - Contract name
+ * @param libraryName - Name of the library to reference
+ * @param abi - Optional ABI
+ * @returns A mock artifact with library link references
+ *
+ * @example
+ * ```typescript
+ * const artifact = createMockArtifactWithLibrary('Calculator', 'MathLib');
+ * ```
+ */
+export function createMockArtifactWithLibrary(name, libraryName, abi = DEFAULT_ABI) {
+    return {
+        contractName: name,
+        abi,
+        bytecode: '0x6080604052348015600f57600080fd5b50',
+        deployedBytecode: '0x6080604052',
+        linkReferences: {
+            'contracts/libraries.sol': {
+                [libraryName]: [{ length: 20, start: 50 }],
+            },
+        },
+        metadata: JSON.stringify({ compiler: { version: '0.8.20' }, settings: { optimizer: { enabled: true } } }),
+    };
+}
+// ============================================================================
+// Mock Environment
+// ============================================================================
+/**
+ * Default named accounts for testing.
+ */
+const DEFAULT_NAMED_ACCOUNTS = {
+    deployer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+    user1: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
+    user2: '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC',
+};
+/**
+ * Creates a mock environment for testing deployments.
+ *
+ * @param options - Optional configuration
+ * @returns An object containing the environment, provider, and deployments record
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const {env, provider} = createMockEnvironment();
+ *
+ * // With custom provider responses
+ * const {env, provider} = createMockEnvironment({
+ *   providerConfig: {
+ *     responses: {
+ *       eth_getCode: '0x6080...', // Simulate deployed contract
+ *     },
+ *   },
+ * });
+ *
+ * // Update responses during test
+ * provider.setResponse('eth_getCode', '0x'); // Reset to empty
+ * ```
+ */
+export function createMockEnvironment(options = {}) {
+    const deployments = {};
+    const provider = createMockProvider(options.providerConfig);
+    const namedAccounts = options.namedAccounts || DEFAULT_NAMED_ACCOUNTS;
+    const chainId = options.chainId ?? 31337;
+    const chainName = options.chainName ?? 'localhost';
+    const addressSigners = {};
+    for (const address of Object.values(namedAccounts)) {
+        addressSigners[address] = {
+            type: 'remote',
+            signer: provider,
+        };
+    }
+    const env = {
+        namedAccounts: namedAccounts,
+        network: {
+            chain: {
+                id: chainId,
+                name: chainName,
+                nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+            },
+            provider,
+            deterministicDeployment: {
+                create2: {
+                    factory: '0x4e59b44847b379578588920cA78FbF26c0B4956C',
+                    deployer: '0x3f39e218c8a8b13d2488ccf2a3b7d0e3c0c8e8d9',
+                    signedTx: '0xf8a5',
+                    funding: '100000000000000000',
+                },
+                create3: {
+                    factory: '0x000000000004d4f168daE7DB3C610F408eE22F57',
+                    salt: '0x5361109ca02853ca8e22046b7125306d9ec4ae4cdecc393c567b6be861df3db6',
+                    bytecode: '0x6080604052348015600f57600080fd5b506103ca8061001f6000396000f3fe6080604052600436106100295760003560e01c8063360d0fad1461002e5780639881d19514610077575b600080fd5b34801561003a57600080fd5b5061004e610049366004610228565b61008a565b60405173ffffffffffffffffffffffffffffffffffffffff909116815260200160405180910390f35b61004e61008536600461029c565b6100ee565b6040517fffffffffffffffffffffffffffffffffffffffff000000000000000000000000606084901b166020820152603481018290526000906054016040516020818303038152906040528051906020012091506100e78261014c565b9392505050565b6040517fffffffffffffffffffffffffffffffffffffffff0000000000000000000000003360601b166020820152603481018290526000906054016040516020818303038152906040528051906020012091506100e734848461015e565b600061015882306101ce565b92915050565b60006f67363d3d37363d34f03d5260086018f3600052816010806000f58061018e5763301164256000526004601cfd5b8060145261d69460005260016034536017601e20915060008085516020870188855af1823b026101c65763301164256000526004601cfd5b509392505050565b60006040518260005260ff600b53836020527f21c35dbe1b344a2488cf3321d6ce542f8e9f305544ff09e4993a62319a497c1f6040526055600b20601452806040525061d694600052600160345350506017601e20919050565b6000806040838503121561023b57600080fd5b823573ffffffffffffffffffffffffffffffffffffffff8116811461025f57600080fd5b946020939093013593505050565b7f4e487b7100000000000000000000000000000000000000000000000000000000600052604160045260246000fd5b600080604083850312156102af57600080fd5b823567ffffffffffffffff8111156102c657600080fd5b8301601f810185136102d757600080fd5b803567ffffffffffffffff8111156102f1576102f161026d565b6040517fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe0603f7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe0601f8501160116810181811067ffffffffffffffff8211171561035d5761035d61026d565b60405281815282820160200187101561037557600080fd5b816020840160208301376000602092820183015296940135945050505056fea264697066735822122059dcc5dc6453397d13ff28021e28472a80a45bbd97f3135f69bd2650773aeb0164736f6c634300081a0033',
+                    proxyBytecode: '0x67363d3d37363d34f03d5260086018f3',
+                },
+            },
+        },
+        addressSigners,
+        tags: {
+            test: true,
+            'auto-mine': true,
+            ...(options.tags || {}),
+        },
+        get: (name) => deployments[name],
+        getOrNull: (name) => deployments[name] || null,
+        save: async (name, deployment) => {
+            deployments[name] = deployment;
+            return deployment;
+        },
+        savePendingDeployment: async (pendingDeployment) => {
+            const pd = pendingDeployment;
+            return {
+                ...pd.partialDeployment,
+                address: pd.expectedAddress || ('0x' + '1'.repeat(40)),
+                newlyDeployed: true,
+            };
+        },
+        savePendingExecution: async () => { },
+        showMessage: (message) => {
+            // Could be configured to capture messages for testing
+        },
+    };
+    return { env, provider, deployments };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rocketh/test-utils",
+  "version": "0.0.2",
+  "description": "Test utilities for rocketh packages",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "eip-1193": "^0.6.5",
+    "viem": "^2.44.4",
+    "@rocketh/core": "0.17.9"
+  },
+  "devDependencies": {
+    "as-soon": "^0.1.4",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "as-soon -w src pnpm build"
+  }
+}

package/src/index.ts

@@ -0,0 +1,488 @@
+/**
+ * @rocketh/test-utils
+ *
+ * Test utilities for rocketh packages. Provides mock environments, providers,
+ * and artifacts for testing deployment scenarios.
+ */
+
+import type {Abi, Artifact, Environment} from '@rocketh/core/types';
+import type {EIP1193Provider} from 'eip-1193';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Configuration for mock provider responses.
+ * Allows tests to specify custom return values for specific RPC methods.
+ */
+export type MockProviderConfig = {
+	/**
+	 * Override responses for specific RPC methods.
+	 * Can be a static value or a function that receives params and returns a value.
+	 */
+	responses?: {
+		[method: string]: unknown | ((params?: unknown[]) => unknown | Promise<unknown>);
+	};
+
+	/**
+	 * Called when an unmocked method is requested.
+	 * If not provided, returns null and logs a warning.
+	 */
+	onUnmockedMethod?: (method: string, params?: unknown[]) => unknown | Promise<unknown>;
+};
+
+/**
+ * A mock EIP-1193 provider with configurable responses.
+ */
+export type MockProvider = EIP1193Provider & {
+	/**
+	 * Update the configuration for the mock provider.
+	 */
+	setConfig: (config: MockProviderConfig) => void;
+
+	/**
+	 * Update or add a specific response for an RPC method.
+	 */
+	setResponse: (method: string, response: unknown | ((params?: unknown[]) => unknown | Promise<unknown>)) => void;
+
+	/**
+	 * Get all recorded requests made to the provider.
+	 */
+	getRequests: () => Array<{method: string; params?: unknown[]}>;
+
+	/**
+	 * Clear recorded requests.
+	 */
+	clearRequests: () => void;
+
+	/**
+	 * Add an event listener (no-op in mock).
+	 */
+	on: (event: string, listener: (...args: unknown[]) => void) => MockProvider;
+
+	/**
+	 * Remove an event listener (no-op in mock).
+	 */
+	removeListener: (event: string, listener: (...args: unknown[]) => void) => MockProvider;
+};
+
+/**
+ * Options for creating a mock environment.
+ */
+export type MockEnvironmentOptions = {
+	/**
+	 * Custom provider configuration.
+	 */
+	providerConfig?: MockProviderConfig;
+
+	/**
+	 * Custom named accounts. Defaults to deployer, user1, user2.
+	 */
+	namedAccounts?: Record<string, `0x${string}`>;
+
+	/**
+	 * Chain ID. Defaults to 31337 (localhost).
+	 */
+	chainId?: number;
+
+	/**
+	 * Chain name. Defaults to 'localhost'.
+	 */
+	chainName?: string;
+
+	/**
+	 * Tags to set on the environment.
+	 */
+	tags?: Record<string, boolean>;
+};
+
+/**
+ * Result of creating a mock environment.
+ */
+export type MockEnvironmentResult = {
+	/**
+	 * The mock environment.
+	 */
+	env: Environment;
+
+	/**
+	 * The mock provider (for inspecting/updating responses).
+	 */
+	provider: MockProvider;
+
+	/**
+	 * The deployments record (for inspecting saved deployments).
+	 */
+	deployments: Record<string, unknown>;
+};
+
+// ============================================================================
+// Mock Provider
+// ============================================================================
+
+/**
+ * Default RPC method responses for a mock provider.
+ * These simulate a basic EVM environment.
+ */
+function getDefaultResponses(txCounter: {
+	value: number;
+}): Record<string, unknown | ((params?: unknown[]) => unknown | Promise<unknown>)> {
+	return {
+		eth_sendTransaction: () => {
+			txCounter.value++;
+			return `0x${'0'.repeat(63)}${txCounter.value.toString(16)}` as `0x${string}`;
+		},
+		eth_sendRawTransaction: () => {
+			txCounter.value++;
+			return `0x${'1'.repeat(63)}${txCounter.value.toString(16)}` as `0x${string}`;
+		},
+		eth_getCode: () => '0x',
+		eth_getBalance: () => '0x' + BigInt('1000000000000000000000').toString(16),
+		evm_mine: () => null,
+		eth_getTransactionReceipt: (params?: unknown[]) => ({
+			contractAddress: ('0x' + 'a'.repeat(40)) as `0x${string}`,
+			status: '0x1',
+			blockNumber: '0x1',
+			blockHash: `0x${'b'.repeat(64)}`,
+			transactionHash: (params?.[0] as string) || `0x${'c'.repeat(64)}`,
+			gasUsed: '0x5208',
+		}),
+		eth_chainId: () => '0x7a69', // 31337
+		eth_blockNumber: () => '0x1',
+		eth_gasPrice: () => '0x3b9aca00', // 1 gwei
+		eth_estimateGas: () => '0x5208', // 21000
+		eth_getTransactionCount: () => '0x0',
+	};
+}
+
+/**
+ * Creates a mock EIP-1193 provider with configurable responses.
+ *
+ * @param config - Optional configuration for custom responses
+ * @returns A mock provider that can be used in tests
+ *
+ * @example
+ * ```typescript
+ * const provider = createMockProvider({
+ *   responses: {
+ *     eth_getCode: '0x6080...', // Return deployed code
+ *     eth_getBalance: (params) => {
+ *       const address = params?.[0];
+ *       return address === '0x123...' ? '0x0' : '0x1000';
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createMockProvider(config: MockProviderConfig = {}): MockProvider {
+	const txCounter = {value: 0};
+	const defaultResponses = getDefaultResponses(txCounter);
+	let currentConfig = {...config};
+	const requests: Array<{method: string; params?: unknown[]}> = [];
+
+	const request = async ({method, params}: {method: string; params?: unknown[]}): Promise<unknown> => {
+		requests.push({method, params: params as unknown[]});
+
+		// Check custom responses first
+		const customResponse = currentConfig.responses?.[method];
+		if (customResponse !== undefined) {
+			if (typeof customResponse === 'function') {
+				return customResponse(params as unknown[]);
+			}
+			return customResponse;
+		}
+
+		// Check default responses
+		const defaultResponse = defaultResponses[method];
+		if (defaultResponse !== undefined) {
+			if (typeof defaultResponse === 'function') {
+				return defaultResponse(params as unknown[]);
+			}
+			return defaultResponse;
+		}
+
+		// Handle unmocked method
+		if (currentConfig.onUnmockedMethod) {
+			return currentConfig.onUnmockedMethod(method, params as unknown[]);
+		}
+
+		console.warn(`Unmocked provider method: ${method}`);
+		return null;
+	};
+
+	const provider: MockProvider = {
+		request: request as EIP1193Provider['request'],
+		on: () => provider, // No-op event listener
+		removeListener: () => provider, // No-op event listener removal
+		setConfig: (newConfig: MockProviderConfig) => {
+			currentConfig = {...newConfig};
+		},
+		setResponse: (method: string, response: unknown | ((params?: unknown[]) => unknown | Promise<unknown>)) => {
+			if (!currentConfig.responses) {
+				currentConfig.responses = {};
+			}
+			currentConfig.responses[method] = response;
+		},
+		getRequests: () => [...requests],
+		clearRequests: () => {
+			requests.length = 0;
+		},
+	};
+	return provider;
+}
+
+// ============================================================================
+// Mock Artifacts
+// ============================================================================
+
+/**
+ * Default ABI for mock artifacts.
+ */
+const DEFAULT_ABI: Abi = [
+	{
+		type: 'function',
+		name: 'getValue',
+		inputs: [],
+		outputs: [{type: 'uint256'}],
+		stateMutability: 'view',
+	},
+	{
+		type: 'constructor',
+		inputs: [{type: 'uint256', name: '_initialValue'}],
+		stateMutability: 'nonpayable',
+	},
+] as const;
+
+/**
+ * Creates a mock artifact for testing.
+ *
+ * @param name - Contract name
+ * @param abi - Optional ABI (defaults to a simple contract with constructor and getValue)
+ * @returns A mock artifact object
+ *
+ * @example
+ * ```typescript
+ * const artifact = createMockArtifact('MyContract', [
+ *   {
+ *     type: 'constructor',
+ *     inputs: [{type: 'address', name: 'owner'}],
+ *     stateMutability: 'nonpayable',
+ *   },
+ * ]);
+ * ```
+ */
+export function createMockArtifact<TAbi extends Abi = typeof DEFAULT_ABI>(
+	name: string,
+	abi: TAbi = DEFAULT_ABI as TAbi,
+): Artifact<TAbi> {
+	return {
+		contractName: name,
+		abi,
+		bytecode: '0x6080604052348015600f57600080fd5b50' as `0x${string}`,
+		deployedBytecode: '0x6080604052' as `0x${string}`,
+		linkReferences: {},
+		metadata: JSON.stringify({compiler: {version: '0.8.20'}, settings: {optimizer: {enabled: true}}}),
+	};
+}
+
+export function createExampleArtifact(name: string, templateNumber: number): Artifact<Abi> {
+	const mock = createMockArtifact(name);
+	if (templateNumber == 0) {
+		(mock as any).abi = [
+			{
+				type: 'function',
+				name: 'getValue0',
+				inputs: [],
+				outputs: [{type: 'uint256'}],
+				stateMutability: 'view',
+			},
+			{
+				type: 'constructor',
+				inputs: [{type: 'uint256', name: '_initialValue'}],
+				stateMutability: 'nonpayable',
+			},
+		];
+	} else if (templateNumber == 1) {
+		(mock as any).abi = [
+			{
+				type: 'function',
+				name: 'getValue1',
+				inputs: [],
+				outputs: [{type: 'uint256'}],
+				stateMutability: 'view',
+			},
+			{
+				type: 'constructor',
+				inputs: [{type: 'uint256', name: '_initialValue'}],
+				stateMutability: 'nonpayable',
+			},
+		];
+	} else if (templateNumber == 2) {
+		(mock as any).abi = [
+			{
+				type: 'function',
+				name: 'getValue2',
+				inputs: [],
+				outputs: [{type: 'uint256'}],
+				stateMutability: 'view',
+			},
+			{
+				type: 'constructor',
+				inputs: [{type: 'uint256', name: '_initialValue'}],
+				stateMutability: 'nonpayable',
+			},
+		];
+	} else {
+		throw new Error(`no template ${templateNumber}`);
+	}
+
+	return mock;
+}
+
+/**
+ * Creates a mock artifact with library references.
+ *
+ * @param name - Contract name
+ * @param libraryName - Name of the library to reference
+ * @param abi - Optional ABI
+ * @returns A mock artifact with library link references
+ *
+ * @example
+ * ```typescript
+ * const artifact = createMockArtifactWithLibrary('Calculator', 'MathLib');
+ * ```
+ */
+export function createMockArtifactWithLibrary<TAbi extends Abi = typeof DEFAULT_ABI>(
+	name: string,
+	libraryName: string,
+	abi: TAbi = DEFAULT_ABI as TAbi,
+): Artifact<TAbi> {
+	return {
+		contractName: name,
+		abi,
+		bytecode: '0x6080604052348015600f57600080fd5b50' as `0x${string}`,
+		deployedBytecode: '0x6080604052' as `0x${string}`,
+		linkReferences: {
+			'contracts/libraries.sol': {
+				[libraryName]: [{length: 20, start: 50}],
+			},
+		},
+		metadata: JSON.stringify({compiler: {version: '0.8.20'}, settings: {optimizer: {enabled: true}}}),
+	};
+}
+
+// ============================================================================
+// Mock Environment
+// ============================================================================
+
+/**
+ * Default named accounts for testing.
+ */
+const DEFAULT_NAMED_ACCOUNTS: Record<string, `0x${string}`> = {
+	deployer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+	user1: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
+	user2: '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC',
+};
+
+/**
+ * Creates a mock environment for testing deployments.
+ *
+ * @param options - Optional configuration
+ * @returns An object containing the environment, provider, and deployments record
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const {env, provider} = createMockEnvironment();
+ *
+ * // With custom provider responses
+ * const {env, provider} = createMockEnvironment({
+ *   providerConfig: {
+ *     responses: {
+ *       eth_getCode: '0x6080...', // Simulate deployed contract
+ *     },
+ *   },
+ * });
+ *
+ * // Update responses during test
+ * provider.setResponse('eth_getCode', '0x'); // Reset to empty
+ * ```
+ */
+export function createMockEnvironment(options: MockEnvironmentOptions = {}): MockEnvironmentResult {
+	const deployments: Record<string, unknown> = {};
+	const provider = createMockProvider(options.providerConfig);
+	const namedAccounts = options.namedAccounts || DEFAULT_NAMED_ACCOUNTS;
+	const chainId = options.chainId ?? 31337;
+	const chainName = options.chainName ?? 'localhost';
+
+	const addressSigners: Record<string, {type: 'remote'; signer: MockProvider}> = {};
+	for (const address of Object.values(namedAccounts)) {
+		addressSigners[address] = {
+			type: 'remote',
+			signer: provider,
+		};
+	}
+
+	const env: Environment = {
+		namedAccounts: namedAccounts as Record<string, `0x${string}`>,
+		network: {
+			chain: {
+				id: chainId,
+				name: chainName,
+				nativeCurrency: {name: 'Ether', symbol: 'ETH', decimals: 18},
+			},
+			provider,
+			deterministicDeployment: {
+				create2: {
+					factory: '0x4e59b44847b379578588920cA78FbF26c0B4956C' as `0x${string}`,
+					deployer: '0x3f39e218c8a8b13d2488ccf2a3b7d0e3c0c8e8d9' as `0x${string}`,
+					signedTx: '0xf8a5' as `0x${string}`,
+					funding: '100000000000000000',
+				},
+				create3: {
+					factory: '0x000000000004d4f168daE7DB3C610F408eE22F57',
+					salt: '0x5361109ca02853ca8e22046b7125306d9ec4ae4cdecc393c567b6be861df3db6',
+					bytecode:
+						'0x6080604052348015600f57600080fd5b506103ca8061001f6000396000f3fe6080604052600436106100295760003560e01c8063360d0fad1461002e5780639881d19514610077575b600080fd5b34801561003a57600080fd5b5061004e610049366004610228565b61008a565b60405173ffffffffffffffffffffffffffffffffffffffff909116815260200160405180910390f35b61004e61008536600461029c565b6100ee565b6040517fffffffffffffffffffffffffffffffffffffffff000000000000000000000000606084901b166020820152603481018290526000906054016040516020818303038152906040528051906020012091506100e78261014c565b9392505050565b6040517fffffffffffffffffffffffffffffffffffffffff0000000000000000000000003360601b166020820152603481018290526000906054016040516020818303038152906040528051906020012091506100e734848461015e565b600061015882306101ce565b92915050565b60006f67363d3d37363d34f03d5260086018f3600052816010806000f58061018e5763301164256000526004601cfd5b8060145261d69460005260016034536017601e20915060008085516020870188855af1823b026101c65763301164256000526004601cfd5b509392505050565b60006040518260005260ff600b53836020527f21c35dbe1b344a2488cf3321d6ce542f8e9f305544ff09e4993a62319a497c1f6040526055600b20601452806040525061d694600052600160345350506017601e20919050565b6000806040838503121561023b57600080fd5b823573ffffffffffffffffffffffffffffffffffffffff8116811461025f57600080fd5b946020939093013593505050565b7f4e487b7100000000000000000000000000000000000000000000000000000000600052604160045260246000fd5b600080604083850312156102af57600080fd5b823567ffffffffffffffff8111156102c657600080fd5b8301601f810185136102d757600080fd5b803567ffffffffffffffff8111156102f1576102f161026d565b6040517fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe0603f7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe0601f8501160116810181811067ffffffffffffffff8211171561035d5761035d61026d565b60405281815282820160200187101561037557600080fd5b816020840160208301376000602092820183015296940135945050505056fea264697066735822122059dcc5dc6453397d13ff28021e28472a80a45bbd97f3135f69bd2650773aeb0164736f6c634300081a0033',
+					proxyBytecode: '0x67363d3d37363d34f03d5260086018f3',
+				},
+			},
+		},
+		addressSigners,
+		tags: {
+			test: true,
+			'auto-mine': true,
+			...(options.tags || {}),
+		},
+		get: <T>(name: string) => deployments[name] as T,
+		getOrNull: <T>(name: string) => (deployments[name] as T) || null,
+		save: async <T>(name: string, deployment: T) => {
+			deployments[name] = deployment;
+			return deployment as T;
+		},
+		savePendingDeployment: async (pendingDeployment: unknown) => {
+			const pd = pendingDeployment as {
+				partialDeployment: Record<string, unknown>;
+				expectedAddress?: `0x${string}`;
+			};
+			return {
+				...pd.partialDeployment,
+				address: pd.expectedAddress || (('0x' + '1'.repeat(40)) as `0x${string}`),
+				newlyDeployed: true,
+			};
+		},
+		savePendingExecution: async () => {},
+		showMessage: (message: string) => {
+			// Could be configured to capture messages for testing
+		},
+	} as unknown as Environment;
+
+	return {env, provider, deployments};
+}
+
+// ============================================================================
+// Re-exports
+// ============================================================================
+
+export type {Environment} from '@rocketh/core/types';