apify-test-tools 0.1.0

package/lib/run-test-result.ts

@@ -0,0 +1,70 @@
+import { ActorRun, ApifyClient } from 'apify-client';
+import type { Dataset, SdkCrawlerStatistics } from './types';
+
+export class RunTestResult {
+    private log: string | undefined;
+    private dataset: Dataset<unknown> | undefined;
+    private statistics: SdkCrawlerStatistics | undefined;
+    private runInfo: ActorRun | undefined;
+    private input: unknown | undefined;
+
+    constructor(
+        private readonly apifyClient: ApifyClient,
+        private readonly run: ActorRun,
+    ) { /**/ }
+
+    getStatistics = async (): Promise<SdkCrawlerStatistics | undefined> => {
+        if (this.statistics) {
+            return this.statistics;
+        }
+        const kvs = this.apifyClient.keyValueStore(this.run.defaultKeyValueStoreId);
+        const stats = await kvs.getRecord('SDK_CRAWLER_STATISTICS_0');
+        this.statistics = stats?.value as unknown as SdkCrawlerStatistics;
+        return this.statistics;
+    };
+
+    getLog = async (): Promise<string> => {
+        if (this.log) {
+            return this.log;
+        }
+        const runLog = await this.apifyClient.run(this.id).log().get();
+        this.log = runLog;
+        return runLog as string;
+    };
+
+    getDataset = async<T>(): Promise<Dataset<T>> => {
+        if (this.dataset) {
+            return this.dataset as Dataset<T>;
+        }
+        const dataset = this.apifyClient.dataset(this.run.defaultDatasetId);
+        const items = (await dataset.listItems()).items as T[];
+        this.dataset = { items };
+        return this.dataset as Dataset<T>;
+    };
+
+    getInput = async<T>(): Promise<T> => {
+        if (this.input) {
+            return this.input as T
+        }
+        const kvs = this.apifyClient.keyValueStore(this.run.defaultKeyValueStoreId);
+        const input = await kvs.getRecord('INPUT');
+        return input as T;
+    }
+
+    getRunInfo = async (): Promise<ActorRun> => {
+        if (this.runInfo) {
+            return this.runInfo;
+        }
+        const run = this.apifyClient.run(this.run.id);
+        this.runInfo = await run.get();
+        return this.runInfo!;
+    };
+
+    get id(): string {
+        return this.run.id;
+    }
+
+    get status(): string {
+        return this.run.status;
+    }
+}

package/lib/types.ts

@@ -0,0 +1,131 @@
+import { ActorCallOptions } from 'apify-client';
+import { Assertion } from 'vitest';
+
+export type ActorBuild = {
+    buildId: string;
+    actorId: string;
+    buildNumber: string;
+    actorName: string;
+}
+
+export type RunOptions<T> = {
+    input: Omit<T, 'actorName'>
+    options?: ActorCallOptions
+    prefilledInput?: boolean
+}
+
+export type Dataset<T> = {
+    items: T[]
+}
+
+export type OpenInterval = {
+    min: number
+    max?: undefined
+} | {
+    min?: undefined
+    max: number
+}
+
+export type ClosedInterval = {
+    min: number
+    max: number
+}
+
+export type Interval = number | OpenInterval | ClosedInterval
+
+export type ToFinishWithOptionsWithDefaults = {
+    status: RunStatus
+    duration: Interval | null
+    failedRequests: Interval | null
+    requestsRetries: Interval | null
+    forbiddenLogs: string[]
+}
+export type IntervalOption<PpeEvent extends string> = keyof Pick<
+    ToFinishWithOptions<PpeEvent>,
+    | 'datasetItemCount'
+    | 'requestsRetries'
+    | 'failedRequests'
+    | 'duration'
+>
+
+export type ToFinishWithOptions<PpeEvent extends string> = Partial<ToFinishWithOptionsWithDefaults> & {
+    datasetItemCount: Interval
+    /**
+     * Define expected charged (PPE) event counts. You can also define count as `Interval`.
+     *
+     * Example
+     * ```ts
+     * chargedEventCounts: {
+     *   'actor-start': 4,
+     *   'item-pushed': { min: 10, max: 20 },
+     * }
+     * ```
+     *
+     * If you omit any PPE event, it's expected count will be 0.
+     * Assertion will fail if `chargedEventCounts` doesn't contain some of the expected events.
+     */
+    chargedEventCounts?: Record<PpeEvent, Interval>
+};
+
+export type SdkCrawlerStatistics = {
+    requestsFinished: number
+    requestsFailed: number
+    requestsRetries: number
+    requestsFailedPerMinute: number
+    requestsFinishedPerMinute: number
+    requestMinDurationMillis: number
+    requestMaxDurationMillis: number
+    requestRetryHistogram: number[]
+    requestTotalFailedDurationMillis: number
+    requestTotalFinishedDurationMillis: number
+    crawlerStartedAt: string
+    crawlerFinishedAt: string
+    statsPersistedAt: string
+    crawlerRuntimeMillis: number
+    crawlerLastStartTimestamp: number
+}
+
+export type RunStatus =
+    | 'SUCCEEDED'
+    | 'READY'
+    | 'RUNNING'
+    | 'FAILED'
+    | 'ABORTING'
+    | 'ABORTED'
+    | 'TIMING-OUT'
+    | 'TIMED-OUT'
+
+export interface ActorMatchers<R = unknown> {
+    toBeArray: () => R
+    toBeBoolean: () => R
+    toBeEmptyArray: () => R
+    toBeNonEmptyArray: () => R
+    toBeNonEmptyString: () => R
+    toBeNumber: () => R
+    toBeFalse: () => R
+    toBeTrue: () => R
+    toBeNonEmptyObject: () => R
+    toBeObject: () => R
+    toBeString: () => R
+    toBeWholeNumber: () => R
+    toBeWithinRange: (lower: number, upper: number) => R
+    /**
+     * Validates the following properties of a run:
+     * - `status` (default: `SUCCEEDED`)
+     * - `duration` in milliseconds (default: `{ min: 600, max: 600_000}` - <0.6s, 10min>)
+     * - `failedRequests` (default: `0`)
+     * - `requestsRetries` (default: `{ max: 3 }`)
+     * - `forbiddenLogs` (default: `['ReferenceError', 'TypeError']`)
+     * - `datasetItemCount` (required)
+     * - `chargedEventCounts`
+     */
+    toFinishWith: <PpeEvent extends string>(options: ToFinishWithOptions<PpeEvent>) => Promise<R>
+    toStartWith: (prefix: string) => R
+    hard: <T>(actual: T, message?: string) => Assertion
+}
+
+declare module 'vitest' {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    interface Assertion<T = any> extends ActorMatchers<T> { }
+    interface AsymmetricMatchersContaining extends ActorMatchers { }
+}

package/lib/utils.ts

@@ -0,0 +1,49 @@
+import { ApifyClient } from 'apify-client';
+
+/**
+ * Gets prefilled values for a provided build or, if not provided, uses actor's
+ * default build (this is usually `latest`).
+ */
+export const getActorPrefilledInput = async (
+    apifyClient: ApifyClient,
+    actorNameOrId: string,
+    buildId: string | undefined,
+) => {
+    if (!buildId) {
+        const actorInfo = await apifyClient.actor(actorNameOrId).get();
+
+        const defaultBuildTag = actorInfo?.defaultRunOptions.build;
+
+        const taggedBuild = actorInfo?.taggedBuilds?.[defaultBuildTag || ''];
+        buildId = taggedBuild?.buildId;
+
+        if (!buildId) {
+            console.error(`Coudn't find default build for actor ${actorNameOrId}. Prefilled values will not be used.`);
+            return {}
+        }
+    }
+
+    const buildInfo = await apifyClient.build(buildId).get();
+
+    const inputSchema = buildInfo?.actorDefinition?.input as {
+        properties: Record<string, { prefill?: unknown }>
+    } | undefined
+
+    if (!inputSchema) {
+        console.error(
+            `Coudn't find input schema definition for actor ${actorNameOrId}, build ${buildId}.`,
+            'Prefilled values will not be used',
+        );
+        return {}
+    }
+
+    const prefill: Record<string, unknown> = {};
+
+    for (const [propertyName, propertyValue] of Object.entries(inputSchema.properties)) {
+        if (propertyValue.prefill !== undefined) {
+            prefill[propertyName] = propertyValue.prefill;
+        }
+    }
+
+    return prefill;
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "apify-test-tools",
+    "version": "0.1.0",
+    "type": "module",
+    "description": "TBD",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "bin": {
+        "apify-test-tools": "dist/bin/main.js"
+    },
+    "types": "./dist/index.d.ts",
+    "main": "./dist/lib/lib.js",
+    "dependencies": {
+        "@apify/consts": "^2.43.0",
+        "@slack/web-api": "^7.9.2",
+        "apify-client": "^2.12.6",
+        "yargs": "^18.0.0"
+    },
+    "devDependencies": {
+        "@apify/eslint-config-ts": "^0.3.0",
+        "@apify/tsconfig": "^0.1.0",
+        "@types/yargs": "^17.0.33",
+        "@typescript-eslint/eslint-plugin": "^6.7.2",
+        "@typescript-eslint/parser": "^6.7.2",
+        "eslint": "^8.50.0",
+        "tsx": "^4.19.2",
+        "typescript": "^5.7",
+        "vitest": "^3.2.4"
+    },
+    "scripts": {
+        "start": "npm run dist/bin/main.js",
+        "start:dev": "GITHUB_WORKSPACE=local-clone tsx bin/main.ts",
+        "build": "tsc && chmod +x ./dist/bin/main.js",
+        "lint": "eslint ./src --ext .ts",
+        "lint:fix": "eslint ./src --ext .ts --fix",
+        "test": "vitest run"
+    },
+    "author": "oklinov",
+    "license": "ISC"
+}

package/scripts/hook-job-started.sh

@@ -0,0 +1,11 @@
+reponame=$(jq '.repository.name' ${GITHUB_EVENT_PATH})
+commit_message=$(jq '.head_commit.message' ${GITHUB_EVENT_PATH})
+pr_title=$(jq '.pull_request.title' ${GITHUB_EVENT_PATH})
+
+if [ "${commit_message}" != "null" ]; then
+    echo "Received push event from repo ${reponame} with commit message ${commit_message}"
+    fi
+
+if [ "${pr_title}" != "null" ]; then
+    echo "Received PR event from repo ${reponame} with PR title ${pr_title}"
+    fi

package/test/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "extends": "@apify/tsconfig",
+    "compilerOptions": {
+        "module": "ES2022",
+        "target": "ES2022",
+        "outDir": "dist",
+        "noUnusedLocals": false,
+        "noEmit": true,
+        "lib": ["DOM", "es2021"],
+        "skipLibCheck": true,
+    },
+    "include": [
+        "./**/*",
+    ]
+}

package/test/unit/custom-matchers.test.ts

@@ -0,0 +1,61 @@
+import process from 'process';
+import { describe } from 'vitest';
+
+import { ApifyClient } from 'apify-client';
+import { testTestActor } from '../../lib/lib';
+import { RunTestResult } from '../../lib/run-test-result';
+
+type PpeEventType =
+    | 'actor-start'
+    | 'search-page-scraped'
+    | 'ads-scraped'
+enum PpeEventEnum {
+    ACTOR_START = 'actor-start',
+    SEARCH_PAGE_SCRAPED = 'search-page-scraped',
+    ADS_SCRAPED = 'ads-scraped',
+}
+const PPE_EVENT_CONST = {
+    ACTOR_START: 'actor-start',
+    ITEM_PUSHED: 'search-page-scraped',
+    ADS_SCRAPED: 'ads-scraped',
+} as const;
+
+describe('custom-matchers', { timeout: 100_000 }, () => {
+    testTestActor('basic', async ({ expect }) => {
+        const apifyClient = new ApifyClient({ token: process.env.TESTER_APIFY_TOKEN });
+        const run = await apifyClient.run('k5MNKmaDGHlABDn2I').get();
+        const runResult = new RunTestResult(apifyClient, run!);
+        await expect(runResult).toFinishWith<PpeEventType>({
+            datasetItemCount: { min: 10, max: 20 },
+            duration: 10,
+            status: 'TIMING-OUT',
+            chargedEventCounts: {
+                'actor-start': 1,
+                'search-page-scraped': { min: 1 },
+                'ads-scraped': 3,
+            },
+        });
+
+        await expect(runResult).toFinishWith<PpeEventEnum>({
+            datasetItemCount: { min: 10, max: 20 },
+            chargedEventCounts: {
+                'actor-start': 1,
+                'search-page-scraped': { min: 1 },
+                'ads-scraped': 0,
+            },
+        });
+
+        await expect(runResult).toFinishWith<typeof PPE_EVENT_CONST[keyof typeof PPE_EVENT_CONST]>({
+            datasetItemCount: { min: 1, max: 20 },
+            chargedEventCounts: {
+                'actor-start': 1,
+                'search-page-scraped': { min: 1 },
+                'ads-scraped': 0,
+            },
+        });
+
+        expect(3).toEqual(3);
+        expect.hard(5).toEqual(5);
+        expect(10).toEqual(10);
+    });
+});

package/test/unit/should-built-and-test.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from 'vitest';
+
+import type { ActorConfig } from '../../bin/types.js';
+import { getChangedActors } from '../../bin/utils.js';
+
+describe('Should build and test parser', () => {
+    // From https://github.com/apify-store/testing-repo-for-github-actions
+    const ACTOR_CONFIGS: ActorConfig[] = [
+        {
+            actorName: 'lukaskrivka/testing-github-integration-1',
+            folder: 'actors/lukaskrivka_testing-github-integration-1',
+            isStandalone: false,
+        },
+        {
+            actorName: 'lukaskrivka/testing-github-integration-2',
+            folder: 'actors/lukaskrivka_testing-github-integration-2',
+            isStandalone: false,
+        },
+        {
+            actorName: 'lukaskrivka/test-standalone',
+            folder: 'standalone-actors/lukaskrivka_test-standalone',
+            isStandalone: true,
+        },
+    ];
+
+    test('Ignores dev-only readme', async () => {
+        const FILES = ['README.md', 'code/README.md', 'shared/README.md'];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({ actorConfigs: ACTOR_CONFIGS, isLatest: false, filepathsChanged: FILES });
+
+        expect(actorsChanged).toEqual([]);
+        expect(codeChanged).toBe(false);
+    });
+
+    test('Ignores other ignored files and folders', async () => {
+        const FILES = ['.vscode/', '.gitignore', '.husky/', '.eslintrc', '.editorconfig', '.actor/'];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({ actorConfigs: ACTOR_CONFIGS, isLatest: false, filepathsChanged: FILES });
+
+        expect(actorsChanged).toEqual([]);
+        expect(codeChanged).toBe(false);
+    });
+
+    test('Only builds latest for all Actors', async () => {
+        const FILES = ['shared/CHANGELOG.md', 'CHANGELOG.md'];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({ actorConfigs: ACTOR_CONFIGS, isLatest: true, filepathsChanged: FILES });
+
+        expect(actorsChanged).toEqual(ACTOR_CONFIGS.filter(({ isStandalone }) => !isStandalone));
+        expect(codeChanged).toBe(false);
+    });
+
+    test('Code updated, tests miniactors', async () => {
+        const FILES = ['code/src/main.ts', 'package.json'];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({ actorConfigs: ACTOR_CONFIGS, isLatest: false, filepathsChanged: FILES });
+
+        expect(actorsChanged).toEqual(ACTOR_CONFIGS.filter(({ isStandalone }) => !isStandalone));
+        expect(codeChanged).toBe(true);
+    });
+
+    test('Specific Actor functionality configs updated', async () => {
+        const FILES = ['actors/lukaskrivka_testing-github-integration-1/.actor/actor.json', 'standalone-actors/lukaskrivka_test-standalone/Dockerfile'];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({ actorConfigs: ACTOR_CONFIGS, isLatest: false, filepathsChanged: FILES });
+
+        expect(actorsChanged).toEqual([ACTOR_CONFIGS[0], ACTOR_CONFIGS[2]]);
+        expect(codeChanged).toBe(false);
+    });
+
+    test('src/main.ts updated', async () => {
+        const FILES = [
+            'src/main.ts',
+        ];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({ actorConfigs: ACTOR_CONFIGS, isLatest: true, filepathsChanged: FILES });
+
+        expect(actorsChanged).toEqual(ACTOR_CONFIGS.slice(0, 2));
+        expect(codeChanged).toBe(false);
+    });
+
+    test('Miniactor, Code and standalone actor updated,', async () => {
+        const FILES = [
+            'actors/lukaskrivka_testing-github-integration-1/.actor/actor.json',
+            'code/src/main.ts',
+            'standalone-actors/lukaskrivka_test-standalone/Dockerfile',
+        ];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({ actorConfigs: ACTOR_CONFIGS, isLatest: false, filepathsChanged: FILES });
+
+        expect(actorsChanged).toEqual(ACTOR_CONFIGS);
+        expect(codeChanged).toBe(true);
+    });
+
+    test('Specific Actor non-functional configs updated', async () => {
+        const FILES = ['actors/lukaskrivka_testing-github-integration-2/.actor/README.md', 'standalone-actors/lukaskrivka_test-standalone/CHANGELOG.md'];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({ actorConfigs: ACTOR_CONFIGS, isLatest: false, filepathsChanged: FILES });
+
+        expect(actorsChanged).toEqual([]);
+        expect(codeChanged).toBe(false);
+    });
+
+    test('Google Maps real user-case that had undefined', async () => {
+        const FILES = ['actors/compass_Google-Maps-Reviews-Scraper/.actor/INPUT_SCHEMA.json', 'actors/compass_crawler-google-places/.actor/INPUT_SCHEMA.json',
+            'code/src/consts.ts', 'code/src/crawlers/cheerio/routes.ts', 'code/src/detail_page_handle.ts', 'code/src/enqueue_places.ts',
+            'code/src/helper-classes/initialize-all.ts', 'code/src/helper-classes/stats.ts', 'code/src/helper-classes/unmatched-categories.ts',
+            'code/src/main.ts', 'code/src/typedefs/general.ts', 'code/src/utils/background-enqueue.ts'];
+
+        const ACTOR_CONFIGS_GOOGLE_MAPS: ActorConfig[] = [
+            {
+                // Edge case of capitals in actor name :)
+                actorName: 'compass/Google-Maps-Reviews-Scraper',
+                folder: 'actors/compass_Google-Maps-Reviews-Scraper',
+                isStandalone: false,
+            },
+            {
+                actorName: 'compass/crawler-google-places',
+                folder: 'actors/compass_crawler-google-places',
+                isStandalone: false,
+            },
+            {
+                actorName: 'compass/easy-google-maps',
+                folder: 'actors/compass_easy-google-maps',
+                isStandalone: false,
+            },
+            {
+                actorName: 'compass/google-maps-extractor',
+                folder: 'actors/compass_google-maps-extractor',
+                isStandalone: false,
+            },
+            {
+                actorName: 'compass/google-places-api',
+                folder: 'actors/compass_google-places-api',
+                isStandalone: false,
+            },
+            {
+                actorName: 'lukaskrivka/google-maps-with-contact-details',
+                folder: 'actors/lukaskrivka_google-maps-with-contact-details',
+                isStandalone: false,
+            },
+            {
+                actorName: 'natasha.lekh/gas-prices-scraper',
+                folder: 'actors/natasha.lekh_gas-prices-scraper',
+                isStandalone: false,
+            },
+            {
+                actorName: 'natasha.lekh/vegan-places-finder',
+                folder: 'actors/natasha.lekh_vegan-places-finder',
+                isStandalone: false,
+            },
+            {
+                actorName: 'lukaskrivka/google-maps-scraper-orchestrator',
+                folder: 'standalone-actors/lukaskrivka_google-maps-scraper-orchestrator',
+                isStandalone: true,
+            },
+        ];
+
+        const { actorsChanged, codeChanged } = await getChangedActors({
+            actorConfigs: ACTOR_CONFIGS_GOOGLE_MAPS, isLatest: false, filepathsChanged: FILES,
+        });
+
+        expect(actorsChanged).toEqual(ACTOR_CONFIGS_GOOGLE_MAPS.filter(({ isStandalone }) => !isStandalone));
+        expect(codeChanged).toBe(true);
+    });
+});

package/test/unit/test-actor.test.ts

@@ -0,0 +1,17 @@
+import { describe, testActor } from '../../lib/lib';
+
+describe('testActor tests', async () => {
+    testActor('compass/google-maps-extractor', 'basic', async ({ expect, run }) => {
+        const runResult = await run({
+            input: {},
+            prefilledInput: true,
+            options: {
+                memory: 512,
+            },
+        })
+        const input = await runResult.getInput<{ maxCrawledPlacesPerSearch: number }>();
+        await expect(runResult).toFinishWith({
+            datasetItemCount: input.maxCrawledPlacesPerSearch,
+        })
+    });
+});

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "extends": "@apify/tsconfig",
+    "compilerOptions": {
+        "declaration": true,
+        "module": "ES2022",
+        "target": "ES2022",
+        "outDir": "dist",
+        "noUnusedLocals": false,
+        "strict": true,
+        "esModuleInterop": true,
+        "lib": ["DOM", "es2021"],
+        "skipLibCheck": true,
+    },
+    "include": [
+        "./index.ts",
+        "./bin/**/*",
+        "./lib/**/*",
+        "./test/**/*",
+    ]
+}