Simplify monorepo-workflow-utils tests

The tests for `monorepo-workflow-utils.ts` are not as readable or
maintainable as I'd like them to be. This commit attempts to fix that:

* While there isn't a whole lot we can do in terms of the scenarios
  we're testing because the function makes a lot of calls and the logic
  inside of it is somewhat complicated, we can at least move
  code that is responsible for parsing the TODAY environment variable,
  building a ReleasePlan object from the release spec, and applying the
  updates to the repos themselves out into separate files. This
  simplifies the test data and removes a few tests entirely.
* We can also simplify how `planRelease` (one of the things we moved
  out) works so that instead of checking whether the
  version-to-be-released for a package is the same as the package's
  current version there, we can check for that in
  `validateReleaseSpecification`.
* We also simplify the structure of the tests so that we aren't using so
  many nested `describe` blocks. This ends up being very difficult to
  keep straight in one's head, so the flattened layout here makes it a
  little more palatable.
* Finally, we simplify the setup code for each test. Currently we are
  mocking all of the dependencies for `followMonorepoWorkflow` in one
  go, but we're doing so in a way that forces the reader to wade through
  a bunch of type definitions. That isn't really that helpful. The most
  complicated part of reading the tests for `followMonorepoWorkflow`
  isn't the dependencies — it's the logic. So we take all of the
  decision points we have to make in the implementation and represent
  those as options to our setup function in the tests so it's as clear
  as possible which exact scenario is being tested just by reading the
  test.

Author: mcmire

src/git-utils.test.ts

@@ -3,6 +3,7 @@ import * as miscUtils from './misc-utils';
 import {
   getStdoutFromGitCommandWithin,
   getRepositoryHttpsUrl,
+  captureChangesInReleaseBranch,
 } from './git-utils';
 
 jest.mock('./misc-utils');
@@ -79,4 +80,34 @@ describe('git-utils', () => {
       );
     });
   });
+
+  describe('captureChangesInReleaseBranch', () => {
+    it('checks out a new branch, stages all files, and creates a new commit', async () => {
+      const getStdoutFromCommandSpy = jest.spyOn(
+        miscUtils,
+        'getStdoutFromCommand',
+      );
+
+      await captureChangesInReleaseBranch(
+        '/path/to/project',
+        'some-release-name',
+      );
+
+      expect(getStdoutFromCommandSpy).toHaveBeenCalledWith(
+        'git',
+        ['checkout', '-b', 'release/some-release-name'],
+        { cwd: '/path/to/project' },
+      );
+      expect(getStdoutFromCommandSpy).toHaveBeenCalledWith(
+        'git',
+        ['add', '-A'],
+        { cwd: '/path/to/project' },
+      );
+      expect(getStdoutFromCommandSpy).toHaveBeenCalledWith(
+        'git',
+        ['commit', '-m', 'Release some-release-name'],
+        { cwd: '/path/to/project' },
+      );
+    });
+  });
 });

src/git-utils.ts

@@ -78,3 +78,37 @@ export async function getRepositoryHttpsUrl(
 
   throw new Error(`Unrecognized URL for git remote "origin": ${gitConfigUrl}`);
 }
+
+/**
+ * This function does three things:
+ *
+ * 1. Stages all of the changes which have been made to the repo thus far and
+ *    creates a new Git commit which carries the name of the new release.
+ * 2. Creates a new branch pointed to that commit (which also carries the name
+ *    of the new release).
+ * 3. Switches to that branch.
+ *
+ * @param projectRepositoryPath - The path to the project directory.
+ * @param releaseName - The name of the release, which will be used to name the
+ * commit and the branch.
+ */
+export async function captureChangesInReleaseBranch(
+  projectRepositoryPath: string,
+  releaseName: string,
+) {
+  // TODO: What if the index was dirty before this script was run? Or what if
+  // you're in the middle of a rebase? Might want to check that up front before
+  // changes are even made.
+  // TODO: What if this branch already exists? Append the build number?
+  await getStdoutFromGitCommandWithin(projectRepositoryPath, [
+    'checkout',
+    '-b',
+    `release/${releaseName}`,
+  ]);
+  await getStdoutFromGitCommandWithin(projectRepositoryPath, ['add', '-A']);
+  await getStdoutFromGitCommandWithin(projectRepositoryPath, [
+    'commit',
+    '-m',
+    `Release ${releaseName}`,
+  ]);
+}

src/initialization-utils.test.ts

@@ -3,14 +3,24 @@ import path from 'path';
 import { when } from 'jest-when';
 import { buildMockProject, buildMockPackage } from '../tests/unit/helpers';
 import { initialize } from './initialization-utils';
+import * as envUtils from './env-utils';
 import * as inputsUtils from './inputs-utils';
 import * as projectUtils from './project-utils';
 
+jest.mock('./env-utils');
 jest.mock('./inputs-utils');
 jest.mock('./project-utils');
 
 describe('initialize', () => {
-  it('returns an object that contains data necessary to run the workflow', async () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('returns an object derived from command-line arguments and environment variables that contains data necessary to run the workflow', async () => {
     const project = buildMockProject();
     when(jest.spyOn(inputsUtils, 'readInputs'))
       .calledWith(['arg1', 'arg2'])
@@ -19,20 +29,47 @@ describe('initialize', () => {
         tempDirectory: '/path/to/temp',
         reset: true,
       });
+    jest
+      .spyOn(envUtils, 'getEnvironmentVariables')
+      .mockReturnValue({ TODAY: '2022-06-22', EDITOR: undefined });
     when(jest.spyOn(projectUtils, 'readProject'))
       .calledWith('/path/to/project')
       .mockResolvedValue(project);
 
-    const config = await initialize(['arg1', 'arg2'], '/path/to/somewhere');
+    const config = await initialize(['arg1', 'arg2'], '/path/to/cwd');
 
     expect(config).toStrictEqual({
       project,
       tempDirectoryPath: '/path/to/temp',
       reset: true,
+      today: new Date('2022-06-22'),
     });
   });
 
-  it('uses a default temporary directory based on the name of the package if no such directory was passed as an input', async () => {
+  it('resolves the project directory relative to the current working directory', async () => {
+    const project = buildMockProject({
+      rootPackage: buildMockPackage('@foo/bar'),
+    });
+    when(jest.spyOn(inputsUtils, 'readInputs'))
+      .calledWith(['arg1', 'arg2'])
+      .mockResolvedValue({
+        projectDirectory: 'project',
+        tempDirectory: undefined,
+        reset: true,
+      });
+    jest
+      .spyOn(envUtils, 'getEnvironmentVariables')
+      .mockReturnValue({ TODAY: undefined, EDITOR: undefined });
+    const readProjectSpy = jest
+      .spyOn(projectUtils, 'readProject')
+      .mockResolvedValue(project);
+
+    await initialize(['arg1', 'arg2'], '/path/to/cwd');
+
+    expect(readProjectSpy).toHaveBeenCalledWith('/path/to/cwd/project');
+  });
+
+  it('uses a default temporary directory based on the name of the package', async () => {
     const project = buildMockProject({
       rootPackage: buildMockPackage('@foo/bar'),
     });
@@ -43,20 +80,63 @@ describe('initialize', () => {
         tempDirectory: undefined,
         reset: true,
       });
+    jest
+      .spyOn(envUtils, 'getEnvironmentVariables')
+      .mockReturnValue({ TODAY: undefined, EDITOR: undefined });
     when(jest.spyOn(projectUtils, 'readProject'))
       .calledWith('/path/to/project')
       .mockResolvedValue(project);
 
-    const config = await initialize(['arg1', 'arg2'], '/path/to/somewhere');
+    const config = await initialize(['arg1', 'arg2'], '/path/to/cwd');
 
-    expect(config).toStrictEqual({
-      project,
-      tempDirectoryPath: path.join(
-        os.tmpdir(),
-        'create-release-branch',
-        '@foo__bar',
-      ),
-      reset: true,
-    });
+    expect(config.tempDirectoryPath).toStrictEqual(
+      path.join(os.tmpdir(), 'create-release-branch', '@foo__bar'),
+    );
+  });
+
+  it('uses the current date if TODAY is undefined', async () => {
+    const project = buildMockProject();
+    const today = new Date('2022-01-01');
+    when(jest.spyOn(inputsUtils, 'readInputs'))
+      .calledWith(['arg1', 'arg2'])
+      .mockResolvedValue({
+        projectDirectory: '/path/to/project',
+        tempDirectory: undefined,
+        reset: true,
+      });
+    jest
+      .spyOn(envUtils, 'getEnvironmentVariables')
+      .mockReturnValue({ TODAY: undefined, EDITOR: undefined });
+    when(jest.spyOn(projectUtils, 'readProject'))
+      .calledWith('/path/to/project')
+      .mockResolvedValue(project);
+    jest.setSystemTime(today);
+
+    const config = await initialize(['arg1', 'arg2'], '/path/to/cwd');
+
+    expect(config.today).toStrictEqual(today);
+  });
+
+  it('uses the current date if TODAY is not a parsable date', async () => {
+    const project = buildMockProject();
+    const today = new Date('2022-01-01');
+    when(jest.spyOn(inputsUtils, 'readInputs'))
+      .calledWith(['arg1', 'arg2'])
+      .mockResolvedValue({
+        projectDirectory: '/path/to/project',
+        tempDirectory: undefined,
+        reset: true,
+      });
+    jest
+      .spyOn(envUtils, 'getEnvironmentVariables')
+      .mockReturnValue({ TODAY: 'asdfgdasf', EDITOR: undefined });
+    when(jest.spyOn(projectUtils, 'readProject'))
+      .calledWith('/path/to/project')
+      .mockResolvedValue(project);
+    jest.setSystemTime(today);
+
+    const config = await initialize(['arg1', 'arg2'], '/path/to/cwd');
+
+    expect(config.today).toStrictEqual(today);
   });
 });

src/initialization-utils.ts

@@ -1,5 +1,6 @@
 import os from 'os';
 import path from 'path';
+import { getEnvironmentVariables } from './env-utils';
 import { readProject, Project } from './project-utils';
 import { readInputs } from './inputs-utils';
 
@@ -14,8 +15,15 @@ import { readInputs } from './inputs-utils';
 export async function initialize(
   argv: string[],
   cwd: string,
-): Promise<{ project: Project; tempDirectoryPath: string; reset: boolean }> {
+): Promise<{
+  project: Project;
+  tempDirectoryPath: string;
+  reset: boolean;
+  today: Date;
+}> {
   const inputs = await readInputs(argv);
+  const { TODAY } = getEnvironmentVariables();
+
   const projectDirectoryPath = path.resolve(cwd, inputs.projectDirectory);
   const project = await readProject(projectDirectoryPath);
   const tempDirectoryPath =
@@ -26,6 +34,11 @@ export async function initialize(
           project.rootPackage.validatedManifest.name.replace('/', '__'),
         )
       : path.resolve(cwd, inputs.tempDirectory);
+  const parsedTodayTimestamp =
+    TODAY === undefined ? NaN : new Date(TODAY).getTime();
+  const today = isNaN(parsedTodayTimestamp)
+    ? new Date()
+    : new Date(parsedTodayTimestamp);
 
-  return { project, tempDirectoryPath, reset: inputs.reset };
+  return { project, tempDirectoryPath, reset: inputs.reset, today };
 }

src/main.test.ts

@@ -10,12 +10,14 @@ jest.mock('./monorepo-workflow-utils');
 describe('main', () => {
   it('executes the monorepo workflow if the project is a monorepo', async () => {
     const project = buildMockProject({ isMonorepo: true });
+    const today = new Date();
     const stdout = fs.createWriteStream('/dev/null');
     const stderr = fs.createWriteStream('/dev/null');
     jest.spyOn(initializationUtils, 'initialize').mockResolvedValue({
       project,
       tempDirectoryPath: '/path/to/temp/directory',
       reset: false,
+      today,
     });
     const followMonorepoWorkflowSpy = jest
       .spyOn(monorepoWorkflowUtils, 'followMonorepoWorkflow')
@@ -32,19 +34,22 @@ describe('main', () => {
       project,
       tempDirectoryPath: '/path/to/temp/directory',
       firstRemovingExistingReleaseSpecification: false,
+      today,
       stdout,
       stderr,
     });
   });
 
   it('executes the polyrepo workflow if the project is within a polyrepo', async () => {
     const project = buildMockProject({ isMonorepo: false });
+    const today = new Date();
     const stdout = fs.createWriteStream('/dev/null');
     const stderr = fs.createWriteStream('/dev/null');
     jest.spyOn(initializationUtils, 'initialize').mockResolvedValue({
       project,
       tempDirectoryPath: '/path/to/temp/directory',
       reset: false,
+      today,
     });
     const followMonorepoWorkflowSpy = jest
       .spyOn(monorepoWorkflowUtils, 'followMonorepoWorkflow')

src/main.ts

@@ -23,7 +23,10 @@ export async function main({
   stdout: Pick<WriteStream, 'write'>;
   stderr: Pick<WriteStream, 'write'>;
 }) {
-  const { project, tempDirectoryPath, reset } = await initialize(argv, cwd);
+  const { project, tempDirectoryPath, reset, today } = await initialize(
+    argv,
+    cwd,
+  );
 
   if (project.isMonorepo) {
     stdout.write(
@@ -33,6 +36,7 @@ export async function main({
       project,
       tempDirectoryPath,
       firstRemovingExistingReleaseSpecification: reset,
+      today,
       stdout,
       stderr,
     });