@ohos-ports/azle 0.33.0-beta.0

package/src/stable/test/global_state.ts

@@ -0,0 +1,202 @@
+import { execSync } from 'node:child_process';
+
+import { expect } from '@jest/globals';
+
+import { getDfxRoot } from '#utils/dfx_root';
+
+import { getCanisterNames } from './canister_names';
+
+type GlobalState = {
+    azleRejectCallbacksLen: number;
+    azleResolveCallbacksLen: number;
+    azleTimerCallbacksLen: number;
+    azleInterCanisterCallFuturesLen: number;
+    azleActionsLen: number;
+    azleIsJobQueueEmpty: boolean;
+};
+
+/**
+ * Checks the global state of all canisters defined in the dfx.json file.
+ *
+ * @remarks
+ *
+ * It checks the state recursively with exponential backoff, waiting for critical states to clear.
+ * If critical states are not clear after a certain amount of time, it will stop checking with a jest failure.
+ */
+export async function runGlobalStateChecks(): Promise<void> {
+    const canisterNames = await getCanisterNames();
+
+    for (const canisterName of canisterNames) {
+        await checkCanisterGlobalStateWithRetry(canisterName);
+    }
+}
+
+async function checkCanisterGlobalStateWithRetry(
+    canisterName: string
+): Promise<void> {
+    const maxWaitTimePower = 8; // 2^8 = 256 seconds
+
+    const { finalGlobalState, previousActionsLen } =
+        await checkCanisterGlobalStateRecursively(
+            canisterName,
+            {
+                checkCount: 0,
+                currentWaitTimePower: 0,
+                totalWaitTime: 0,
+                previousActionsLen: undefined
+            },
+            maxWaitTimePower
+        );
+
+    expect(areCriticalStatesClear(finalGlobalState, previousActionsLen)).toBe(
+        true
+    );
+}
+
+async function checkCanisterGlobalStateRecursively(
+    canisterName: string,
+    state: {
+        checkCount: number;
+        currentWaitTimePower: number;
+        totalWaitTime: number;
+        previousActionsLen: number | undefined;
+    },
+    maxWaitTimePower: number
+): Promise<{
+    finalGlobalState: GlobalState;
+    previousActionsLen: number | undefined;
+}> {
+    console.info(
+        `Global state check ${state.checkCount} for canister ${canisterName}`
+    );
+
+    const globalState = await getCanisterGlobalState(canisterName);
+
+    console.info(`Check ${state.checkCount} results:`, globalState);
+
+    const criticalStatesClear = areCriticalStatesClear(
+        globalState,
+        state.previousActionsLen
+    );
+
+    if (criticalStatesClear === true && state.checkCount >= 2) {
+        return {
+            finalGlobalState: globalState,
+            previousActionsLen: state.previousActionsLen
+        };
+    }
+
+    const hasReachedMaxWaitTime =
+        state.currentWaitTimePower >= maxWaitTimePower;
+
+    if (hasReachedMaxWaitTime === true) {
+        return {
+            finalGlobalState: globalState,
+            previousActionsLen: state.previousActionsLen
+        };
+    }
+
+    const currentWaitTimeMs = Math.pow(2, state.currentWaitTimePower) * 1_000;
+
+    console.info(
+        `Waiting ${currentWaitTimeMs}ms (2^${state.currentWaitTimePower} seconds) before next check (total wait: ${state.totalWaitTime}ms)`
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, currentWaitTimeMs));
+
+    const nextState = {
+        checkCount: state.checkCount + 1,
+        currentWaitTimePower: state.currentWaitTimePower + 1,
+        totalWaitTime: state.totalWaitTime + currentWaitTimeMs,
+        previousActionsLen: globalState.azleActionsLen
+    };
+
+    return checkCanisterGlobalStateRecursively(
+        canisterName,
+        nextState,
+        maxWaitTimePower
+    );
+}
+
+async function getCanisterGlobalState(
+    canisterName: string
+): Promise<GlobalState> {
+    const azleRejectCallbacksLen = Number(
+        execSync(
+            `dfx canister call ${canisterName} _azle_reject_callbacks_len --output json`,
+            {
+                cwd: getDfxRoot(),
+                encoding: 'utf-8'
+            }
+        ).trim()
+    );
+    const azleResolveCallbacksLen = Number(
+        execSync(
+            `dfx canister call ${canisterName} _azle_resolve_callbacks_len --output json`,
+            {
+                cwd: getDfxRoot(),
+                encoding: 'utf-8'
+            }
+        ).trim()
+    );
+    const azleTimerCallbacksLen = Number(
+        execSync(
+            `dfx canister call ${canisterName} _azle_timer_callbacks_len --output json`,
+            {
+                cwd: getDfxRoot(),
+                encoding: 'utf-8'
+            }
+        ).trim()
+    );
+    const azleInterCanisterCallFuturesLen = Number(
+        execSync(
+            `dfx canister call ${canisterName} _azle_inter_canister_call_futures_len --output json`,
+            {
+                cwd: getDfxRoot(),
+                encoding: 'utf-8'
+            }
+        ).trim()
+    );
+    const azleActionsLen = Number(
+        execSync(
+            `dfx canister call ${canisterName} _azle_actions_len --output json`,
+            {
+                cwd: getDfxRoot(),
+                encoding: 'utf-8'
+            }
+        ).trim()
+    );
+    const azleIsJobQueueEmpty = JSON.parse(
+        execSync(
+            `dfx canister call ${canisterName} _azle_is_job_queue_empty --output json`,
+            { cwd: getDfxRoot(), encoding: 'utf-8' }
+        ).trim()
+    ) as boolean;
+
+    return {
+        azleRejectCallbacksLen,
+        azleResolveCallbacksLen,
+        azleTimerCallbacksLen,
+        azleInterCanisterCallFuturesLen,
+        azleActionsLen,
+        azleIsJobQueueEmpty
+    };
+}
+
+function areCriticalStatesClear(
+    globalState: GlobalState,
+    previousActionsLen: number | undefined
+): boolean {
+    const globalActionsLengthUnchanged =
+        previousActionsLen === undefined ||
+        globalState.azleActionsLen === previousActionsLen;
+
+    return (
+        globalState.azleRejectCallbacksLen === 0 &&
+        globalState.azleResolveCallbacksLen === 0 &&
+        globalState.azleTimerCallbacksLen === 0 &&
+        globalState.azleInterCanisterCallFuturesLen === 0 &&
+        globalState.azleIsJobQueueEmpty === true &&
+        globalActionsLengthUnchanged === true
+    );
+}

package/src/stable/test/index.ts

@@ -0,0 +1,274 @@
+import * as dns from 'node:dns';
+dns.setDefaultResultOrder('ipv4first');
+
+import { describe, expect, test } from '@jest/globals';
+import { DEFAULT_EXPECTED_ERRORS } from 'cuzz';
+
+import { execSyncPretty } from '#utils/exec_sync_pretty';
+
+import { recordsBenchmarksForCanisters } from './benchmarks';
+import { getCanisterNames } from './canister_names';
+import { getCuzzConfig, runFuzzTests } from './fuzz';
+import { runGlobalStateChecks } from './global_state';
+import {
+    checkMemoryChanges,
+    startingMemoryState,
+    takeMemorySnapshot
+} from './memory_state';
+
+export type Test = () => void;
+
+export { getCanisterNames } from './canister_names';
+export { getCanisterActor } from './get_canister_actor';
+export { expect } from '@jest/globals';
+export { defaultPropTestParams } from '#test/property/default_prop_test_params';
+
+export function runTests(tests: Test): void {
+    const {
+        shouldRunTests,
+        shouldCheckGlobalStateAfterTests,
+        shouldCheckMemoryStateAfterTests,
+        shouldRunTypeChecks,
+        shouldRecordBenchmarks,
+        shouldFuzz,
+        shouldCheckGlobalStateAfterFuzzTests
+    } = processEnvVars();
+
+    (shouldRunTests === true ? describe : describe.skip)(
+        `correctness tests`,
+        () => {
+            (shouldCheckMemoryStateAfterTests === true ? please : please.skip)(
+                'snapshot the canister memory size and heap allocation for all canisters before correctness tests',
+                async () => {
+                    const snapshot = await takeMemorySnapshot();
+
+                    startingMemoryState.correctness.heapAllocations =
+                        snapshot.heapAllocations;
+                    startingMemoryState.correctness.memorySizes =
+                        snapshot.memorySizes;
+                }
+            );
+
+            tests();
+
+            (shouldCheckGlobalStateAfterTests === true ? it : it.skip)(
+                'checks that all internal global state variables for all canisters are empty',
+                runGlobalStateChecks
+            );
+
+            (shouldCheckMemoryStateAfterTests === true ? it : it.skip)(
+                'checks the canister memory size and heap allocation for all canisters after correctness tests',
+                async () => {
+                    await checkMemoryChanges(
+                        startingMemoryState.correctness.heapAllocations,
+                        startingMemoryState.correctness.memorySizes
+                    );
+                }
+            );
+
+            (shouldRunTypeChecks === true ? it : it.skip)(
+                'checks TypeScript types',
+                async () => {
+                    const typeCheckCommand = `npm exec --offline tsc -- --skipLibCheck`; // TODO: remove skipLibCheck once https://github.com/demergent-labs/azle/issues/2690 is resolved
+                    try {
+                        execSyncPretty(typeCheckCommand, {
+                            stdio: 'inherit'
+                        });
+                    } catch {
+                        expect('Type checking failed').toBe(
+                            'Type checking to pass'
+                        );
+                    }
+                }
+            );
+        }
+    );
+
+    (shouldRecordBenchmarks === true ? describe : describe.skip)(
+        `benchmarks`,
+        () => {
+            it('records benchmarks for all canisters', async () => {
+                const canisterNames = await getCanisterNames();
+                await recordsBenchmarksForCanisters(canisterNames);
+            });
+        }
+    );
+
+    (shouldFuzz === true && process.env.AZLE_EXPERIMENTAL !== 'true'
+        ? describe
+        : describe.skip)('fuzz tests', () => {
+        please(
+            'snapshot the canister memory size and heap allocation for all canisters before fuzz tests',
+            async () => {
+                const snapshot = await takeMemorySnapshot();
+                startingMemoryState.fuzz.heapAllocations =
+                    snapshot.heapAllocations;
+                startingMemoryState.fuzz.memorySizes = snapshot.memorySizes;
+            }
+        );
+
+        it('runs fuzz tests', runFuzzTests);
+
+        (shouldCheckGlobalStateAfterFuzzTests === true ? it : it.skip)(
+            'checks that all internal global state variables for all canisters are empty',
+            async () => {
+                while (true) {
+                    try {
+                        await runGlobalStateChecks();
+                    } catch (error: any) {
+                        if (
+                            isExpectedError(error, DEFAULT_EXPECTED_ERRORS) ===
+                            true
+                        ) {
+                            continue;
+                        }
+
+                        throw error;
+                    }
+                    break;
+                }
+            }
+        );
+
+        it('checks the canister memory size and heap allocation for all canisters after fuzz tests', async () => {
+            await checkMemoryChanges(
+                startingMemoryState.fuzz.heapAllocations,
+                startingMemoryState.fuzz.memorySizes
+            );
+        });
+    });
+}
+
+export function wait(name: string, delay: number): void {
+    runWait(test, name, delay);
+}
+
+wait.skip = (name: string, delay: number): void =>
+    runWait(test.skip, name, delay);
+wait.only = (name: string, delay: number): void =>
+    runWait(test.only, name, delay);
+
+export function please(name: string, fn: () => void | Promise<void>): void {
+    test(`please ${name}`, async () => {
+        console.info(`Preparing: ${name}`);
+        await fn();
+    });
+}
+please.each = test.each;
+please.only = test.only;
+please.skip = test.skip;
+
+export function it(name: string, fn: () => void | Promise<void>): void {
+    test(`it ${name}`, async () => {
+        console.info(`Testing: ${name}`);
+        await fn();
+    });
+}
+it.each = test.each;
+it.only = test.only;
+it.skip = test.skip;
+
+function processEnvVars(): {
+    shouldRunTests: boolean;
+    shouldCheckGlobalStateAfterTests: boolean;
+    shouldCheckMemoryStateAfterTests: boolean;
+    shouldRunTypeChecks: boolean;
+    shouldRecordBenchmarks: boolean;
+    shouldFuzz: boolean;
+    shouldCheckGlobalStateAfterFuzzTests: boolean;
+} {
+    const runTests = process.env.AZLE_RUN_TESTS ?? 'true';
+    const checkGlobalStateAfterTests =
+        process.env.AZLE_CHECK_GLOBAL_STATE_AFTER_TESTS ?? 'true';
+    const checkMemoryStateAfterTests =
+        process.env.AZLE_CHECK_MEMORY_STATE_AFTER_TESTS ?? 'true';
+    const runTypeChecks = process.env.AZLE_RUN_TYPE_CHECKS ?? 'true';
+    const recordBenchmarks = process.env.AZLE_RECORD_BENCHMARKS ?? 'false';
+    const fuzz = process.env.AZLE_FUZZ ?? 'false';
+    const checkGlobalStateAfterFuzzTests =
+        process.env.AZLE_CHECK_GLOBAL_STATE_AFTER_FUZZ_TESTS ?? 'true';
+
+    const hasOnly = [
+        runTests,
+        runTypeChecks,
+        fuzz,
+        checkGlobalStateAfterTests,
+        checkMemoryStateAfterTests,
+        checkGlobalStateAfterFuzzTests
+    ].includes('only');
+
+    const shouldRunTests = shouldRun(runTests, hasOnly, true);
+    const shouldCheckGlobalStateAfterTests = shouldRun(
+        checkGlobalStateAfterTests,
+        hasOnly,
+        true
+    );
+    const shouldCheckMemoryStateAfterTests = shouldRun(
+        checkMemoryStateAfterTests,
+        hasOnly,
+        true
+    );
+    const shouldRunTypeChecks = shouldRun(runTypeChecks, hasOnly, true);
+    const shouldRecordBenchmarks = recordBenchmarks === 'true' && !hasOnly;
+    const cuzzConfig = getCuzzConfig();
+    const shouldFuzz =
+        cuzzConfig.skip !== true &&
+        typeof cuzzConfig.skip !== 'string' &&
+        shouldRun(fuzz, hasOnly, false);
+    const shouldCheckGlobalStateAfterFuzzTests =
+        shouldFuzz === true &&
+        shouldRun(checkGlobalStateAfterFuzzTests, hasOnly, true);
+
+    return {
+        shouldRunTests,
+        shouldRunTypeChecks,
+        shouldRecordBenchmarks,
+        shouldFuzz,
+        shouldCheckGlobalStateAfterTests,
+        shouldCheckMemoryStateAfterTests,
+        shouldCheckGlobalStateAfterFuzzTests
+    };
+}
+
+function shouldRun(
+    envVar: string,
+    hasOnly: boolean,
+    runByDefault: boolean
+): boolean {
+    if (hasOnly === true) {
+        return envVar === 'only';
+    }
+
+    if (runByDefault === true) {
+        return envVar !== 'false';
+    }
+
+    return envVar === 'true';
+}
+
+function runWait(
+    testFn: typeof test | typeof test.only | typeof test.skip,
+    name: string,
+    delay: number
+): void {
+    testFn(`wait ${name}`, createWait(name, delay), delay + 1_000);
+}
+
+function createWait(name: string, delay: number): () => Promise<void> {
+    return async () => {
+        console.info(`Waiting: ${delay} milliseconds ${name}`);
+        await new Promise((resolve) => {
+            setTimeout(resolve, delay);
+        });
+    };
+}
+
+/**
+ * Checks if an error matches any of a list of expected error messages.
+ */
+function isExpectedError(error: Error, expectedErrors: string[]): boolean {
+    return expectedErrors.some((expected) => {
+        const regex = new RegExp(expected);
+        return regex.test(error.message) || regex.test(error.toString());
+    });
+}

package/src/stable/test/memory_state.ts

@@ -0,0 +1,187 @@
+import { execSync } from 'node:child_process';
+
+import { expect } from '@jest/globals';
+import { formatMemorySize, getRawMemorySize } from 'cuzz';
+
+import { getCanisterConfig } from '#build/utils/get_canister_config';
+import { getDfxRoot } from '#utils/dfx_root';
+
+import { getCanisterNames } from './canister_names';
+
+type HeapAllocations = {
+    [canisterName: string]: number | null;
+};
+
+type MemorySizes = {
+    [canisterName: string]: number | null;
+};
+
+type MemoryState = {
+    correctness: {
+        heapAllocations: HeapAllocations;
+        memorySizes: MemorySizes;
+    };
+    fuzz: {
+        heapAllocations: HeapAllocations;
+        memorySizes: MemorySizes;
+    };
+};
+
+export let startingMemoryState: MemoryState = {
+    correctness: {
+        heapAllocations: {},
+        memorySizes: {}
+    },
+    fuzz: {
+        heapAllocations: {},
+        memorySizes: {}
+    }
+};
+
+/**
+ * Returns a snapshot of the current dfx/ICP memory size and the heap allocation for all canisters.
+ */
+export async function takeMemorySnapshot(): Promise<{
+    heapAllocations: HeapAllocations;
+    memorySizes: MemorySizes;
+}> {
+    const canisterNames = await getCanisterNames();
+
+    const canisterSnapshots = await Promise.all(
+        canisterNames.map(async (canisterName) => {
+            const heapAllocation = getHeapAllocation(canisterName);
+
+            console.info(
+                `Canister ${canisterName} heap allocation: ${formatMemorySize(heapAllocation)}`
+            );
+
+            const memorySize = await getRawMemorySize(canisterName);
+
+            console.info(
+                `Canister ${canisterName} memory size: ${formatMemorySize(memorySize)}`
+            );
+
+            return {
+                canisterName,
+                heapAllocation,
+                memorySize
+            };
+        })
+    );
+
+    const heapAllocations = canisterSnapshots.reduce<HeapAllocations>(
+        (acc, { canisterName, heapAllocation }) => ({
+            ...acc,
+            [canisterName]: heapAllocation
+        }),
+        {}
+    );
+
+    const memorySizes = canisterSnapshots.reduce<MemorySizes>(
+        (acc, { canisterName, memorySize }) => ({
+            ...acc,
+            [canisterName]: memorySize
+        }),
+        {}
+    );
+
+    return { heapAllocations, memorySizes };
+}
+
+/**
+ * Checks the increases in memory size and heap allocation for all canisters.
+ *
+ * @remarks
+ *
+ * If a canister's heap allocation increases by more than 100_000 bytes this will throw a jest failure.
+ * If a canister's memory size increases by more than 100_000 bytes and the canister's `memorySizeIncreaseExpected` is not set to true in the canister's config, this will throw a jest failure.
+ */
+export async function checkMemoryChanges(
+    startingHeapAllocations: HeapAllocations,
+    startingMemorySizes: MemorySizes
+): Promise<void> {
+    const canisterNames = await getCanisterNames();
+
+    for (const canisterName of canisterNames) {
+        const canisterConfig = await getCanisterConfig(canisterName);
+
+        const clearHeapMethods = canisterConfig.custom?.test?.clearHeapMethods;
+
+        for (const clearHeapMethod of clearHeapMethods ?? []) {
+            execSync(
+                `dfx canister call ${canisterName} ${clearHeapMethod} --output json`,
+                {
+                    cwd: getDfxRoot(),
+                    encoding: 'utf-8'
+                }
+            );
+        }
+
+        const finalHeapAllocation = getHeapAllocation(canisterName);
+        const startingHeapAllocation = startingHeapAllocations[canisterName];
+
+        const finalMemorySize = await getRawMemorySize(canisterName);
+        const startingMemorySize = startingMemorySizes[canisterName];
+
+        if (
+            finalHeapAllocation === null ||
+            startingHeapAllocation === null ||
+            finalMemorySize === null ||
+            startingMemorySize === null
+        ) {
+            throw new Error(
+                `At least one of the memory sizes or heap allocations for canister ${canisterName} is null. This most likely indicates an error in fetching the data.`
+            );
+        }
+
+        const heapAllocationIncrease =
+            finalHeapAllocation - startingHeapAllocation;
+        const heapAllocationIncreaseText =
+            heapAllocationIncrease === 0
+                ? 'no change'
+                : heapAllocationIncrease > 0
+                  ? `+${formatMemorySize(heapAllocationIncrease)}`
+                  : `-${formatMemorySize(heapAllocationIncrease)}`;
+
+        console.info(
+            `Canister ${canisterName} final heap allocation: ${formatMemorySize(finalHeapAllocation)} (${heapAllocationIncreaseText})`
+        );
+
+        const memorySizeIncrease = finalMemorySize - startingMemorySize;
+        const memorySizeIncreaseText =
+            memorySizeIncrease === 0
+                ? 'no change'
+                : memorySizeIncrease > 0
+                  ? `+${formatMemorySize(memorySizeIncrease)}`
+                  : `-${formatMemorySize(memorySizeIncrease)}`;
+
+        console.info(
+            `Canister ${canisterName} final memory size: ${formatMemorySize(finalMemorySize)} (${memorySizeIncreaseText})`
+        );
+
+        expect(heapAllocationIncrease).toBeLessThanOrEqual(100_000);
+
+        const memorySizeIncreaseExpected =
+            canisterConfig.custom?.test?.memorySizeIncreaseExpected === true;
+
+        if (memorySizeIncreaseExpected === false) {
+            expect(memorySizeIncrease).toBeLessThanOrEqual(100_000);
+        }
+    }
+}
+
+function getHeapAllocation(canisterName: string): number | null {
+    try {
+        return Number(
+            execSync(
+                `dfx canister call ${canisterName} _azle_heap_allocation --output json`,
+                {
+                    cwd: getDfxRoot(),
+                    encoding: 'utf-8'
+                }
+            )
+        );
+    } catch {
+        return null;
+    }
+}

package/src/stable/test/property/default_prop_test_params.ts

@@ -0,0 +1,36 @@
+import * as fc from 'fast-check';
+
+export function defaultPropTestParams<T = unknown>(): fc.Parameters<T> {
+    const baseParams = {
+        numRuns: Number(process.env.AZLE_PROPTEST_NUM_RUNS ?? 1),
+        reporter: (runDetails: fc.RunDetails<T>): void => {
+            const seed = runDetails.seed;
+            const path = runDetails.counterexamplePath;
+            const experimental = process.env.AZLE_EXPERIMENTAL === 'true';
+            const reproductionCommand = `${experimental ? 'AZLE_EXPERIMENTAL=true ' : ''}AZLE_PROPTEST_SEED=${seed}${path !== null ? ` AZLE_PROPTEST_PATH="${path}"` : ''} AZLE_VERBOSE=true AZLE_DEV_TEMPLATE=true npm test`;
+            const reproductionMessage = `To reproduce this exact test case, run:\ncd ${process.cwd()}\n${reproductionCommand}`;
+            console.info(reproductionMessage);
+            if (runDetails.failed) {
+                const error =
+                    runDetails.errorInstance === undefined ||
+                    runDetails.errorInstance === null
+                        ? ''
+                        : `${runDetails.errorInstance.toString()}\n\n`;
+
+                throw new Error(
+                    `${reproductionMessage}\n\n${error}${fc.defaultReportMessage(runDetails)}`
+                );
+            }
+        },
+        endOnFailure: process.env.AZLE_PROPTEST_SHRINK === 'true' ? false : true
+    };
+
+    const seed =
+        process.env.AZLE_PROPTEST_SEED !== undefined
+            ? Number(process.env.AZLE_PROPTEST_SEED)
+            : undefined;
+
+    const path = process.env.AZLE_PROPTEST_PATH;
+
+    return seed !== undefined ? { ...baseParams, seed, path } : baseParams;
+}

package/src/stable/test/type/assert_type.ts

@@ -0,0 +1,9 @@
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+export type IsExact<T, U> = [T] extends [U]
+    ? [U] extends [T]
+        ? true
+        : false
+    : false;
+export type NotAnyAndExact<T, U> =
+    IsAny<T> extends true ? false : IsExact<T, U>;
+export type AssertType<T extends true> = T;