apify-test-tools 0.9.1-beta.4 → 0.9.1-beta.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apify-test-tools",
-  "version": "0.9.1-beta.4",
+  "version": "0.9.1-beta.6",
   "type": "module",
   "description": "TBD",
   "repository": {
@@ -20,7 +20,8 @@
     "@slack/web-api": "^7.9.2",
     "apify-client": "^2.22.2",
     "ignore": "^7.0.5",
-    "yargs": "^18.0.0"
+    "yargs": "^18.0.0",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@apify/eslint-config": "^1.0.0",

package/test/fixtures/bin/utils/files/array.json

@@ -0,0 +1 @@
+[{ "a": 1 }]

package/test/fixtures/bin/utils/files/comments.jsonc

@@ -0,0 +1,4 @@
+{
+    // this is a comment
+    "a": 3,
+}

package/test/fixtures/bin/utils/files/empty-object.json

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

package/test/fixtures/bin/utils/files/malformed.json

@@ -0,0 +1 @@
+{ "a": 1

package/test/fixtures/bin/utils/files/nested.json

@@ -0,0 +1,6 @@
+{
+    "storages": { "datasets": { "default": { "title": "Default" } } },
+    "overrideActorContext": ["../shared", "."],
+    "changelog": null,
+    "nested": [{ "deep": [1, 2, { "deeper": true }] }]
+}

package/test/fixtures/bin/utils/files/no-json-extension.actorrc

@@ -0,0 +1 @@
+{ "a": 1 }

package/test/fixtures/bin/utils/files/null.json

@@ -0,0 +1 @@
+null

package/test/fixtures/bin/utils/files/number.json

@@ -0,0 +1 @@
+42

package/test/fixtures/bin/utils/files/unreadable.json

@@ -0,0 +1 @@
+{ "a": 1 }

package/test/tsconfig.json

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

package/test/unit/bin/utils/config/load-config.test.ts

@@ -0,0 +1,179 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { CONFIG_FILE_NAME, loadActorConfig, readConfigFile } from '../../../../../bin/utils/config/load-config.js';
+import type { ResolvedActorConfig } from '../../../../../bin/utils/config/structures/base.js';
+
+let repoDir: string;
+let originalCwd: string;
+
+beforeEach(async () => {
+    originalCwd = process.cwd();
+    // `realpath` because macOS hands out a symlinked temp dir, while `process.cwd()` reports the target.
+    repoDir = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'apify-test-tools-config-')));
+    process.chdir(repoDir);
+});
+
+afterEach(async () => {
+    process.chdir(originalCwd);
+    await fs.rm(repoDir, { recursive: true, force: true });
+});
+
+const emptyActorSelection = { actors: [], ignore: [] };
+
+const validConfig = (actors: object[]) => JSON.stringify({ actors });
+const actorJson = (fields: Record<string, unknown> = {}) => JSON.stringify(fields);
+
+const writeFiles = async (files: Record<string, string>) =>
+    Promise.all(
+        Object.entries(files).map(async ([filePath, contents]) => {
+            const absPath = path.join(repoDir, filePath);
+            await fs.mkdir(path.dirname(absPath), { recursive: true });
+            await fs.writeFile(absPath, contents);
+        }),
+    );
+
+describe('loadActorConfig', () => {
+    const entry = (fields: Partial<ResolvedActorConfig> = {}): ResolvedActorConfig => ({
+        folder: 'actors/shopify',
+        actorFullName: 'myteam/shopify',
+        tokenEnvVar: 'APIFY_TOKEN',
+        ...fields,
+    });
+
+    const writeActorJson = async (fields: Record<string, unknown> = {}) =>
+        writeFiles({ 'actors/shopify/.actor/actor.json': actorJson(fields) });
+
+    it('resolves data coming from actor.json', async () => {
+        await writeActorJson({ dockerContextDir: '..' });
+
+        expect(loadActorConfig(entry())).toEqual({
+            actorFullName: 'myteam/shopify',
+            folder: 'actors/shopify',
+            tokenEnvVar: 'APIFY_TOKEN',
+            dockerContextDir: 'actors/shopify',
+            contextPaths: ['actors/shopify'],
+        });
+    });
+
+    it('defaults dockerContextDir to the actor folder when actor.json does not set it', async () => {
+        await writeActorJson();
+
+        expect(loadActorConfig(entry()).dockerContextDir).toBe('actors/shopify');
+    });
+
+    it('resolves dockerContextDir relative to the .actor/ folder, not the actor folder', async () => {
+        await writeActorJson({ dockerContextDir: '../../..' });
+
+        expect(loadActorConfig(entry()).dockerContextDir).toBe('');
+    });
+
+    it('throws when dockerContextDir resolves outside the repository root', async () => {
+        await writeActorJson({ dockerContextDir: '../../../..' });
+
+        expect(() => loadActorConfig(entry())).toThrow(/resolves outside the repository root/);
+    });
+
+    it('throws when actor.json is missing', () => {
+        expect(() => loadActorConfig(entry())).toThrow('Cannot read');
+    });
+
+    it('resolves contextPaths from overrideActorContext', async () => {
+        await writeActorJson({ dockerContextDir: '../../..' });
+
+        expect(loadActorConfig(entry({ overrideActorContext: ['actors/shopify', 'packages'] })).contextPaths).toEqual([
+            'actors/shopify',
+            'packages',
+        ]);
+    });
+
+    it('adds the actor own folder automatically when overrideActorContext does not cover it', async () => {
+        await writeActorJson();
+
+        expect(loadActorConfig(entry({ overrideActorContext: ['code', 'shared'] })).contextPaths).toEqual([
+            'code',
+            'shared',
+            'actors/shopify',
+        ]);
+    });
+
+    it('allows overrideActorContext with disjoint sibling paths that all reach the actor folder via one entry', async () => {
+        await writeActorJson();
+
+        expect(
+            loadActorConfig(entry({ overrideActorContext: ['actors/shopify', 'code', 'shared'] })).contextPaths,
+        ).toEqual(['actors/shopify', 'code', 'shared']);
+    });
+
+    it('throws when overrideActorContext entries overlap (one is a prefix of another)', async () => {
+        await writeActorJson();
+
+        expect(() => loadActorConfig(entry({ overrideActorContext: ['actors/shopify', 'actors'] }))).toThrow(/overlap/);
+    });
+
+    it('throws when overrideActorContext contains the repo root alongside another entry', async () => {
+        await writeActorJson();
+
+        expect(() => loadActorConfig(entry({ overrideActorContext: ['', 'actors/shopify'] }))).toThrow(/overlap/);
+    });
+});
+
+describe('readConfigFile', () => {
+    // Golden output massaging the whole config reading process
+    it("carries the parser's normalization through to ActorConfig[]", async () => {
+        await writeFiles({
+            [CONFIG_FILE_NAME]: validConfig([
+                { folder: '.', actorFullName: 'apify/root', tokenEnvVar: 'APIFY_TOKEN_APIFY' },
+                {
+                    folder: 'actors/shopify/',
+                    actorFullName: 'myteam/shopify',
+                    tokenEnvVar: 'APIFY_TOKEN',
+                    overrideActorContext: ['actors/shopify/', 'packages/'],
+                },
+            ]),
+            '.actor/actor.json': actorJson({}),
+            'actors/shopify/.actor/actor.json': actorJson({}),
+        });
+
+        expect(await readConfigFile(emptyActorSelection)).toEqual([
+            {
+                actorFullName: 'apify/root',
+                folder: '',
+                tokenEnvVar: 'APIFY_TOKEN_APIFY',
+                dockerContextDir: '',
+                contextPaths: [''],
+            },
+            {
+                actorFullName: 'myteam/shopify',
+                folder: 'actors/shopify',
+                tokenEnvVar: 'APIFY_TOKEN',
+                dockerContextDir: 'actors/shopify',
+                contextPaths: ['actors/shopify', 'packages'],
+            },
+        ]);
+    });
+
+    it('throws when config file is missing', async () => {
+        await expect(readConfigFile(emptyActorSelection)).rejects.toThrow('not found');
+    });
+
+    it('throws when config file contains invalid JSON', async () => {
+        await writeFiles({ [CONFIG_FILE_NAME]: '{bad json' });
+        await expect(readConfigFile(emptyActorSelection)).rejects.toThrow('invalid JSON');
+    });
+
+    it('throws when the config file is not a JSON object', async () => {
+        await writeFiles({ [CONFIG_FILE_NAME]: JSON.stringify([{ folder: 'actors/shopify' }]) });
+        await expect(readConfigFile(emptyActorSelection)).rejects.toThrow('"actors" array');
+    });
+
+    // The wording of a schema failure belongs to the strategy; this only checks that the failure
+    // reaches the caller rather than being swallowed on the way out of readConfigFile.
+    it('surfaces a schema failure from the parser', async () => {
+        await writeFiles({ [CONFIG_FILE_NAME]: JSON.stringify({ notActors: [] }) });
+        await expect(readConfigFile(emptyActorSelection)).rejects.toThrow(/at actors/);
+    });
+});

package/test/unit/bin/utils/config/parser.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest';
+
+import { _privates, parseConfigFile } from '../../../../../bin/utils/config/parser.js';
+import { CONFIG_FILE_STRATEGY } from '../../../../../bin/utils/config/structures/base.js';
+import { LEGACY_PARSER } from '../../../../../bin/utils/config/structures/legacy.js';
+
+const { selectStrategy, verifyConfiguration } = _privates;
+
+const actor = (fields: Record<string, unknown> = {}) => ({
+    folder: 'actors/shopify',
+    actorFullName: 'myteam/shopify',
+    tokenEnvVar: 'APIFY_TOKEN',
+    ...fields,
+});
+
+describe('selectStrategy', () => {
+    it('falls back to the legacy strategy when no mode is declared', () => {
+        expect(selectStrategy(undefined)).toBe(LEGACY_PARSER);
+    });
+
+    it('honours an explicit mode', () => {
+        expect(selectStrategy(CONFIG_FILE_STRATEGY.LEGACY)).toBe(LEGACY_PARSER);
+    });
+
+    it('throws on a mode no strategy is registered for', () => {
+        expect(() => selectStrategy('some-nonexistent-mode')).toThrow(/Invalid input/);
+    });
+});
+
+describe('verifyConfiguration', () => {
+    it('resolves the repo root to "" and gets rid of trailing slashes', () => {
+        const result = verifyConfiguration([
+            { folder: '.', actorFullName: 'myteam/root', tokenEnvVar: 'APIFY_TOKEN' },
+            {
+                folder: 'actors/shopify/',
+                actorFullName: 'myteam/shopify',
+                tokenEnvVar: 'APIFY_TOKEN',
+                overrideActorContext: ['packages/'],
+            },
+        ]);
+
+        expect(result).toEqual([
+            { folder: '', actorFullName: 'myteam/root', tokenEnvVar: 'APIFY_TOKEN', overrideActorContext: undefined },
+            {
+                folder: 'actors/shopify',
+                actorFullName: 'myteam/shopify',
+                tokenEnvVar: 'APIFY_TOKEN',
+                overrideActorContext: ['packages'],
+            },
+        ]);
+    });
+
+    it.each([
+        ['"." and ""', '.', ''],
+        ['weird roots', '', './//'],
+        ['a trailing slash', 'actors/shopify', 'actors/shopify/'],
+    ])('rejects folders that collide once normalized: %s', (_name, first, second) => {
+        expect(() =>
+            verifyConfiguration([
+                actor({ folder: first, actorFullName: 'myteam/actor-a' }),
+                actor({ folder: second, actorFullName: 'myteam/actor-b' }),
+            ]),
+        ).toThrow(/Duplicate folder/);
+    });
+
+    it('quotes a duplicate folder the way it was written, not the way it normalized', () => {
+        expect(() =>
+            verifyConfiguration([
+                actor({ folder: '.', actorFullName: 'myteam/actor-a' }),
+                actor({ folder: './', actorFullName: 'myteam/actor-b' }),
+            ]),
+        ).toThrow('Duplicate folder "./"');
+    });
+
+    it('rejects two entries pointing at the same actor', () => {
+        expect(() => verifyConfiguration([actor({ folder: 'actors/a' }), actor({ folder: 'actors/b' })])).toThrow(
+            /Duplicate actor "myteam\/shopify"/,
+        );
+    });
+
+    it('treats actorFullName case-sensitively — "myteam/A" is not "myteam/a"', () => {
+        expect(() =>
+            verifyConfiguration([
+                actor({ folder: 'actors/a', actorFullName: 'myteam/abc' }),
+                actor({ folder: 'actors/b', actorFullName: 'myteam/ABC' }),
+            ]),
+        ).not.toThrow();
+    });
+
+    it('reports every collision at once instead of stopping at the first', () => {
+        const message = (() => {
+            try {
+                verifyConfiguration([
+                    actor({ folder: 'actors/a', actorFullName: 'myteam/actor-a' }),
+                    actor({ folder: 'actors/a', actorFullName: 'myteam/actor-b' }),
+                    actor({ folder: 'actors/c', actorFullName: 'myteam/actor-c' }),
+                    actor({ folder: 'actors/d', actorFullName: 'myteam/actor-c' }),
+                ]);
+                return '';
+            } catch (err) {
+                return (err as Error).message;
+            }
+        })();
+
+        expect(message.split('\n')).toEqual([
+            'Duplicate folder "actors/a". Each actor must have a unique folder.',
+            'Duplicate actor "myteam/actor-c". Each entry must point at a different actor.',
+        ]);
+    });
+
+    it('reports both problems for an entry that duplicates a folder and an actor at once', () => {
+        expect(() => verifyConfiguration([actor(), actor()])).toThrow(/Duplicate folder[\s\S]*Duplicate actor/);
+    });
+
+    it('accepts an empty configuration', () => {
+        expect(verifyConfiguration([])).toEqual([]);
+    });
+});
+
+describe('parseConfigFile', () => {
+    it('validates and normalizes a plain object without touching the filesystem', () => {
+        expect(parseConfigFile({ actors: [actor({ folder: 'actors/shopify/' })] })).toEqual([
+            actor({ folder: 'actors/shopify', overrideActorContext: undefined }),
+        ]);
+    });
+
+    it('surfaces cross-entry violations from verifyConfiguration', () => {
+        expect(() =>
+            parseConfigFile({
+                actors: [
+                    actor({ actorFullName: 'myteam/actor-a', folder: 'collide/collide' }),
+                    actor({ actorFullName: 'myteam/actor-b', folder: 'collide/collide' }),
+                ],
+            }),
+        ).toThrow(/Duplicate folder/);
+    });
+});

package/test/unit/bin/utils/config/structures/base.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+
+import { ACTOR_NAME, USERNAME } from '@apify/consts';
+
+import { ACTOR_FULL_NAME_REGEX } from '../../../../../../bin/utils/config/structures/base.js';
+
+// ACTOR_FULL_NAME_REGEX is spliced together from two platform constants by stripping their anchors
+// and joining them with a "/". These tests are about the splice, not about re-testing the platform's
+// own rules: an anchor left behind, an anchor stripped too eagerly, or the actor-name alternation
+// losing its parentheses would all produce a regex that still looks plausible and matches the wrong
+// things. The cases below are the ones that tell those failures apart.
+describe('ACTOR_FULL_NAME_REGEX', () => {
+    it.each([
+        ['apify/web-scraper'],
+        ['myteam/shopify'],
+        ['my.team/web-scraper'],
+        ['my-team/shopify'],
+        ['my_team/a1'],
+        // ACTOR_NAME's first alternative — a single character — is a legal actor name on its own.
+        ['myteam/a'],
+        ['myteam/a--b'],
+    ])('accepts %s', (fullName) => {
+        expect(ACTOR_FULL_NAME_REGEX.test(fullName)).toBe(true);
+    });
+
+    it.each([
+        ['there is no slash', 'shopify'],
+        ['the owner half is empty', '/shopify'],
+        ['the actor half is empty', 'myteam/'],
+        ['there are two slashes', 'myteam//shopify'],
+        ['there is a third segment', 'myteam/shopify/extra'],
+        ['the owner holds a space', 'my team/shopify'],
+        ['the actor name starts with a hyphen', 'myteam/-shopify'],
+        ['the actor name ends with a hyphen', 'myteam/shopify-'],
+        ['the actor name holds an underscore', 'myteam/web_scraper'],
+        ['the actor name holds a dot', 'myteam/web.scraper'],
+    ])('rejects a name where %s', (_name, fullName) => {
+        expect(ACTOR_FULL_NAME_REGEX.test(fullName)).toBe(false);
+    });
+
+    // Both halves arrive anchored and get de-anchored so they can be joined; the composed regex has to
+    // put the anchors back. Without them these all match on a substring.
+    it.each([
+        ['leading text', 'see myteam/shopify'],
+        ['trailing text', 'myteam/shopify here'],
+        ['a leading newline', '\nmyteam/shopify'],
+        ['a trailing newline', 'myteam/shopify\n'],
+        ['surrounding whitespace', ' myteam/shopify '],
+    ])('matches the whole string, so it rejects %s', (_name, fullName) => {
+        expect(ACTOR_FULL_NAME_REGEX.test(fullName)).toBe(false);
+    });
+
+    // ACTOR_NAME's source is an alternation, "(A|B)". It survives the splice only because the platform
+    // wrote it parenthesized — lose those parens and the regex becomes "^owner/A|B$", where the "B"
+    // branch matches a bare actor name with no owner at all.
+    it('keeps the actor-name alternation from swallowing the owner half', () => {
+        expect(ACTOR_NAME.REGEX.source).toMatch(/^\^\(.*\)\$$/);
+        expect(ACTOR_FULL_NAME_REGEX.test('shopify')).toBe(false);
+        expect(ACTOR_FULL_NAME_REGEX.test('a')).toBe(false);
+    });
+
+    // The owner half carries a {min,max} quantifier, the one part of either source that a sloppy strip
+    // could eat. Bounds come from the constants so this stays honest if the platform moves them.
+    it("enforces the platform's username length bounds", () => {
+        const owner = (length: number) => `${'a'.repeat(length)}/shopify`;
+
+        expect(ACTOR_FULL_NAME_REGEX.test(owner(USERNAME.MIN_LENGTH))).toBe(true);
+        expect(ACTOR_FULL_NAME_REGEX.test(owner(USERNAME.MIN_LENGTH - 1))).toBe(false);
+        expect(ACTOR_FULL_NAME_REGEX.test(owner(USERNAME.MAX_LENGTH))).toBe(true);
+        expect(ACTOR_FULL_NAME_REGEX.test(owner(USERNAME.MAX_LENGTH + 1))).toBe(false);
+    });
+
+    // `.source` carries the pattern and none of the flags, so the flags have to be re-applied by hand.
+    // USERNAME.REGEX is declared /i and the platform does accept "MyTeam" as a username; drop that on
+    // the way here and the owner half silently becomes stricter than the thing it was copied from.
+    it('accepts either half in any case, the way the platform does', () => {
+        expect(USERNAME.REGEX.flags).toContain('i');
+        expect(ACTOR_FULL_NAME_REGEX.flags).toContain('i');
+
+        expect(ACTOR_FULL_NAME_REGEX.test('myteam/Shopify')).toBe(true);
+        expect(ACTOR_FULL_NAME_REGEX.test('MyTeam/shopify')).toBe(true);
+    });
+});

package/test/unit/bin/utils/config/structures/legacy.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+
+import { LEGACY_PARSER } from '../../../../../../bin/utils/config/structures/legacy.js';
+
+const entry = (fields: Record<string, unknown> = {}) => ({
+    folder: 'actors/shopify',
+    actorFullName: 'myteam/shopify',
+    tokenEnvVar: 'APIFY_TOKEN',
+    ...fields,
+});
+
+describe('LEGACY_PARSER', () => {
+    it("returns the entries as written — normalizing is not this layer's job", () => {
+        const raw = entry({ folder: 'actors/shopify/', overrideActorContext: ['packages/'] });
+
+        expect(LEGACY_PARSER.parse({ actors: [raw] })).toEqual([raw]);
+    });
+
+    it('drops the "mode" discriminator rather than choking on it', () => {
+        expect(LEGACY_PARSER.parse({ mode: 'legacy', actors: [entry()] })).toEqual([entry()]);
+    });
+
+    it('rejects a file with no "actors" array', () => {
+        expect(() => LEGACY_PARSER.parse({ notActors: [] })).toThrow(/expected array[\s\S]*at actors/);
+    });
+
+    it('rejects an empty "actors" array', () => {
+        expect(() => LEGACY_PARSER.parse({ actors: [] })).toThrow(/Too small/);
+    });
+
+    it.each([
+        ['folder is missing', { folder: undefined }, /at actors\[0\]\.folder/],
+        ['folder is not a string', { folder: 123 }, /at actors\[0\]\.folder/],
+        ['tokenEnvVar is missing', { tokenEnvVar: undefined }, /at actors\[0\]\.tokenEnvVar/],
+        ['overrideActorContext is not an array', { overrideActorContext: 'packages' }, /expected array/],
+        ['overrideActorContext holds non-strings', { overrideActorContext: [123] }, /overrideActorContext\[0\]/],
+    ])('rejects an entry where %s', (_name, fields, expected) => {
+        expect(() => LEGACY_PARSER.parse({ actors: [entry(fields)] })).toThrow(expected);
+    });
+
+    // The "owner/name" halves are checked against the platform's own username/actor-name rules.
+    it.each([
+        ['no slash', 'shopify-scraper'],
+        ['an empty owner', '/shopify'],
+        ['an empty name', 'myteam/'],
+        ['more than two halves', 'myteam/shopify/extra'],
+    ])('rejects an actorFullName with %s', (_name, actorFullName) => {
+        expect(() => LEGACY_PARSER.parse({ actors: [entry({ actorFullName })] })).toThrow(
+            /at actors\[0\]\.actorFullName/,
+        );
+    });
+
+    // Uppercase owners are legal on the platform; ./base.test.ts covers why that is easy to lose.
+    it.each([['myteam/shopify'], ['my.team/web-scraper'], ['my_team/a1'], ['apify/web-scraper'], ['MyTeam/shopify']])(
+        'accepts the actorFullName %s',
+        (actorFullName) => {
+            expect(() => LEGACY_PARSER.parse({ actors: [entry({ actorFullName })] })).not.toThrow();
+        },
+    );
+
+    it('reports every invalid field at once instead of only the first', () => {
+        const message = (() => {
+            try {
+                LEGACY_PARSER.parse({
+                    actors: [{ folder: 123, actorFullName: 'shopify', overrideActorContext: 'nope' }],
+                });
+                throw new Error('Function should have thrown');
+            } catch (err) {
+                return (err as Error).message;
+            }
+        })();
+
+        expect(message).toContain('actors[0].folder');
+        expect(message).toContain('actors[0].actorFullName');
+        expect(message).toContain('actors[0].tokenEnvVar');
+        expect(message).toContain('actors[0].overrideActorContext');
+    });
+});