apify-test-tools 0.10.2-beta.2 → 0.10.2-beta.20

package/bin/actor-ids.ts

@@ -0,0 +1,41 @@
+import { ApifyClient } from 'apify-client';
+
+import { logger } from './logger.js';
+import type { TestTarget } from './stdin-input.js';
+
+type ActorGetter = Pick<ApifyClient, 'actor'>;
+
+/**
+ * Adds the ID each target is missing: the raw ID to those listed by full name, e.g. by `get-actor-configs`, and the
+ * full name to those listed by raw ID. The lib matches a test to its Actor by the ID the test names, so a target
+ * without either ID would skip the tests that name its Actor by the other one.
+ *
+ * An Actor the token can't see keeps only the ID it was listed with, with a warning, rather than failing the run:
+ * `get-actor-configs` lists every Actor in the repository, also ones no platform test uses, such as Actors the tester
+ * account was never given access to. A test that names it by the listed ID still runs and fails on its own.
+ */
+export const withActorIds = async (
+    targets: TestTarget[],
+    client: ActorGetter = new ApifyClient({ token: process.env.TESTER_APIFY_TOKEN }),
+): Promise<TestTarget[]> =>
+    Promise.all(
+        targets.map(async (target) => {
+            const { actorFullName, actorRawId } = target;
+            if (actorFullName && actorRawId) return target;
+            // The parser lets no target through without either ID
+            const actorId = (actorFullName ?? actorRawId)!;
+            const actor = await client.actor(actorId).get();
+            if (!actor) {
+                logger.warn(
+                    `Actor ${actorId} not found, or TESTER_APIFY_TOKEN can't access it. Tests that name it by ` +
+                        `${actorFullName ? 'its raw ID' : 'its full name'} will be skipped.`,
+                );
+                return target;
+            }
+            return {
+                ...target,
+                actorFullName: actorFullName ?? `${actor.username}/${actor.name}`,
+                actorRawId: actorRawId ?? actor.id,
+            };
+        }),
+    );

package/bin/affected-actors.ts

@@ -0,0 +1,211 @@
+import { type ChangedActors, getChangedActors } from './diff-changes.js';
+import {
+    findCommitSha,
+    getChangedFilesBetween,
+    getChangelogAdditions,
+    getCommitsBetween,
+    getMergeBase,
+    resolveCommitSha,
+    resolveReleaseBaseCommit,
+} from './git.js';
+import { logger } from './logger.js';
+import type { ActorConfig, Commit, GitRange } from './types.js';
+import { readConfigFile, readRepoSettings } from './utils/config/load-config.js';
+
+// The range always ends at the checked-out commit: check out what you want to inspect
+const HEAD = 'HEAD';
+
+interface AffectedActorsOptions {
+    /**
+     * Base usually points to the master branch
+     * Only what HEAD changes compared to base counts, like `git diff base...HEAD` or GitHub's "Files changed" tab:
+     * the branch's own changes, not what it merged in from base.
+     */
+    base?: string;
+    /**
+     * With `base` it's the last validated commit of the branch: Actors that didn't change after it are left out.
+     * It's ignored when it is HEAD (a rerun) or isn't in the local history. Without `base` everything after it
+     * counts, and it must be an ancestor of HEAD (e.g. the last release).
+     */
+    since?: string;
+    actors: string[];
+    ignore: string[];
+}
+
+/** The JSON document `get-affected-actors` prints. Versioned, since other commands and workflows consume it. */
+interface AffectedActors {
+    version: 1;
+    head: string;
+    /** The commits, changed files and changelog describe the whole range, `--since` with `--base` only narrows the Actors. */
+    commits: Commit[];
+    changedFiles: string[];
+    changelog: string | null;
+    /**
+     * Actors with at least one functional change. They need a new build and tests. Only the names: the config file
+     * stays the source of truth for the rest.
+     */
+    functionallyChangedActors: { actorFullName: string }[];
+    /**
+     * Actors with cosmetic changes (README, CHANGELOG, cosmetic .actor JSON) and no functional one. They only need a
+     * release build.
+     */
+    cosmeticallyChangedActors: { actorFullName: string }[];
+    /**
+     * Actors whose platform tests (`platformTestsGlob` in the config) changed in their context, whatever else
+     * changed. Their tests need to run, but a test change alone needs no release. An Actor can also be in one of the
+     * lists above.
+     */
+    testChangedActors: { actorFullName: string }[];
+}
+
+const names = (configs: ActorConfig[]) => configs.map(({ actorFullName }) => ({ actorFullName }));
+
+/** The branch's last validated commit, unless it can't narrow anything down. */
+const findValidatedSha = async (since: string, headSha: string): Promise<string | undefined> => {
+    const sinceSha = await findCommitSha(since);
+    if (!sinceSha) {
+        logger.info(
+            `Last validated commit ${since} is not in the local history (force-push?), checking the whole branch`,
+        );
+        return undefined;
+    }
+    if (sinceSha === headSha) {
+        logger.info('Last validated commit is HEAD, so this is a rerun: checking the whole branch from scratch');
+        return undefined;
+    }
+    return sinceSha;
+};
+
+/**
+ * This is Juan's magical algorithm where we need just 2 git diffs to determine functional changes on Actors.
+ *
+ * Naively, we could just check branch HEAD changes vs base or parent of first commit and be done but
+ * we do this jiu-jitsu code to apply 2 optimizations:
+ * 1. On our PR branch, we track last validated commit (since) that was tested and so we only need to test new commits.
+ * 2. We also merge changes from the base branch (usually master) and we can consider those already validated as well.
+ *
+ * But there is annoying problem: even if both our branch and base are validated, they could have novel interactions and
+ * we need to retest those.
+ *
+ * So we look at:
+ * 1. The changes introduced by our branch since the last validated commit (`since..HEAD`).
+ * 2. The changes introduced by the branch compared to the base branch (`base...HEAD`). The important part is that this
+ * diff does check the whole branch, discarding the last validated commit (since) so it checks those novel interactions problem.
+ *
+ * The magic is that both need to contain changes for an Actor to be retested:
+ * 1. If we have changes only in since..HEAD (and not in base...HEAD), it means those changes came from merging the base alone
+ * which is already validated and there were actually no real changes introduced by our branch alone.
+ * 2. If we have changes only in base...HEAD (and not in since..HEAD), it means there are no new changes on our branch
+ * since it was last validated. base...HEAD has changes that we already validated.
+ *
+ * This enables to simply do those 2 diffs for each Actor's context separately and only Actors that have changes
+ * in both diffs need to be retested.
+ *
+ * THIS ASSUMES BRANCH IS UP TO DATE WITH BASE WHEN IT MERGES, which we currently require. Only then is HEAD what lands on
+ * base, and base's commits validated. Otherwise what lands is HEAD combined with base's newer commits, which nobody
+ * tested, however the Actors are picked.
+ *
+ * In each example the branch's functional change to Actor A was validated at `since`, then one more push follows:
+ *
+ * Example scenarios:
+ * - Our own branch only: a commit changes A's README and B's code.
+ *   `since..HEAD`: A cosmetic, B functional. `base...HEAD`: A and B functional.
+ *   → A cosmetic, B functional: only B is tested, A's code is still the validated one.
+ * - Cosmetic merge: the branch merges base, which only changed READMEs and the CHANGELOG.
+ *   `since..HEAD`: every Actor cosmetic (CHANGELOG counts for all). `base...HEAD`: A functional, since the merged
+ *   files now match base and drop out of it.
+ *   → A cosmetic, the other Actors left out: nothing is tested.
+ * - Functional merge: the branch merges base, which changed code of A and of C.
+ *   `since..HEAD`: A and C functional. `base...HEAD`: A functional.
+ *   → A functional, C left out: A is tested, since base's change can interact with the branch's, while C only has
+ *   base's change, which base already validated.
+ */
+const intersectChangedInBranchVsSince = (branch: ChangedActors, sinceValidated: ChangedActors): ChangedActors => {
+    const narrowed: ChangedActors = {
+        functional: [],
+        cosmetic: [],
+        // The same rule for tests: the branch changed them, and they changed again since they were last validated
+        test: branch.test.filter((actor) => sinceValidated.test.includes(actor)),
+    };
+    // All checks are done for each Actor separately, that's cleanest and most accurate
+    for (const actor of [...branch.functional, ...branch.cosmetic]) {
+        // base...HEAD
+        const changedFunctionallyOnBranch = branch.functional.includes(actor);
+        // since..HEAD
+        const changedFunctionallySince = sinceValidated.functional.includes(actor);
+
+        // changedSince is used for release. Release cares also about cosmetic.
+        const changedSince = changedFunctionallySince || sinceValidated.cosmetic.includes(actor);
+
+        // Nothing changed since the last validation, so the branch's change to this Actor is already validated
+        if (!changedSince) continue;
+
+        // As we said, only intersection counts as functional, otherwise it's cosmetic
+        if (changedFunctionallyOnBranch && changedFunctionallySince) {
+            narrowed.functional.push(actor);
+        } else {
+            narrowed.cosmetic.push(actor);
+        }
+    }
+    return narrowed;
+};
+
+/**
+ * Finds the Actors whose context changed in the given range. `base` selects the branch's own changes
+ * (a PR), `since` the changes after a known commit (a release, or the last validated commit of a PR).
+ */
+export const getAffectedActors = async ({
+    base,
+    since: sinceOption,
+    actors,
+    ignore,
+}: AffectedActorsOptions): Promise<AffectedActors> => {
+    // An empty --since (e.g. an empty cache file) means the same as not passing it
+    const since = sinceOption || undefined;
+    if (!base && !since) {
+        throw new Error('Pass --base, --since, or both to select the commits to inspect.');
+    }
+
+    const actorConfigs = await readConfigFile({ actors, ignore });
+    const { platformTestsGlob } = await readRepoSettings();
+    const getChangedInRange = async (range: GitRange) => {
+        const changedFiles = await getChangedFilesBetween(range.fromRef, range.toRef);
+        return {
+            changedFiles,
+            changedActors: await getChangedActors({
+                filepathsChanged: changedFiles,
+                actorConfigs,
+                range,
+                platformTestsGlob,
+            }),
+        };
+    };
+
+    const headSha = await resolveCommitSha(HEAD);
+    const rangeVsBase: GitRange = {
+        // merge base = PR, release base = push to master (release)
+        fromRef: base ? await getMergeBase(base, HEAD) : await resolveReleaseBaseCommit(since!),
+        toRef: headSha,
+    };
+
+    // Falls back to rangeVsBase.fromRef when there's no (usable) last validated commit — same as
+    // intersecting the branch's changes with themselves, which is a no-op (see this function's docs).
+    const validatedSha = base && since ? await findValidatedSha(since, headSha) : undefined;
+    const sinceFromRef = validatedSha ?? rangeVsBase.fromRef;
+
+    const { changedFiles, changedActors: changedVsBase } = await getChangedInRange(rangeVsBase);
+    const { changedActors: changedSinceActors } = await getChangedInRange({ fromRef: sinceFromRef, toRef: headSha });
+    // See this function's docs to understand the algorithm: only intersection counts as functional, otherwise it's cosmetic.
+    const changedActors = intersectChangedInBranchVsSince(changedVsBase, changedSinceActors);
+
+    return {
+        version: 1,
+        head: headSha,
+        commits: await getCommitsBetween(rangeVsBase.fromRef, rangeVsBase.toRef),
+        changedFiles,
+        changelog: await getChangelogAdditions(rangeVsBase.fromRef, rangeVsBase.toRef, changedFiles),
+        functionallyChangedActors: names(changedActors.functional),
+        cosmeticallyChangedActors: names(changedActors.cosmetic),
+        testChangedActors: names(changedActors.test),
+    };
+};

package/bin/build-from-local.ts

@@ -6,7 +6,13 @@ import AdmZip from 'adm-zip';
 import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType } from 'apify-client';
 
-import { ApifyBuilder, LOCAL_SOURCE_VERSION_NUMBER, runAndSummarizeBuilds } from './build.js';
+import {
+    ApifyBuilder,
+    assertEnvVarsMatchDefaultVersion,
+    LOCAL_SOURCE_VERSION_NUMBER,
+    resolveDefaultVersion,
+    runAndSummarizeBuilds,
+} from './build.js';
 import { loadDockerIgnore } from './dockerignore.js';
 import { logger } from './logger.js';
 import { isPathWithinScope } from './path-utils.js';
@@ -190,15 +196,27 @@ type LocalBuildPlan = {
 export const runBuildsFromLocal = async ({
     actorConfigs,
     dryRun,
+    requireEnvVarsInSync = false,
 }: {
     actorConfigs: ActorConfig[];
     dryRun: boolean;
+    // See assertEnvVarsMatchDefaultVersion
+    requireEnvVarsInSync?: boolean;
 }): Promise<BuildData[] | DryRunPlan<LocalBuildPlan>> => {
     // Read-only preparation shared with the real build, so a dry run fails on a missing token, an unknown
     // Actor or unreadable sources just like the build would
     const preparedBuilds = await Promise.all(
         actorConfigs.map(async (actorConfig) => {
             const actorInfo = await ApifyBuilder.fromActorConfig(actorConfig).getActorInfo();
+            if (requireEnvVarsInSync) {
+                const { defaultVersion } = resolveDefaultVersion(actorConfig.actorFullName, actorInfo);
+                assertEnvVarsMatchDefaultVersion(
+                    actorConfig.actorFullName,
+                    actorInfo,
+                    defaultVersion,
+                    LOCAL_SOURCE_VERSION_NUMBER,
+                );
+            }
             // Zipped and uploaded like `apify push` does, since inline SOURCE_FILES are capped at ~9 MB.
             const zip = new AdmZip();
             const sourceFiles = await collectSourceFiles(actorConfig);

package/bin/build.ts

@@ -1,22 +1,21 @@
 import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType, ApifyClient } from 'apify-client';
 
-import { normalizeRepoUrl } from './git.js';
+import { getCurrentBranch, normalizeRepoUrl, resolveRepoUrl } from './git.js';
 import { logger } from './logger.js';
 import type { ActorConfig, BuildData, DryRunPlan } from './types.js';
 
 type BuildPrActorOptions = {
-    buildTag?: string;
     versionNumber: string;
     gitRepoUrl: string;
     actorConfig: ActorConfig;
     actorInfo: ApifyClientTypes.Actor;
-    useDockerCache: boolean;
 };
 
 // Fixed version number used to build from local source files, since there is no real version to track.
 export const LOCAL_SOURCE_VERSION_NUMBER = '0.98';
-const DEFAULT_TEST_VERSION_NUMBER = '0.99';
+// Stands for each Actor's default version: the one its default build tag points to
+export const DEFAULT_VERSION_KEYWORD = 'default';
 
 // Shown whenever an Actor isn't set up the way CI builds need it
 const ACTOR_SETUP_REQUIREMENT =
@@ -83,6 +82,44 @@ export const assertRepoUrlMatchesDefaultVersion = (
     }
 };
 
+const getEnvVarNames = (version: ApifyClientTypes.ActorVersion | undefined): string[] =>
+    (version?.envVars ?? []).map(({ name }) => name).filter((name): name is string => !!name);
+
+/**
+ * Guards against testing an Actor with different env vars than users run it with, e.g. a variable added to
+ * the default version but not to the test version, which would make the tests pass or fail for the wrong
+ * reason. Only names are compared because the API doesn't return secret values.
+ */
+export const assertEnvVarsMatchDefaultVersion = (
+    actorFullName: string,
+    actorInfo: ApifyClientTypes.Actor,
+    defaultVersion: ApifyClientTypes.ActorVersion | undefined,
+    versionNumber: string,
+) => {
+    if (!defaultVersion) {
+        throw new Error(
+            `[${actorFullName}] The version of the default build no longer exists. ${ACTOR_SETUP_REQUIREMENT}`,
+        );
+    }
+    const version = actorInfo.versions.find((v) => v.versionNumber === versionNumber);
+    const defaultNames = getEnvVarNames(defaultVersion);
+    const names = getEnvVarNames(version);
+    const missing = defaultNames.filter((name) => !names.includes(name));
+    const extra = names.filter((name) => !defaultNames.includes(name));
+    if (missing.length === 0 && extra.length === 0) return;
+
+    const differences = [
+        missing.length > 0 ? `missing ${missing.join(', ')}` : undefined,
+        extra.length > 0 ? `extra ${extra.join(', ')}` : undefined,
+    ].filter(Boolean);
+    throw new Error(
+        `[${actorFullName}] Env vars of version ${versionNumber} are out of sync with default version ` +
+            `${defaultVersion.versionNumber} (${differences.join('; ')}). ` +
+            `${version ? '' : `Version ${versionNumber} doesn't exist yet, so create it on the platform first. `}` +
+            `Add or remove the env vars in version ${versionNumber} so their names match the default version's.`,
+    );
+};
+
 export class ApifyBuilder {
     private constructor(
         private readonly apifyClient: ApifyClient,
@@ -206,7 +243,7 @@ export class ApifyBuilder {
 
         const actorInfo = await this.getActorInfo();
 
-        // 'devel' used to be hardcoded for testing version 0.99, once we get rid of this tag everywhere, we can remove this code
+        // A build tagged 'devel' is kept for DEFAULT_DAYS_BACK_DEVEL only. Remove this once no Actor has the tag
         const taggedDevelBuildNumber: string | undefined = actorInfo.taggedBuilds!.devel?.buildNumber;
 
         const allTags = Object.keys(actorInfo.taggedBuilds ?? {});
@@ -319,20 +356,20 @@ export const runAndSummarizeBuilds = async (
 type GitBuildPlan = {
     actorFullName: string;
     versionNumber: string;
-    buildTag?: string;
     gitRepoUrl: string;
-    useDockerCache: boolean;
 };
 
 type RunBuildsOptions = {
     actorConfigs: ActorConfig[];
-    isLatest?: boolean;
+    // A version number like "0.99", or DEFAULT_VERSION_KEYWORD for each Actor's default version
+    versionNumber: string;
     repoUrl: string;
     // False when the repo URL was passed explicitly, see assertRepoUrlMatchesDefaultVersion
     shouldVerifyRepoUrl: boolean;
     branch: string;
     dryRun: boolean;
-    useDockerCache: boolean;
+    // See assertEnvVarsMatchDefaultVersion
+    requireEnvVarsInSync?: boolean;
 };
 
 export const runBuilds = async ({
@@ -340,9 +377,9 @@ export const runBuilds = async ({
     shouldVerifyRepoUrl,
     branch,
     actorConfigs,
-    isLatest = false,
+    versionNumber,
     dryRun,
-    useDockerCache,
+    requireEnvVarsInSync = false,
 }: RunBuildsOptions): Promise<BuildData[] | DryRunPlan<GitBuildPlan>> => {
     // Fetched once per Actor and reused for the checks, the version numbers and the build itself
     const buildConfigs: BuildPrActorOptions[] = await Promise.all(
@@ -352,9 +389,28 @@ export const runBuilds = async ({
                 actorConfig.actorFullName,
                 actorInfo,
             );
+            // Builds keep the tags their version gives them, so a default version without the default build tag
+            // would build fine but leave users on the previous build
+            if (versionNumber === DEFAULT_VERSION_KEYWORD && defaultVersion?.buildTag !== defaultBuildTag) {
+                logger.warn(
+                    `[${actorConfig.actorFullName}] Default version ${defaultVersionNumber} has build tag ` +
+                        `"${defaultVersion?.buildTag ?? 'none'}", not "${defaultBuildTag}", so users keep running the previous build. ` +
+                        'Set the build tag of the version on the platform to change that.',
+                );
+            }
             if (shouldVerifyRepoUrl) {
                 assertRepoUrlMatchesDefaultVersion(actorConfig.actorFullName, defaultVersion, repoUrl);
             }
+            const targetVersionNumber =
+                versionNumber === DEFAULT_VERSION_KEYWORD ? defaultVersionNumber : versionNumber;
+            if (requireEnvVarsInSync) {
+                assertEnvVarsMatchDefaultVersion(
+                    actorConfig.actorFullName,
+                    actorInfo,
+                    defaultVersion,
+                    targetVersionNumber,
+                );
+            }
 
             // Depending on if these are miniactors or standaloneActors
             let gitRepoUrl = `${repoUrl}#${branch}`;
@@ -365,9 +421,7 @@ export const runBuilds = async ({
                 actorConfig,
                 actorInfo,
                 gitRepoUrl,
-                versionNumber: isLatest ? defaultVersionNumber : DEFAULT_TEST_VERSION_NUMBER,
-                buildTag: isLatest ? defaultBuildTag : undefined,
-                useDockerCache,
+                versionNumber: targetVersionNumber,
             };
         }),
     );
@@ -375,21 +429,15 @@ export const runBuilds = async ({
     // Everything above only reads, so a dry run has checked what the real run would, short of writing
     if (dryRun) {
         logger.info('[DRY RUN] Would build:');
-        for (const { actorConfig, versionNumber, gitRepoUrl } of buildConfigs) {
-            logger.info(`  ${actorConfig.actorFullName} (${versionNumber}) from ${gitRepoUrl}`);
+        const builds = buildConfigs.map((buildConfig) => ({
+            actorFullName: buildConfig.actorConfig.actorFullName,
+            versionNumber: buildConfig.versionNumber,
+            gitRepoUrl: buildConfig.gitRepoUrl,
+        }));
+        for (const build of builds) {
+            logger.info(`  ${build.actorFullName} (${build.versionNumber}) from ${build.gitRepoUrl}`);
         }
-        return {
-            dryRun: true,
-            builds: buildConfigs.map(
-                ({ actorConfig, versionNumber, buildTag, gitRepoUrl, useDockerCache: useCache }) => ({
-                    actorFullName: actorConfig.actorFullName,
-                    versionNumber,
-                    buildTag,
-                    gitRepoUrl,
-                    useDockerCache: useCache,
-                }),
-            ),
-        };
+        return { dryRun: true, builds };
     }
 
     const buildConfigsByActorFullName = new Map(
@@ -397,20 +445,38 @@ export const runBuilds = async ({
     );
 
     return runAndSummarizeBuilds(actorConfigs, 'BUILDS', async (actorConfig, builder) => {
-        const {
-            actorInfo,
-            buildTag,
-            versionNumber,
-            gitRepoUrl,
-            useDockerCache: useCache,
-        } = buildConfigsByActorFullName.get(actorConfig.actorFullName)!;
+        const buildConfig = buildConfigsByActorFullName.get(actorConfig.actorFullName)!;
+        // No buildTag: the version keeps the one it has, so its build gets the tag the version already gives it
         const actorVersion: ApifyClientTypes.ActorVersion = {
-            buildTag,
-            versionNumber,
-            gitRepoUrl,
+            versionNumber: buildConfig.versionNumber,
+            gitRepoUrl: buildConfig.gitRepoUrl,
             sourceType: ActorSourceType.GitRepo,
         };
-        return builder.createVersionAndBuild(versionNumber, actorVersion, useCache, actorInfo);
+        // Always with the Docker cache: CI always asked for it, and a clean build can still be started on the platform
+        return builder.createVersionAndBuild(buildConfig.versionNumber, actorVersion, true, buildConfig.actorInfo);
+    });
+};
+
+type BuildActorsOptions = Omit<RunBuildsOptions, 'repoUrl' | 'shouldVerifyRepoUrl' | 'branch'> & {
+    // Defaults to the `origin` remote, see resolveRepoUrl
+    repoUrl?: string;
+};
+
+/**
+ * Builds exactly the given Actors from the checked-out Git branch, as it is on the remote. Fails on a detached HEAD,
+ * where there is no branch to build. Used by `build` and the commands built on top of it.
+ */
+export const buildActors = async ({ actorConfigs, repoUrl, ...options }: BuildActorsOptions) => {
+    if (actorConfigs.length === 0) {
+        logger.info('No Actors to build');
+        // Still the dry-run shape in a dry run, so it can't pass for a real (empty) result
+        return options.dryRun ? { dryRun: true as const, builds: [] } : [];
+    }
+    return runBuilds({
+        ...options,
+        ...(await resolveRepoUrl(repoUrl)),
+        actorConfigs,
+        branch: await getCurrentBranch(),
     });
 };