apify-test-tools 0.10.2-beta.0 → 0.10.2-beta.10

package/bin/diff-changes.ts

@@ -1,14 +1,18 @@
+import picomatch from 'picomatch';
+
 import { isCosmeticOnlyJsonSchemaChange } from './diff-json-schema.js';
 import { type DockerIgnoreMatcher, loadDockerIgnore } from './dockerignore.js';
 import { logger } from './logger.js';
-import type { ActorConfig, Commit } from './types.js';
+import type { ActorConfig, GitRange } from './types.js';
 import { type RelativeDir, RelativeFile } from './utils/path/repo-relative.js';
 
 interface ShouldBuildAndTestOptions {
     filepathsChanged: string[];
     actorConfigs: ActorConfig[];
-    isLatest?: boolean;
-    commits: Commit[];
+    /** The range the files changed in, to compare `.actor` JSON files across. */
+    range: GitRange;
+    // Glob relative to the repo root. Matching files count as changes even when .dockerignore lists them.
+    testFilesGlob?: string;
 }
 
 const IGNORED_TOP_LEVEL_FILES = [
@@ -41,7 +45,7 @@ type FileChangeForActor =
  * 2. Context matching (actorConfig.contextPaths) → outside-context if no match
  * 3. Hardcoded ignore list, checked against the path hoisted relative to the matched context entry → ignored
  * 4. .dockerignore filtering (patterns relative to dockerContextDir), skipped for the actor's own `.actor/`
- *    dir → ignored if matched
+ *    dir and for test files → ignored if matched
  * 5. README.md by filename → cosmetic if inside the actor's own folder, otherwise ignored
  * 6. .json inside the actor's own `.actor/` dir with only cosmetic schema diffs → cosmetic (semantically verified)
  * 7. Everything else → functional
@@ -49,8 +53,9 @@ type FileChangeForActor =
 const classifyFileChange = async (
     changedFile: RelativeFile,
     actorConfig: ActorConfig,
-    commits: Commit[],
+    range: GitRange,
     dockerIgnoreMatcher: DockerIgnoreMatcher,
+    isTestFile: (filePath: string) => boolean,
 ): Promise<FileChangeForActor> => {
     const lowercaseFilePath = changedFile.path.toLowerCase();
 
@@ -75,7 +80,8 @@ const classifyFileChange = async (
     // .actor/ can legitimately be listed in .dockerignore (the Apify platform evaluates it before
     // the Docker build, so excluding it from the build context is a valid caching optimization) —
     // that shouldn't cause changes to .actor/ itself to be ignored here.
-    if (!isUnderActorDotDir && dockerIgnoreMatcher(changedFile.path)) {
+    // Test files are often in .dockerignore too, but a change to them must still build and test.
+    if (!isUnderActorDotDir && !isTestFile(changedFile.path) && dockerIgnoreMatcher(changedFile.path)) {
         return { impact: 'ignored' };
     }
 
@@ -86,7 +92,7 @@ const classifyFileChange = async (
     }
 
     if (lowercaseFilePath.endsWith('.json') && isUnderActorDotDir) {
-        const isCosmetic = await isCosmeticOnlyJsonSchemaChange(commits, changedFile.path);
+        const isCosmetic = await isCosmeticOnlyJsonSchemaChange(range, changedFile.path);
         if (isCosmetic) return { impact: 'cosmetic', semanticallyVerified: true };
     }
 
@@ -106,6 +112,7 @@ const isExcludedBySibling = (filePath: RelativeFile, actor: ActorConfig, allActo
 type ActorChangeEntry = {
     actorConfig: ActorConfig;
     files: string[];
+    hasFunctionalChange: boolean;
 };
 
 type ChangeGroup = { actors: string[]; files: string[] };
@@ -158,13 +165,23 @@ const logChangeGroups = (groups: ChangeGroup[]): void => {
     }
 };
 
+export interface ChangedActors {
+    /** Actors with at least one functional change. They need a new build and tests. */
+    functional: ActorConfig[];
+    /** Actors whose changes are all cosmetic. They only need a new build when released. */
+    cosmetic: ActorConfig[];
+}
+
+/** Finds the Actors the changed files belong to, split by the most impactful change each Actor has. */
 export const getChangedActors = async ({
     filepathsChanged,
     actorConfigs,
-    isLatest = false,
-    commits,
-}: ShouldBuildAndTestOptions): Promise<ActorConfig[]> => {
+    range,
+    testFilesGlob,
+}: ShouldBuildAndTestOptions): Promise<ChangedActors> => {
     const actorsChangedMap = new Map<string, ActorChangeEntry>();
+    const testFilesInContext = new Set<string>();
+    const isTestFile = testFilesGlob ? picomatch(testFilesGlob, { nocase: true, dot: true }) : () => false;
 
     for (const actorConfig of actorConfigs) {
         const dockerIgnoreMatcher = loadDockerIgnore(actorConfig.dockerContextDir);
@@ -176,31 +193,44 @@ export const getChangedActors = async ({
                 continue;
             }
 
-            const change = await classifyFileChange(filePath, actorConfig, commits, dockerIgnoreMatcher);
+            const change = await classifyFileChange(filePath, actorConfig, range, dockerIgnoreMatcher, isTestFile);
+            if (change.impact !== 'outside-context' && isTestFile(originalFilePath)) {
+                testFilesInContext.add(originalFilePath);
+            }
 
             if (change.impact === 'ignored' || change.impact === 'outside-context') continue;
-            if (change.impact === 'cosmetic' && !isLatest) continue;
 
-            const entry = actorsChangedMap.get(actorConfig.folder.path) ?? { actorConfig, files: [] };
+            const entry = actorsChangedMap.get(actorConfig.folder.path) ?? {
+                actorConfig,
+                files: [],
+                hasFunctionalChange: false,
+            };
             entry.files.push(originalFilePath);
+            entry.hasFunctionalChange ||= change.impact === 'functional';
             actorsChangedMap.set(actorConfig.folder.path, entry);
         }
     }
 
-    const actorsChanged = Array.from(actorsChangedMap.values()).map((entry) => entry.actorConfig);
-
     // Log changes grouped by actor set, so changes shared across actors are logged once
     // instead of being repeated per actor.
-    const fileToActors = buildFileToActorsMap(actorsChangedMap);
-    const groups = groupFilesByActorSet(fileToActors);
-    logChangeGroups(groups);
-
-    if (actorsChanged.length > 0) {
-        const actors = actorsChanged.map((config) => config.actorFullName);
-        logger.info(`[DIFF]: Actors to be built and tested: ${actors.join(', ')}`);
-    } else {
-        logger.info(`[DIFF]: No relevant files changed, skipping builds and tests`);
+    logChangeGroups(groupFilesByActorSet(buildFileToActorsMap(actorsChangedMap)));
+
+    for (const testFile of filepathsChanged.filter(
+        (filePath) => isTestFile(filePath) && !testFilesInContext.has(filePath),
+    )) {
+        logger.warn(
+            `[DIFF]: Test file ${testFile} is outside every Actor's context, so changing only it builds and tests nothing. ` +
+                `Add its folder to "overrideActorContext" of the Actors it tests.`,
+        );
     }
 
-    return actorsChanged;
+    const entries = Array.from(actorsChangedMap.values());
+    const functional = entries.filter((entry) => entry.hasFunctionalChange).map((entry) => entry.actorConfig);
+    const cosmetic = entries.filter((entry) => !entry.hasFunctionalChange).map((entry) => entry.actorConfig);
+
+    const names = (configs: ActorConfig[]) => configs.map((config) => config.actorFullName).join(', ') || 'none';
+    logger.info(`[DIFF]: Actors with functional changes: ${names(functional)}`);
+    logger.info(`[DIFF]: Actors with only cosmetic changes: ${names(cosmetic)}`);
+
+    return { functional, cosmetic };
 };

package/bin/diff-json-schema.ts

@@ -1,5 +1,5 @@
 import { logger } from './logger.js';
-import type { Commit } from './types.js';
+import type { GitRange } from './types.js';
 import { runGitCommand } from './utils.js';
 
 const COSMETIC_JSON_FIELD_NAMES = new Set([
@@ -29,11 +29,10 @@ const isCosmeticObjectChange = (oldVal: unknown, newVal: unknown, currentKey?: s
  * Returns true if the two JSON strings differ only in cosmetic fields
  * (title, description, example, enumTitles, sectionCaption, sectionDescription).
  */
-export const isCosmeticOnlyJsonSchemaChange = async (commits: Commit[], changedFilepath: string): Promise<boolean> => {
-    // TODO: validate this is the right commit range
-    const oldRef = `${commits[0].sha}~`;
-    const newRef = commits[commits.length - 1].sha;
-
+export const isCosmeticOnlyJsonSchemaChange = async (
+    { fromRef: oldRef, toRef: newRef }: GitRange,
+    changedFilepath: string,
+): Promise<boolean> => {
     const [oldJson, newJson] = await Promise.all([
         runGitCommand(['show', `${oldRef}:${changedFilepath}`])
             .then(JSON.parse)

package/bin/git.ts

@@ -5,80 +5,56 @@ import { GitCommandError, runGitCommand } from './utils.js';
 export const GIT_FORMAT_SEPARATOR = '»¦«';
 const GIT_LOG_FORMAT = ['%H', '%aN<%aE>', '%aD', '%s'].join(GIT_FORMAT_SEPARATOR);
 
+// Lists the changed paths. With rename detection (on by default) a moved file is listed only under its new path,
+// so the Actor whose context it left wouldn't count as changed. --no-renames lists it as deleted and added instead.
+const LIST_CHANGED_PATHS = ['--name-only', '--no-renames'];
+
 /**
- * Gets the list of changed files between the given commits (inclusive).
+ * Gets the list of changed files between the given commits (inclusive), so it diffs from the parent of the oldest.
  */
 export const getChangedFiles = async (commits: Commit[]) => {
-    // getCommits never returns an empty list (the rerun check returns all commits when the base commit
-    // is the branch HEAD, and an empty git range throws when parsing), so this signals a programmer error
+    // getCommits never returns an empty list (it throws on an empty range, and the rerun check returns all
+    // commits when the base commit is the branch HEAD), so this signals a programmer error
     if (commits.length === 0) {
         throw new Error('Cannot get changed files: the commit list is empty. This should never happen.');
     }
 
-    const changedFilesString = await runGitCommand(
-        ['diff', '--name-only', `${commits[0].sha}~..${commits[commits.length - 1].sha}`],
-        { operation: 'get the list of changed files between commits' },
-    );
-
-    const changedFiles = changedFilesString.split('\n').filter(Boolean);
-    logger.info(`Changed files (up to 50): ${changedFiles.slice(0, 50).join(', ')}`);
-    return changedFiles;
+    return getChangedFilesBetween(`${commits[0].sha}~`, commits[commits.length - 1].sha);
 };
 
 /**
- * Returns true if the branch contains a merge commit whose parent is reachable from targetBranch
- * (i.e. a genuine "merge from target" commit, not a merge of some unrelated branch).
- * Uses the full targetBranch..sourceBranch range, ignoring baseCommit.
+ * Files that differ between two commits, i.e. changed by the commits in the range (fromRef, toRef]. fromRef's own
+ * changes are not included: to include them, pass its parent, `${sha}~` (as getChangedFiles does).
+ * Diffing the endpoints, rather than walking a commit list, is what keeps merges right: the oldest commit of a
+ * merged branch can predate fromRef, and its changes are already in fromRef.
  */
-export const hasMergeFromTarget = async (sourceBranch: string, targetBranch: string): Promise<boolean> => {
-    const mergeShas = (
-        await runGitCommand(['log', '--merges', '--pretty=format:%H', `${targetBranch}..${sourceBranch}`], {
-            operation: 'find merge commits on the source branch that are absent from the target branch',
-        })
-    )
-        .split('\n')
-        .filter(Boolean);
+export const getChangedFilesBetween = async (fromRef: string, toRef: string) => {
+    const changedFilesString = await runGitCommand(['diff', ...LIST_CHANGED_PATHS, `${fromRef}..${toRef}`], {
+        operation: 'get the list of changed files between commits',
+    });
 
-    for (const sha of mergeShas) {
-        const parents = (
-            await runGitCommand(['log', '-1', '--pretty=format:%P', sha], {
-                operation: 'get parents of a merge commit',
-            })
-        ).split(' ');
-        for (const parent of parents) {
-            // git merge-base A B outputs the common ancestor.
-            // If that equals A, then A is an ancestor of B (i.e. parent is reachable from targetBranch).
-            let mergeBase: string;
-            try {
-                mergeBase = await runGitCommand(['merge-base', parent, targetBranch], {
-                    operation: 'check whether a merge parent is reachable from the target branch',
-                });
-            } catch (error) {
-                // Exit code 1 on merge-base means the histories have no common ancestor.
-                if (error instanceof GitCommandError && error.exitCode === 1) {
-                    continue;
-                }
-                throw error;
-            }
-            if (mergeBase === parent) {
-                return true;
-            }
-        }
-    }
-    return false;
+    const changedFiles = changedFilesString.split('\n').filter(Boolean);
+    logger.info(`Changed files (up to 50): ${changedFiles.slice(0, 50).join(', ')}`);
+    return changedFiles;
 };
 
 /**
- * Returns all files touched by non-merge commits on the branch (full history, ignoring baseCommit).
- * Used to check whether the branch itself has any functional changes, independent of what master merged in.
+ * The commit `git diff base...head` compares against: where `head` forked from `base`, or the last commit of `base`
+ * that `head` merged in. The diff from it holds only what `head` itself changed, like GitHub's "Files changed" tab.
+ * With criss-cross merges there are several such commits and git picks one.
  */
-export const getBranchOnlyChangedFiles = async (sourceBranch: string, targetBranch: string): Promise<string[]> => {
-    const output = await runGitCommand(
-        ['log', '--no-merges', '--name-only', '--pretty=format:', `${targetBranch}..${sourceBranch}`],
-        { operation: 'list files changed by non-merge commits on the source branch' },
-    );
-    return output.split('\n').filter(Boolean);
-};
+export const getMergeBase = async (base: string, head: string): Promise<string> =>
+    runGitCommand(['merge-base', base, head], { operation: `find where ${head} forked from ${base}` });
+
+/** Resolves a ref to a commit, or undefined when it isn't in the local history (e.g. it was force-pushed away). */
+export const findCommitSha = async (ref: string): Promise<string | undefined> =>
+    runGitCommand(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
+        operation: `look up ${ref} in local Git history`,
+    }).catch((error: unknown) => {
+        // --quiet suppresses Git's error text for a missing commit, but Git still exits with code 1
+        if (error instanceof GitCommandError && error.exitCode === 1) return undefined;
+        throw error;
+    });
 
 const SHA_REGEX = /^[0-9a-f]{40}$/i;
 
@@ -103,13 +79,16 @@ export const parseBaseCommit = (shaOrCommit: string | undefined): string | undef
     return sha;
 };
 
-const fetchAllBranchCommits = async (sourceBranch: string, targetBranch: string): Promise<Commit[]> => {
-    const output = await runGitCommand(
-        ['log', `--pretty=format:${GIT_LOG_FORMAT}`, `${targetBranch}..${sourceBranch}`],
-        { operation: 'list commits reachable from the source ref but absent from the target ref' },
-    );
-    const commitsStrings = output.split('\n');
-    const commits = commitsStrings.map((commitString) => parseCommit(commitString));
+/**
+ * Commits reachable from toRef but not from fromRef, oldest first: the range (fromRef, toRef], so fromRef itself is
+ * not included. To include it, pass its parent, `${sha}~`.
+ */
+export const getCommitsBetween = async (fromRef: string, toRef: string): Promise<Commit[]> => {
+    const output = await runGitCommand(['log', `--pretty=format:${GIT_LOG_FORMAT}`, `${fromRef}..${toRef}`], {
+        operation: 'list commits reachable from the source ref but absent from the target ref',
+    });
+    // An empty range (e.g. `x..x`) prints nothing
+    const commits = output.split('\n').filter(Boolean).map(parseCommit);
     commits.reverse();
     return commits;
 };
@@ -124,7 +103,10 @@ export const getCommits = async ({
     baseCommit,
 }: Pick<Config, 'sourceBranch' | 'targetBranch' | 'baseCommit'>): Promise<Commit[]> => {
     const baseCommitSha = parseBaseCommit(baseCommit);
-    const commits = await fetchAllBranchCommits(sourceBranch, targetBranch);
+    const commits = await getCommitsBetween(targetBranch, sourceBranch);
+    if (commits.length === 0) {
+        throw new Error(`${sourceBranch} has no commits that are not on ${targetBranch}.`);
+    }
 
     // The last validated (base) commit being the branch HEAD means nothing new was pushed since the last
     // validation — the dev reran the workflow (or force-pushed to the same state) to trigger a clean test
@@ -169,21 +151,25 @@ export const parseCommit = (commitString: string): Commit => {
 };
 
 /**
- * Returns the currently checked-out branch. Release builds point the Actor version at this branch,
+ * Returns the currently checked-out branch. Builds point the Actor version at this branch,
  * so a detached HEAD (no branch to point at) is an error rather than a guess.
  */
 export const getCurrentBranch = async (): Promise<string> => {
     const branch = await runGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], {
-        operation: 'determine the current branch for release',
+        operation: 'determine the checked-out branch',
     });
     if (branch === 'HEAD') {
         throw new Error(
-            'Cannot determine the branch to release: HEAD is detached. Check out the branch you want to release.',
+            'Cannot determine the branch to build from: HEAD is detached. Check out the branch you want to build.',
         );
     }
     return branch;
 };
 
+/** Resolves a ref (branch, remote branch, SHA, HEAD, ...) to the full SHA of the commit it points to. */
+export const resolveCommitSha = async (ref: string): Promise<string> =>
+    runGitCommand(['rev-parse', '--verify', `${ref}^{commit}`], { operation: `resolve ${ref} to a commit` });
+
 /**
  * Reads the repository URL from the `origin` remote, rewritten to the SSH form the Apify platform
  * uses for Git repo sources, e.g. git@github.com:apify-store/google-maps
@@ -236,15 +222,15 @@ const ZERO_SHA_REGEX = /^0{40}$/;
  * Unlike the PR path (getCommits), there is no lenient fallback. Falling back to "everything"
  * would rebuild the latest build of every Actor and post it to Slack, so every problem is an error.
  */
-export const resolveReleaseBaseCommit = async (baseCommit: string): Promise<string> => {
+export const resolveReleaseBaseCommit = async (baseCommit: string, head = 'HEAD'): Promise<string> => {
     const sha = parseBaseCommit(baseCommit);
     if (!sha) {
-        throw new Error('--base-commit is required for release. See the README section "Releasing Actors".');
+        throw new Error('A base commit is required for release. See the "Releasing Actors" section of docs/cli.md.');
     }
     if (ZERO_SHA_REGEX.test(sha)) {
         throw new Error(
             `Base commit is ${sha}, which means the branch was just created and there is no previous release to diff against. ` +
-                `Rerun with --base-commit set to the last commit before the changes you want to release.`,
+                `Rerun with the base commit set to the last commit before the changes you want to release.`,
         );
     }
     // --quiet suppresses Git's error text for a missing commit, but Git still exits with code 1.
@@ -261,16 +247,16 @@ export const resolveReleaseBaseCommit = async (baseCommit: string): Promise<stri
         );
     }
     // git merge-base A B outputs the common ancestor. If that equals A, then A is an ancestor of B.
-    const mergeBase = await runGitCommand(['merge-base', verifiedSha, 'HEAD'], {
-        operation: 'check whether the release base commit is an ancestor of HEAD',
+    const mergeBase = await runGitCommand(['merge-base', verifiedSha, head], {
+        operation: `check whether the release base commit is an ancestor of ${head}`,
     }).catch((error: unknown) => {
         if (error instanceof GitCommandError && error.exitCode === 1) return '';
         throw error;
     });
     if (mergeBase !== sha) {
         throw new Error(
-            `Base commit ${sha} is not an ancestor of HEAD, most likely because the branch was force-pushed. ` +
-                `The changed files cannot be determined reliably. Rerun with --base-commit set to an ancestor of HEAD ` +
+            `Base commit ${sha} is not an ancestor of ${head}, most likely because the branch was force-pushed. ` +
+                `The changed files cannot be determined reliably. Rerun with the base commit set to an ancestor of ${head} ` +
                 `from before the changes you want to release.`,
         );
     }
@@ -279,12 +265,16 @@ export const resolveReleaseBaseCommit = async (baseCommit: string): Promise<stri
 
 const CHANGELOG_PATH = 'CHANGELOG.md';
 
-/** Returns the lines added to the root CHANGELOG.md between baseSha and HEAD, or null if it didn't change. */
-const getChangelogAdditions = async (baseSha: string, changedFiles: string[]): Promise<string | null> => {
+/** Returns the lines added to the root CHANGELOG.md between fromRef and toRef, or null if it didn't change. */
+export const getChangelogAdditions = async (
+    fromRef: string,
+    toRef: string,
+    changedFiles: string[],
+): Promise<string | null> => {
     if (!changedFiles.includes(CHANGELOG_PATH)) {
         return null;
     }
-    const diff = await runGitCommand(['diff', baseSha, 'HEAD', '--', CHANGELOG_PATH], {
+    const diff = await runGitCommand(['diff', fromRef, toRef, '--', CHANGELOG_PATH], {
         operation: 'read changelog changes since the last release',
     });
 
@@ -307,23 +297,3 @@ const getChangelogAdditions = async (baseSha: string, changedFiles: string[]): P
     }
     return added.join('\n').trim();
 };
-
-/**
- * Everything that changed since the last release (baseSha, exclusive) up to HEAD, or null when there
- * are no new commits. Changed files come from diffing the range directly instead of from the commit
- * list: with a merge commit, the oldest commit of the merged branch can be older than baseSha, and
- * diffing from its parent would pull in already-released changes.
- */
-export const getReleaseChanges = async (baseSha: string) => {
-    if (
-        (await runGitCommand(['rev-parse', 'HEAD'], { operation: 'identify the current release commit' })) === baseSha
-    ) {
-        return null;
-    }
-    const commits = await fetchAllBranchCommits('HEAD', baseSha);
-    const changedFiles = await runGitCommand(['diff', '--name-only', baseSha, 'HEAD'], {
-        operation: 'list files changed since the last release',
-    }).then((output) => output.split('\n').filter(Boolean));
-    const changelog = await getChangelogAdditions(baseSha, changedFiles);
-    return { commits, changedFiles, changelog };
-};