From 0adc8b7e13011956929fc945e083f75edec16698 Mon Sep 17 00:00:00 2001 From: Adam Ruka Date: Thu, 4 Nov 2021 19:33:59 -0700 Subject: [PATCH] feat(cli): introduce the 'watch' command (#17240) This PR introduces the "watch" command, in two variants: as a separate new `cdk watch` command, and as an argument to the existing `cdk deploy` command. The "watch" process will observe the project files, defined by the new `"include"` and `"exclude"` settings in `cdk.json` (see https://github.com/aws/aws-cdk-rfcs/pull/383 for details), and will trigger a `cdk deploy` when it detects any changes. The deployment will by default use the new "hotswap" deployments for maximum speed. Since `cdk deploy` is a relatively slow process for a "watch" command, there is some logic to perform intelligent queuing of any file events that happen while `cdk deploy` is running. We will batch all of those events, and trigger a single `cdk deploy` after the current one finishes. This ensures only a single `cdk deploy` command ever executes at a time. The observing of the files, and reacting to their changes, is accomplished using the [`chokidar` library](https://www.npmjs.com/package/chokidar). ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* --- packages/aws-cdk/README.md | 63 ++++++ packages/aws-cdk/bin/cdk.ts | 59 +++++ .../lib/api/cloudformation-deployments.ts | 2 +- .../aws-cdk/lib/api/cxapp/cloud-executable.ts | 10 +- packages/aws-cdk/lib/api/deploy-stack.ts | 2 +- packages/aws-cdk/lib/cdk-toolkit.ts | 214 ++++++++++++++---- packages/aws-cdk/package.json | 1 + packages/aws-cdk/test/cdk-toolkit.test.ts | 190 ++++++++++++++++ yarn.lock | 48 +++- 9 files changed, 535 insertions(+), 54 deletions(-) diff --git a/packages/aws-cdk/README.md b/packages/aws-cdk/README.md index 0a2270b08fc90..1bd9e491e34e4 100644 --- a/packages/aws-cdk/README.md +++ b/packages/aws-cdk/README.md @@ -372,6 +372,69 @@ For this reason, only use it for development purposes. **⚠ Note #2**: This command is considered experimental, and might have breaking changes in the future. +### `cdk watch` + +The `watch` command is similar to `deploy`, +but instead of being a one-shot operation, +the command continuously monitors the files of the project, +and triggers a deployment whenever it detects any changes: + +```console +$ cdk watch DevelopmentStack +Detected change to 'lambda-code/index.js' (type: change). Triggering 'cdk deploy' +DevelopmentStack: deploying... + + ✅ DevelopmentStack + +^C +``` + +To end a `cdk watch` session, interrupt the process by pressing Ctrl+C. + +What files are observed is determined by the `"watch"` setting in your `cdk.json` file. +It has two sub-keys, `"include"` and `"exclude"`, each of which can be either a single string, or an array of strings. +Each entry is interpreted as a path relative to the location of the `cdk.json` file. +Globs, both `*` and `**`, are allowed to be used. +Example: + +```json +{ + "app": "mvn -e -q compile exec:java", + "watch": { + "include": "src/main/**", + "exclude": "target/*" + } +} +``` + +The default for `"include"` is `"**/*"` +(which means all files and directories in the root of the project), +and `"exclude"` is optional +(note that we always ignore files and directories starting with `.`, +the CDK output directory, and the `node_modules` directory), +so the minimal settings to enable `watch` are `"watch": {}`. + +If either your CDK code, or application code, needs a build step before being deployed, +`watch` works with the `"build"` key in the `cdk.json` file, +for example: + +```json +{ + "app": "mvn -e -q exec:java", + "build": "mvn package", + "watch": { + "include": "src/main/**", + "exclude": "target/*" + } +} +``` + +Note that `watch` by default uses hotswap deployments (see above for details) -- +to turn them off, pass the `--no-hotswap` option when invoking it. + +**Note**: This command is considered experimental, +and might have breaking changes in the future. + ### `cdk destroy` Deletes a stack from it's environment. This will cause the resources in the stack to be destroyed (unless they were diff --git a/packages/aws-cdk/bin/cdk.ts b/packages/aws-cdk/bin/cdk.ts index b5b60f895c8ca..a938b00f3c02f 100644 --- a/packages/aws-cdk/bin/cdk.ts +++ b/packages/aws-cdk/bin/cdk.ts @@ -118,6 +118,45 @@ async function parseCommandLineArguments() { 'which skips CloudFormation and updates the resources directly, ' + 'and falls back to a full deployment if that is not possible. ' + 'Do not use this in production environments', + }) + .option('watch', { + type: 'boolean', + desc: 'Continuously observe the project files, ' + + 'and deploy the given stack(s) automatically when changes are detected. ' + + 'Implies --hotswap by default', + }), + ) + .command('watch [STACKS..]', "Shortcut for 'deploy --watch'", yargs => yargs + // I'm fairly certain none of these options, present for 'deploy', make sense for 'watch': + // .option('all', { type: 'boolean', default: false, desc: 'Deploy all available stacks' }) + // .option('ci', { type: 'boolean', desc: 'Force CI detection', default: process.env.CI !== undefined }) + // @deprecated(v2) -- tags are part of the Cloud Assembly and tags specified here will be overwritten on the next deployment + // .option('tags', { type: 'array', alias: 't', desc: 'Tags to add to the stack (KEY=VALUE), overrides tags from Cloud Assembly (deprecated)', nargs: 1, requiresArg: true }) + // .option('execute', { type: 'boolean', desc: 'Whether to execute ChangeSet (--no-execute will NOT execute the ChangeSet)', default: true }) + // These options, however, are more subtle - I could be convinced some of these should also be available for 'watch': + // .option('require-approval', { type: 'string', choices: [RequireApproval.Never, RequireApproval.AnyChange, RequireApproval.Broadening], desc: 'What security-sensitive changes need manual approval' }) + // .option('parameters', { type: 'array', desc: 'Additional parameters passed to CloudFormation at deploy time (STACK:KEY=VALUE)', nargs: 1, requiresArg: true, default: {} }) + // .option('previous-parameters', { type: 'boolean', default: true, desc: 'Use previous values for existing parameters (you must specify all parameters on every deployment if this is disabled)' }) + // .option('outputs-file', { type: 'string', alias: 'O', desc: 'Path to file where stack outputs will be written as JSON', requiresArg: true }) + // .option('notification-arns', { type: 'array', desc: 'ARNs of SNS topics that CloudFormation will notify with stack related events', nargs: 1, requiresArg: true }) + .option('build-exclude', { type: 'array', alias: 'E', nargs: 1, desc: 'Do not rebuild asset with the given ID. Can be specified multiple times', default: [] }) + .option('exclusively', { type: 'boolean', alias: 'e', desc: 'Only deploy requested stacks, don\'t include dependencies' }) + .option('change-set-name', { type: 'string', desc: 'Name of the CloudFormation change set to create' }) + .option('force', { alias: 'f', type: 'boolean', desc: 'Always deploy stack even if templates are identical', default: false }) + .option('progress', { type: 'string', choices: [StackActivityProgress.BAR, StackActivityProgress.EVENTS], desc: 'Display mode for stack activity events' }) + .option('rollback', { + type: 'boolean', + desc: "Rollback stack to stable state on failure. Defaults to 'true', iterate more rapidly with --no-rollback or -R. " + + 'Note: do **not** disable this flag for deployments with resource replacements, as that will always fail', + }) + // same hack for -R as above in 'deploy' + .option('R', { type: 'boolean', hidden: true }).middleware(yargsNegativeAlias('R', 'rollback'), true) + .option('hotswap', { + type: 'boolean', + desc: "Attempts to perform a 'hotswap' deployment, " + + 'which skips CloudFormation and updates the resources directly, ' + + 'and falls back to a full deployment if that is not possible. ' + + "'true' by default, use --no-hotswap to turn off", }), ) .command('destroy [STACKS..]', 'Destroy the stack(s) named STACKS', yargs => yargs @@ -335,6 +374,26 @@ async function initCommandLine() { ci: args.ci, rollback: configuration.settings.get(['rollback']), hotswap: args.hotswap, + watch: args.watch, + }); + + case 'watch': + return cli.watch({ + selector, + // parameters: parameterMap, + // usePreviousParameters: args['previous-parameters'], + // outputsFile: configuration.settings.get(['outputsFile']), + // requireApproval: configuration.settings.get(['requireApproval']), + // notificationArns: args.notificationArns, + exclusively: args.exclusively, + toolkitStackName, + roleArn: args.roleArn, + reuseAssets: args['build-exclude'], + changeSetName: args.changeSetName, + force: args.force, + progress: configuration.settings.get(['progress']), + rollback: configuration.settings.get(['rollback']), + hotswap: args.hotswap, }); case 'destroy': diff --git a/packages/aws-cdk/lib/api/cloudformation-deployments.ts b/packages/aws-cdk/lib/api/cloudformation-deployments.ts index 914efd51cd574..da8db43ae8005 100644 --- a/packages/aws-cdk/lib/api/cloudformation-deployments.ts +++ b/packages/aws-cdk/lib/api/cloudformation-deployments.ts @@ -142,7 +142,7 @@ export interface DeployStackOptions { * A 'hotswap' deployment will attempt to short-circuit CloudFormation * and update the affected resources like Lambda functions directly. * - * @default - false (do not perform a 'hotswap' deployment) + * @default - false for regular deployments, true for 'watch' deployments */ readonly hotswap?: boolean; } diff --git a/packages/aws-cdk/lib/api/cxapp/cloud-executable.ts b/packages/aws-cdk/lib/api/cxapp/cloud-executable.ts index eeebec8e90f44..9bbb607de44fb 100644 --- a/packages/aws-cdk/lib/api/cxapp/cloud-executable.ts +++ b/packages/aws-cdk/lib/api/cxapp/cloud-executable.ts @@ -46,10 +46,14 @@ export class CloudExecutable { } /** - * Synthesize a set of stacks + * Synthesize a set of stacks. + * + * @param cacheCloudAssembly whether to cache the Cloud Assembly after it has been first synthesized. + * This is 'true' by default, and only set to 'false' for 'cdk watch', + * which needs to re-synthesize the Assembly each time it detects a change to the project files */ - public async synthesize(): Promise { - if (!this._cloudAssembly) { + public async synthesize(cacheCloudAssembly: boolean = true): Promise { + if (!this._cloudAssembly || !cacheCloudAssembly) { this._cloudAssembly = await this.doSynthesize(); } return this._cloudAssembly; diff --git a/packages/aws-cdk/lib/api/deploy-stack.ts b/packages/aws-cdk/lib/api/deploy-stack.ts index 2d35a3a01aea0..f73eebed57f54 100644 --- a/packages/aws-cdk/lib/api/deploy-stack.ts +++ b/packages/aws-cdk/lib/api/deploy-stack.ts @@ -179,7 +179,7 @@ export interface DeployStackOptions { * A 'hotswap' deployment will attempt to short-circuit CloudFormation * and update the affected resources like Lambda functions directly. * - * @default - false (do not perform a 'hotswap' deployment) + * @default - false for regular deployments, true for 'watch' deployments */ readonly hotswap?: boolean; } diff --git a/packages/aws-cdk/lib/cdk-toolkit.ts b/packages/aws-cdk/lib/cdk-toolkit.ts index cd5e591dce866..95da6dd39e139 100644 --- a/packages/aws-cdk/lib/cdk-toolkit.ts +++ b/packages/aws-cdk/lib/cdk-toolkit.ts @@ -1,6 +1,7 @@ import * as path from 'path'; import { format } from 'util'; import * as cxapi from '@aws-cdk/cx-api'; +import * as chokidar from 'chokidar'; import * as colors from 'colors/safe'; import * as fs from 'fs-extra'; import * as promptly from 'promptly'; @@ -12,9 +13,9 @@ import { CloudAssembly, DefaultSelection, ExtendedStackSelection, StackCollectio import { CloudExecutable } from './api/cxapp/cloud-executable'; import { StackActivityProgress } from './api/util/cloudformation/stack-activity-monitor'; import { printSecurityDiff, printStackDiff, RequireApproval } from './diff'; -import { data, error, highlight, print, success, warning } from './logging'; +import { data, debug, error, highlight, print, success, warning } from './logging'; import { deserializeStructure } from './serialize'; -import { Configuration } from './settings'; +import { Configuration, PROJECT_CONFIG } from './settings'; import { numberFromBool, partition } from './util'; export interface CdkToolkitProps { @@ -112,7 +113,11 @@ export class CdkToolkit { } public async deploy(options: DeployOptions) { - const stacks = await this.selectStacksForDeploy(options.selector, options.exclusively); + if (options.watch) { + return this.watch(options); + } + + const stacks = await this.selectStacksForDeploy(options.selector, options.exclusively, options.cacheCloudAssembly); const requireApproval = options.requireApproval ?? RequireApproval.Broadening; @@ -243,6 +248,85 @@ export class CdkToolkit { } } + public async watch(options: WatchOptions) { + const rootDir = path.dirname(path.resolve(PROJECT_CONFIG)); + debug("root directory used for 'watch' is: %s", rootDir); + + const watchSettings: { include?: string | string[], exclude: string | string [] } | undefined = + this.props.configuration.settings.get(['watch']); + if (!watchSettings) { + throw new Error("Cannot use the 'watch' command without specifying at least one directory to monitor. " + + 'Make sure to add a "watch" key to your cdk.json'); + } + + // For the "include" subkey under the "watch" key, the behavior is: + // 1. No "watch" setting? We error out. + // 2. "watch" setting without an "include" key? We default to observing "./**". + // 3. "watch" setting with an empty "include" key? We default to observing "./**". + // 4. Non-empty "include" key? Just use the "include" key. + const watchIncludes = this.patternsArrayForWatch(watchSettings.include, { rootDir, returnRootDirIfEmpty: true }); + debug("'include' patterns for 'watch': %s", watchIncludes); + + // For the "exclude" subkey under the "watch" key, + // the behavior is to add some default excludes in addition to the ones specified by the user: + // 1. The CDK output directory. + // 2. Any file whose name starts with a dot. + // 3. Any directory's content whose name starts with a dot. + // 4. Any node_modules and its content (even if it's not a JS/TS project, you might be using a local aws-cli package) + const outputDir = this.props.configuration.settings.get(['output']); + const watchExcludes = this.patternsArrayForWatch(watchSettings.exclude, { rootDir, returnRootDirIfEmpty: false }).concat( + `${outputDir}/**`, + '**/.*', + '**/.*/**', + '**/node_modules/**', + ); + debug("'exclude' patterns for 'watch': %s", watchExcludes); + + // Since 'cdk deploy' is a relatively slow operation for a 'watch' process, + // introduce a concurrency latch that tracks the state. + // This way, if file change events arrive when a 'cdk deploy' is still executing, + // we will batch them, and trigger another 'cdk deploy' after the current one finishes, + // making sure 'cdk deploy's always execute one at a time. + // Here's a diagram showing the state transitions: + // -------------- -------- file changed -------------- file changed -------------- file changed + // | | ready event | | ------------------> | | ------------------> | | --------------| + // | pre-ready | -------------> | open | | deploying | | queued | | + // | | | | <------------------ | | <------------------ | | <-------------| + // -------------- -------- 'cdk deploy' done -------------- 'cdk deploy' done -------------- + let latch: 'pre-ready' | 'open' | 'deploying' | 'queued' = 'pre-ready'; + chokidar.watch(watchIncludes, { + ignored: watchExcludes, + cwd: rootDir, + // ignoreInitial: true, + }).on('ready', () => { + latch = 'open'; + debug("'watch' received the 'ready' event. From now on, all file changes will trigger a deployment"); + }).on('all', async (event, filePath) => { + if (latch === 'pre-ready') { + print(`'watch' is observing ${event === 'addDir' ? 'directory' : 'the file'} '%s' for changes`, filePath); + } else if (latch === 'open') { + latch = 'deploying'; + print("Detected change to '%s' (type: %s). Triggering 'cdk deploy'", filePath, event); + await this.invokeDeployFromWatch(options); + + // If latch is still 'deploying' after the 'await', that's fine, + // but if it's 'queued', that means we need to deploy again + while ((latch as 'deploying' | 'queued') === 'queued') { + // TypeScript doesn't realize latch can change between 'awaits', + // and thinks the above 'while' condition is always 'false' without the cast + latch = 'deploying'; + print("Detected file changes during deployment. Invoking 'cdk deploy' again"); + await this.invokeDeployFromWatch(options); + } + latch = 'open'; + } else { // this means latch is either 'deploying' or 'queued' + latch = 'queued'; + print("Detected change to '%s' (type: %s) while 'cdk deploy' is still running. " + + 'Will queue for another deployment after this one finishes', filePath, event); + } + }); + } + public async destroy(options: DestroyOptions) { let stacks = await this.selectStacksForDestroy(options.selector, options.exclusively); @@ -397,8 +481,8 @@ export class CdkToolkit { return stacks; } - private async selectStacksForDeploy(selector: StackSelector, exclusively?: boolean): Promise { - const assembly = await this.assembly(); + private async selectStacksForDeploy(selector: StackSelector, exclusively?: boolean, cacheCloudAssembly?: boolean): Promise { + const assembly = await this.assembly(cacheCloudAssembly); const stacks = await assembly.selectStacks(selector, { extend: exclusively ? ExtendedStackSelection.None : ExtendedStackSelection.Upstream, defaultBehavior: DefaultSelection.OnlySingle, @@ -480,10 +564,38 @@ export class CdkToolkit { return assembly.stackById(stacks.firstStack.id); } - private assembly(): Promise { - return this.props.cloudExecutable.synthesize(); + private assembly(cacheCloudAssembly?: boolean): Promise { + return this.props.cloudExecutable.synthesize(cacheCloudAssembly); } + private patternsArrayForWatch(patterns: string | string[] | undefined, options: { rootDir: string, returnRootDirIfEmpty: boolean }): string[] { + const patternsArray: string[] = patterns !== undefined + ? (Array.isArray(patterns) ? patterns : [patterns]) + : []; + return patternsArray.length > 0 + ? patternsArray + : (options.returnRootDirIfEmpty ? [options.rootDir] : []); + } + + private async invokeDeployFromWatch(options: WatchOptions): Promise { + // 'watch' has different defaults than regular 'deploy' + const deployOptions: DeployOptions = { + ...options, + requireApproval: RequireApproval.Never, + // if 'watch' is called by invoking 'cdk deploy --watch', + // we need to make sure to not call 'deploy' with 'watch' again, + // as that would lead to a cycle + watch: false, + cacheCloudAssembly: false, + hotswap: options.hotswap === undefined ? true : options.hotswap, + }; + + try { + await this.deploy(deployOptions); + } catch (e) { + // just continue - deploy will show the error + } + } } export interface DiffOptions { @@ -542,7 +654,7 @@ export interface DiffOptions { securityOnly?: boolean; } -export interface DeployOptions { +interface WatchOptions { /** * Criteria for selecting stacks to deploy */ @@ -567,6 +679,49 @@ export interface DeployOptions { */ roleArn?: string; + /** + * Reuse the assets with the given asset IDs + */ + reuseAssets?: string[]; + + /** + * Optional name to use for the CloudFormation change set. + * If not provided, a name will be generated automatically. + */ + changeSetName?: string; + + /** + * Always deploy, even if templates are identical. + * @default false + */ + force?: boolean; + + /** + * Display mode for stack deployment progress. + * + * @default - StackActivityProgress.Bar - stack events will be displayed for + * the resource currently being deployed. + */ + progress?: StackActivityProgress; + + /** + * Rollback failed deployments + * + * @default true + */ + readonly rollback?: boolean; + + /** + * Whether to perform a 'hotswap' deployment. + * A 'hotswap' deployment will attempt to short-circuit CloudFormation + * and update the affected resources like Lambda functions directly. + * + * @default - false for regular deployments, true for 'watch' deployments + */ + readonly hotswap?: boolean; +} + +export interface DeployOptions extends WatchOptions { /** * ARNs of SNS topics that CloudFormation will notify with stack related events */ @@ -579,11 +734,6 @@ export interface DeployOptions { */ requireApproval?: RequireApproval; - /** - * Reuse the assets with the given asset IDs - */ - reuseAssets?: string[]; - /** * Tags to pass to CloudFormation for deployment */ @@ -596,18 +746,6 @@ export interface DeployOptions { */ execute?: boolean; - /** - * Optional name to use for the CloudFormation change set. - * If not provided, a name will be generated automatically. - */ - changeSetName?: string; - - /** - * Always deploy, even if templates are identical. - * @default false - */ - force?: boolean; - /** * Additional parameters for CloudFormation at deploy time * @default {} @@ -623,14 +761,6 @@ export interface DeployOptions { */ usePreviousParameters?: boolean; - /** - * Display mode for stack deployment progress. - * - * @default - StackActivityProgress.Bar - stack events will be displayed for - * the resource currently being deployed. - */ - progress?: StackActivityProgress; - /** * Path to file where stack outputs will be written after a successful deploy as JSON * @default - Outputs are not written to any file @@ -645,20 +775,20 @@ export interface DeployOptions { readonly ci?: boolean; /** - * Rollback failed deployments + * Whether this 'deploy' command should actually delegate to the 'watch' command. * - * @default true + * @default false */ - readonly rollback?: boolean; + readonly watch?: boolean; - /* - * Whether to perform a 'hotswap' deployment. - * A 'hotswap' deployment will attempt to short-circuit CloudFormation - * and update the affected resources like Lambda functions directly. + /** + * Whether we should cache the Cloud Assembly after the first time it has been synthesized. + * The default is 'true', we only don't want to do it in case the deployment is triggered by + * 'cdk watch'. * - * @default - false (do not perform a 'hotswap' deployment) + * @default true */ - readonly hotswap?: boolean; + readonly cacheCloudAssembly?: boolean; } export interface DestroyOptions { diff --git a/packages/aws-cdk/package.json b/packages/aws-cdk/package.json index c71dddbf206f4..40fa126a94cb4 100644 --- a/packages/aws-cdk/package.json +++ b/packages/aws-cdk/package.json @@ -76,6 +76,7 @@ "aws-sdk": "^2.979.0", "camelcase": "^6.2.0", "cdk-assets": "0.0.0", + "chokidar": "^3.5.2", "colors": "^1.4.0", "decamelize": "^5.0.1", "fs-extra": "^9.1.0", diff --git a/packages/aws-cdk/test/cdk-toolkit.test.ts b/packages/aws-cdk/test/cdk-toolkit.test.ts index 19276b15b7b7b..e8445da68a6b6 100644 --- a/packages/aws-cdk/test/cdk-toolkit.test.ts +++ b/packages/aws-cdk/test/cdk-toolkit.test.ts @@ -1,3 +1,52 @@ +// We need to mock the chokidar library, used by 'cdk watch' +const mockChokidarWatcherOn = jest.fn(); +const fakeChokidarWatcher = { + on: mockChokidarWatcherOn, +}; +const fakeChokidarWatcherOn = { + get readyCallback(): () => void { + expect(mockChokidarWatcherOn.mock.calls.length).toBeGreaterThanOrEqual(1); + // The call to the first 'watcher.on()' in the production code is the one we actually want here. + // This is a pretty fragile, but at least with this helper class, + // we would have to change it only in one place if it ever breaks + const firstCall = mockChokidarWatcherOn.mock.calls[0]; + // let's make sure the first argument is the 'ready' event, + // just to be double safe + expect(firstCall[0]).toBe('ready'); + // the second argument is the callback + return firstCall[1]; + }, + + get fileEventCallback(): (event: 'add' | 'addDir' | 'change' | 'unlink' | 'unlinkDir', path: string) => Promise { + expect(mockChokidarWatcherOn.mock.calls.length).toBeGreaterThanOrEqual(2); + const secondCall = mockChokidarWatcherOn.mock.calls[1]; + // let's make sure the first argument is not the 'ready' event, + // just to be double safe + expect(secondCall[0]).not.toBe('ready'); + // the second argument is the callback + return secondCall[1]; + }, +}; + +const mockChokidarWatch = jest.fn(); +jest.mock('chokidar', () => ({ + watch: mockChokidarWatch, +})); +const fakeChokidarWatch = { + get includeArgs(): string[] { + expect(mockChokidarWatch.mock.calls.length).toBe(1); + // the include args are the first parameter to the 'watch()' call + return mockChokidarWatch.mock.calls[0][0]; + }, + + get excludeArgs(): string[] { + expect(mockChokidarWatch.mock.calls.length).toBe(1); + // the ignore args are a property of the second parameter to the 'watch()' call + const chokidarWatchOpts = mockChokidarWatch.mock.calls[0][1]; + return chokidarWatchOpts.ignored; + }, +}; + import * as cxschema from '@aws-cdk/cloud-assembly-schema'; import * as cxapi from '@aws-cdk/cx-api'; import { Bootstrapper } from '../lib/api/bootstrap'; @@ -11,6 +60,12 @@ import { instanceMockFrom, MockCloudExecutable, TestStackArtifact } from './util let cloudExecutable: MockCloudExecutable; let bootstrapper: jest.Mocked; beforeEach(() => { + jest.resetAllMocks(); + + mockChokidarWatch.mockReturnValue(fakeChokidarWatcher); + // on() in chokidar's Watcher returns 'this' + mockChokidarWatcherOn.mockReturnValue(fakeChokidarWatcher); + bootstrapper = instanceMockFrom(Bootstrapper); bootstrapper.bootstrapEnvironment.mockResolvedValue({ noOp: false, outputs: {} } as any); @@ -191,6 +246,141 @@ describe('deploy', () => { }); }); +describe('watch', () => { + test("fails when no 'watch' settings are found", async () => { + const toolkit = defaultToolkitSetup(); + + await expect(() => { + return toolkit.watch({ selector: { patterns: [] } }); + }).rejects.toThrow("Cannot use the 'watch' command without specifying at least one directory to monitor. " + + 'Make sure to add a "watch" key to your cdk.json'); + }); + + test('observes only the root directory by default', async () => { + cloudExecutable.configuration.settings.set(['watch'], {}); + const toolkit = defaultToolkitSetup(); + + await toolkit.watch({ selector: { patterns: [] } }); + + const includeArgs = fakeChokidarWatch.includeArgs; + expect(includeArgs.length).toBe(1); + }); + + test("allows providing a single string in 'watch.include'", async () => { + cloudExecutable.configuration.settings.set(['watch'], { + include: 'my-dir', + }); + const toolkit = defaultToolkitSetup(); + + await toolkit.watch({ selector: { patterns: [] } }); + + expect(fakeChokidarWatch.includeArgs).toStrictEqual(['my-dir']); + }); + + test("allows providing an array of strings in 'watch.include'", async () => { + cloudExecutable.configuration.settings.set(['watch'], { + include: ['my-dir1', '**/my-dir2/*'], + }); + const toolkit = defaultToolkitSetup(); + + await toolkit.watch({ selector: { patterns: [] } }); + + expect(fakeChokidarWatch.includeArgs).toStrictEqual(['my-dir1', '**/my-dir2/*']); + }); + + test('ignores the output dir, dot files, dot directories, and node_modules by default', async () => { + cloudExecutable.configuration.settings.set(['watch'], {}); + cloudExecutable.configuration.settings.set(['output'], 'cdk.out'); + const toolkit = defaultToolkitSetup(); + + await toolkit.watch({ selector: { patterns: [] } }); + + expect(fakeChokidarWatch.excludeArgs).toStrictEqual([ + 'cdk.out/**', + '**/.*', + '**/.*/**', + '**/node_modules/**', + ]); + }); + + test("allows providing a single string in 'watch.exclude'", async () => { + cloudExecutable.configuration.settings.set(['watch'], { + exclude: 'my-dir', + }); + const toolkit = defaultToolkitSetup(); + + await toolkit.watch({ selector: { patterns: [] } }); + + const excludeArgs = fakeChokidarWatch.excludeArgs; + expect(excludeArgs.length).toBe(5); + expect(excludeArgs[0]).toBe('my-dir'); + }); + + test("allows providing an array of strings in 'watch.exclude'", async () => { + cloudExecutable.configuration.settings.set(['watch'], { + exclude: ['my-dir1', '**/my-dir2'], + }); + const toolkit = defaultToolkitSetup(); + + await toolkit.watch({ selector: { patterns: [] } }); + + const excludeArgs = fakeChokidarWatch.excludeArgs; + expect(excludeArgs.length).toBe(6); + expect(excludeArgs[0]).toBe('my-dir1'); + expect(excludeArgs[1]).toBe('**/my-dir2'); + }); + + describe('with file change events', () => { + let toolkit: CdkToolkit; + let cdkDeployMock: jest.Mock; + + beforeEach(async () => { + cloudExecutable.configuration.settings.set(['watch'], {}); + toolkit = defaultToolkitSetup(); + cdkDeployMock = jest.fn(); + toolkit.deploy = cdkDeployMock; + await toolkit.watch({ selector: { patterns: [] } }); + }); + + test("does not trigger a 'deploy' before the 'ready' event has fired", async () => { + await fakeChokidarWatcherOn.fileEventCallback('add', 'my-file'); + + expect(cdkDeployMock).not.toHaveBeenCalled(); + }); + + describe("when the 'ready' event has already fired", () => { + beforeEach(() => { + fakeChokidarWatcherOn.readyCallback(); + }); + + test("does trigger a 'deploy' for a file change", async () => { + await fakeChokidarWatcherOn.fileEventCallback('add', 'my-file'); + + expect(cdkDeployMock).toHaveBeenCalled(); + }); + + test("triggers a 'deploy' twice for two file changes", async () => { + await Promise.all([ + fakeChokidarWatcherOn.fileEventCallback('add', 'my-file1'), + fakeChokidarWatcherOn.fileEventCallback('change', 'my-file2'), + ]); + + expect(cdkDeployMock).toHaveBeenCalledTimes(2); + }); + + test("batches file changes that happen during 'deploy'", async () => { + await Promise.all([ + fakeChokidarWatcherOn.fileEventCallback('add', 'my-file1'), + fakeChokidarWatcherOn.fileEventCallback('change', 'my-file2'), + fakeChokidarWatcherOn.fileEventCallback('unlink', 'my-file3'), + ]); + + expect(cdkDeployMock).toHaveBeenCalledTimes(2); + }); + }); + }); +}); + describe('synth', () => { test('with no stdout option', async () => { // GIVE diff --git a/yarn.lock b/yarn.lock index 026281159396d..b98b3ecdb6050 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2287,7 +2287,7 @@ anymatch@^2.0.0: micromatch "^3.1.4" normalize-path "^2.1.1" -anymatch@^3.0.3: +anymatch@^3.0.3, anymatch@~3.1.2: version "3.1.2" resolved "https://registry.npmjs.org/anymatch/-/anymatch-3.1.2.tgz#c0557c096af32f106198f4f4e2a383537e378716" integrity sha512-P43ePfOAIupkguHUycrc4qJ9kz8ZiuOUijaETwX7THt0Y/GNK7v0aa8rY816xWjZ7rJdA5XdMcpVFTKMq+RvWg== @@ -2674,6 +2674,11 @@ before-after-hook@^2.0.0, before-after-hook@^2.2.0: resolved "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.2.tgz#a6e8ca41028d90ee2c24222f201c90956091613e" integrity sha512-3pZEU3NT5BFUo/AD5ERPWOgQOCZITni6iavr5AUw5AUwQjMlI0kzu5btnyD39AF0gUEsDPwJT+oY1ORBJijPjQ== +binary-extensions@^2.0.0: + version "2.2.0" + resolved "https://registry.yarnpkg.com/binary-extensions/-/binary-extensions-2.2.0.tgz#75f502eeaf9ffde42fc98829645be4ea76bd9e2d" + integrity sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA== + bl@^4.0.3: version "4.1.0" resolved "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz#451535264182bec2fbbc83a62ab98cf11d9f7b3a" @@ -2712,7 +2717,7 @@ braces@^2.3.1: split-string "^3.0.2" to-regex "^3.0.1" -braces@^3.0.1: +braces@^3.0.1, braces@~3.0.2: version "3.0.2" resolved "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz#3454e1a462ee8d599e236df336cd9ea4f8afe107" integrity sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A== @@ -2960,6 +2965,21 @@ charenc@0.0.2: resolved "https://registry.npmjs.org/charenc/-/charenc-0.0.2.tgz#c0a1d2f3a7092e03774bfa83f14c0fc5790a8667" integrity sha1-wKHS86cJLgN3S/qD8UwPxXkKhmc= +chokidar@^3.5.2: + version "3.5.2" + resolved "https://registry.yarnpkg.com/chokidar/-/chokidar-3.5.2.tgz#dba3976fcadb016f66fd365021d91600d01c1e75" + integrity sha512-ekGhOnNVPgT77r4K/U3GDhu+FQ2S8TnK/s2KbIGXi0SZWuwkZ2QNyfWdZW+TVfn84DpEP7rLeCt2UI6bJ8GwbQ== + dependencies: + anymatch "~3.1.2" + braces "~3.0.2" + glob-parent "~5.1.2" + is-binary-path "~2.1.0" + is-glob "~4.0.1" + normalize-path "~3.0.0" + readdirp "~3.6.0" + optionalDependencies: + fsevents "~2.3.2" + chownr@^1.1.4: version "1.1.4" resolved "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz#6fc9d7b42d32a583596337666e7d08084da2cc6b" @@ -4801,7 +4821,7 @@ fs.realpath@^1.0.0: resolved "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz#1504ad2523158caa40db4a2787cb01411994ea4f" integrity sha1-FQStJSMVjKpA20onh8sBQRmU6k8= -fsevents@^2.1.2, fsevents@^2.3.2: +fsevents@^2.1.2, fsevents@^2.3.2, fsevents@~2.3.2: version "2.3.2" resolved "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz#8a526f78b8fdf4623b709e0b975c52c24c02fd1a" integrity sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA== @@ -4992,7 +5012,7 @@ github-api@^3.4.0: js-base64 "^2.1.9" utf8 "^2.1.1" -glob-parent@^5.1.1, glob-parent@^5.1.2: +glob-parent@^5.1.1, glob-parent@^5.1.2, glob-parent@~5.1.2: version "5.1.2" resolved "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz#869832c58034fe68a4093c17dc15e8340d8401c4" integrity sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow== @@ -5421,6 +5441,13 @@ is-bigint@^1.0.1: dependencies: has-bigints "^1.0.1" +is-binary-path@~2.1.0: + version "2.1.0" + resolved "https://registry.yarnpkg.com/is-binary-path/-/is-binary-path-2.1.0.tgz#ea1f7f3b80f064236e83470f86c09c254fb45b09" + integrity sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw== + dependencies: + binary-extensions "^2.0.0" + is-boolean-object@^1.1.0: version "1.1.2" resolved "https://registry.npmjs.org/is-boolean-object/-/is-boolean-object-1.1.2.tgz#5c6dc200246dd9321ae4b885a114bb1f75f63719" @@ -5524,7 +5551,7 @@ is-generator-fn@^2.0.0: resolved "https://registry.npmjs.org/is-generator-fn/-/is-generator-fn-2.1.0.tgz#7d140adc389aaf3011a8f2a2a4cfa6faadffb118" integrity sha512-cTIB4yPYL/Grw0EaSzASzg6bBy9gqCofvWN8okThAYIxKJZC+udlRAmGbM0XLeniEJSs8uEgHPGuHSe1XsOLSQ== -is-glob@^4.0.0, is-glob@^4.0.1, is-glob@^4.0.3: +is-glob@^4.0.0, is-glob@^4.0.1, is-glob@~4.0.1, is-glob@^4.0.3: version "4.0.3" resolved "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz#64f61e42cbbb2eec2071a9dac0b28ba1e65d5084" integrity sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg== @@ -7824,7 +7851,7 @@ normalize-path@^2.1.1: dependencies: remove-trailing-separator "^1.0.1" -normalize-path@^3.0.0: +normalize-path@^3.0.0, normalize-path@~3.0.0: version "3.0.0" resolved "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz#0dcd69ff23a1c9b11fd0978316644a0388216a65" integrity sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA== @@ -8467,7 +8494,7 @@ picocolors@^1.0.0: resolved "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz#cb5bdc74ff3f51892236eaf79d68bc44564ab81c" integrity sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ== -picomatch@^2.0.4, picomatch@^2.2.3: +picomatch@^2.0.4, picomatch@^2.2.1, picomatch@^2.2.3: version "2.3.0" resolved "https://registry.npmjs.org/picomatch/-/picomatch-2.3.0.tgz#f1f061de8f6a4bf022892e2d128234fb98302972" integrity sha512-lY1Q/PiJGC2zOv/z391WOTD+Z02bCgsFfvxoXXf6h7kv9o+WmsmzYqrAwY63sNgOxE4xEdq0WyUnXfKeBrSvYw== @@ -8877,6 +8904,13 @@ readdir-scoped-modules@^1.0.0: graceful-fs "^4.1.2" once "^1.3.0" +readdirp@~3.6.0: + version "3.6.0" + resolved "https://registry.yarnpkg.com/readdirp/-/readdirp-3.6.0.tgz#74a370bd857116e245b29cc97340cd431a02a6c7" + integrity sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA== + dependencies: + picomatch "^2.2.1" + redent@^3.0.0: version "3.0.0" resolved "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz#e557b7998316bb53c9f1f56fa626352c6963059f"