Add examples for fetch:cookiecutter scaffolder action & improve related tests

Signed-off-by: parmar-abhinav <abhinav.parmar@infosys.com>

.changeset/stupid-dots-relate.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend-module-cookiecutter': patch
+---
+
+Add examples for `fetch:cookiecutter` scaffolder action & improve related tests

plugins/scaffolder-backend-module-cookiecutter/package.json

@@ -53,6 +53,7 @@
     "command-exists": "^1.2.9",
     "fs-extra": "^11.2.0",
     "winston": "^3.2.1",
+    "yaml": "^2.0.0",
     "yn": "^4.0.0"
   },
   "devDependencies": {

plugins/scaffolder-backend-module-cookiecutter/src/actions/fetch/cookiecutter.examples.test.ts

@@ -0,0 +1,274 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { UrlReader, ContainerRunner } from '@backstage/backend-common';
+import { ConfigReader } from '@backstage/config';
+import { JsonObject } from '@backstage/types';
+import { ScmIntegrations } from '@backstage/integration';
+import { createMockDirectory } from '@backstage/backend-test-utils';
+import { createFetchCookiecutterAction } from './cookiecutter';
+import { join } from 'path';
+import type { ActionContext } from '@backstage/plugin-scaffolder-node';
+import { createMockActionContext } from '@backstage/plugin-scaffolder-node-test-utils';
+import { examples } from './cookiecutter.examples';
+import yaml from 'yaml';
+
+const executeShellCommand = jest.fn();
+const commandExists = jest.fn();
+const fetchContents = jest.fn();
+
+jest.mock('@backstage/plugin-scaffolder-node', () => ({
+  ...jest.requireActual('@backstage/plugin-scaffolder-node'),
+  fetchContents: (...args: any[]) => fetchContents(...args),
+  executeShellCommand: (...args: any[]) => executeShellCommand(...args),
+}));
+
+jest.mock(
+  'command-exists',
+  () =>
+    (...args: any[]) =>
+      commandExists(...args),
+);
+
+describe('fetch:cookiecutter', () => {
+  const mockDir = createMockDirectory({ mockOsTmpDir: true });
+  const integrations = ScmIntegrations.fromConfig(
+    new ConfigReader({
+      integrations: {
+        azure: [
+          { host: 'dev.azure.com', token: 'tokenlols' },
+          { host: 'myazurehostnotoken.com' },
+        ],
+      },
+    }),
+  );
+
+  const mockTmpDir = mockDir.path;
+
+  let mockContext: ActionContext<{
+    url: string;
+    targetPath?: string;
+    values: JsonObject;
+    copyWithoutRender?: string[];
+    extensions?: string[];
+    imageName?: string;
+  }>;
+
+  const containerRunner: jest.Mocked<ContainerRunner> = {
+    runContainer: jest.fn(),
+  };
+
+  const mockReader: UrlReader = {
+    readUrl: jest.fn(),
+    readTree: jest.fn(),
+    search: jest.fn(),
+  };
+
+  const action = createFetchCookiecutterAction({
+    integrations,
+    containerRunner,
+    reader: mockReader,
+  });
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+
+    mockContext = createMockActionContext({
+      input: {
+        url: 'https://google.com/cookie/cutter',
+        targetPath: 'something',
+        values: {
+          help: 'me',
+        },
+      },
+      templateInfo: {
+        entityRef: 'template:default/cookiecutter',
+        baseUrl: 'somebase',
+      },
+      workspacePath: mockTmpDir,
+    });
+    mockDir.setContent({ template: {} });
+
+    commandExists.mockResolvedValue(null);
+
+    // Mock when run container is called it creates some new files in the mock filesystem
+    containerRunner.runContainer.mockImplementation(async () => {
+      mockDir.setContent({
+        'intermediate/testfile.json': '{}',
+      });
+    });
+
+    // Mock when executeShellCommand is called it creates some new files in the mock filesystem
+    executeShellCommand.mockImplementation(async () => {
+      mockDir.setContent({
+        'intermediate/testfile.json': '{}',
+      });
+    });
+  });
+
+  it(`should ${examples[0].description}`, async () => {
+    const input = yaml.parse(examples[0].example).steps[0].input;
+
+    commandExists.mockResolvedValue(false);
+
+    fetchContents.mockImplementation(() => Promise.resolve());
+
+    await action.handler({
+      ...mockContext,
+      input: {
+        ...mockContext.input,
+        ...input,
+      },
+    });
+
+    expect(fetchContents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reader: mockReader,
+        integrations,
+        baseUrl: mockContext.templateInfo?.baseUrl,
+        fetchUrl: mockContext.input.url,
+        outputPath: join(
+          mockTmpDir,
+          'template',
+          "{{cookiecutter and 'contents'}}",
+        ),
+      }),
+    );
+    expect(containerRunner.runContainer).toHaveBeenCalled();
+  });
+
+  it(`should ${examples[1].description}`, async () => {
+    const input = yaml.parse(examples[1].example).steps[0].input;
+
+    commandExists.mockResolvedValue(false);
+
+    fetchContents.mockImplementation(() => Promise.resolve());
+
+    await action.handler({
+      ...mockContext,
+      input: input,
+    });
+
+    expect(fetchContents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reader: mockReader,
+        integrations,
+        baseUrl: mockContext.templateInfo?.baseUrl,
+        fetchUrl: mockContext.input.url,
+        outputPath: join(
+          mockTmpDir,
+          'template',
+          "{{cookiecutter and 'contents'}}",
+        ),
+      }),
+    );
+    expect(containerRunner.runContainer).toHaveBeenCalled();
+  });
+
+  it(`should ${examples[2].description}`, async () => {
+    const input = yaml.parse(examples[2].example).steps[0].input;
+
+    commandExists.mockResolvedValue(false);
+
+    fetchContents.mockImplementation(() => Promise.resolve());
+
+    await action.handler({
+      ...mockContext,
+      input: {
+        ...mockContext.input,
+        ...input,
+      },
+    });
+
+    expect(fetchContents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reader: mockReader,
+        integrations,
+        baseUrl: mockContext.templateInfo?.baseUrl,
+        fetchUrl: mockContext.input.url,
+        outputPath: join(
+          mockTmpDir,
+          'template',
+          "{{cookiecutter and 'contents'}}",
+        ),
+      }),
+    );
+
+    expect(containerRunner.runContainer).toHaveBeenCalled();
+  });
+
+  it(`should ${examples[3].description}`, async () => {
+    const input = yaml.parse(examples[3].example).steps[0].input;
+
+    commandExists.mockResolvedValue(false);
+
+    fetchContents.mockImplementation(() => Promise.resolve());
+
+    await action.handler({
+      ...mockContext,
+      input: {
+        ...mockContext.input,
+        ...input,
+      },
+    });
+
+    expect(fetchContents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reader: mockReader,
+        integrations,
+        baseUrl: mockContext.templateInfo?.baseUrl,
+        fetchUrl: mockContext.input.url,
+        outputPath: join(
+          mockTmpDir,
+          'template',
+          "{{cookiecutter and 'contents'}}",
+        ),
+      }),
+    );
+    expect(containerRunner.runContainer).toHaveBeenCalled();
+  });
+
+  it(`should ${examples[4].description}`, async () => {
+    const input = yaml.parse(examples[4].example).steps[0].input;
+
+    commandExists.mockResolvedValue(false);
+
+    fetchContents.mockImplementation(() => Promise.resolve());
+
+    await action.handler({
+      ...mockContext,
+      input: {
+        ...mockContext.input,
+        ...input,
+      },
+    });
+
+    expect(fetchContents).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reader: mockReader,
+        integrations,
+        baseUrl: mockContext.templateInfo?.baseUrl,
+        fetchUrl: mockContext.input.url,
+        outputPath: join(
+          mockTmpDir,
+          'template',
+          "{{cookiecutter and 'contents'}}",
+        ),
+      }),
+    );
+    expect(containerRunner.runContainer).toHaveBeenCalled();
+  });
+});

plugins/scaffolder-backend-module-cookiecutter/src/actions/fetch/cookiecutter.examples.ts

@@ -0,0 +1,119 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { TemplateExample } from '@backstage/plugin-scaffolder-node';
+import yaml from 'yaml';
+
+export const examples: TemplateExample[] = [
+  {
+    description: 'Fetch and template using cookiecutter with minimal options.',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'fetchTemplate',
+          action: 'fetch:cookiecutter',
+          name: 'Fetch and Template Using Cookiecutter',
+          input: {
+            url: 'https://google.com/cookie/cutter',
+            values: {
+              help: 'me',
+            },
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description:
+      'Fetch and template using cookiecutter with custom target path.',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'fetchTemplate',
+          action: 'fetch:cookiecutter',
+          name: 'Fetch and Template Using Cookiecutter',
+          input: {
+            url: 'https://google.com/cookie/cutter',
+            targetPath: 'custom-path',
+            values: {
+              help: 'me',
+            },
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description:
+      'Fetch and template using cookiecutter with copyWithoutRender.',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'fetchTemplate',
+          action: 'fetch:cookiecutter',
+          name: 'Fetch and Template Using Cookiecutter',
+          input: {
+            url: 'https://google.com/cookie/cutter',
+            values: {
+              help: 'me',
+            },
+            copyWithoutRender: ['.github/*', '*.md'],
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description:
+      'Fetch and template using cookiecutter with custom extensions.',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'fetchTemplate',
+          action: 'fetch:cookiecutter',
+          name: 'Fetch and Template Using Cookiecutter',
+          input: {
+            url: 'https://google.com/cookie/cutter',
+            values: {
+              help: 'me',
+            },
+            extensions: ['jinja2_time.TimeExtension'],
+          },
+        },
+      ],
+    }),
+  },
+  {
+    description:
+      'Fetch and template using cookiecutter with a custom Docker image.',
+    example: yaml.stringify({
+      steps: [
+        {
+          id: 'fetchTemplate',
+          action: 'fetch:cookiecutter',
+          name: 'Fetch and Template Using Cookiecutter',
+          input: {
+            url: 'https://google.com/cookie/cutter',
+            values: {
+              help: 'me',
+            },
+            imageName: 'custom/cookiecutter-image',
+          },
+        },
+      ],
+    }),
+  },
+];

plugins/scaffolder-backend-module-cookiecutter/src/actions/fetch/cookiecutter.ts

@@ -28,6 +28,7 @@ import {
   fetchContents,
   executeShellCommand,
 } from '@backstage/plugin-scaffolder-node';
+import { examples } from './cookiecutter.examples';
 
 export class CookiecutterRunner {
   private readonly containerRunner?: ContainerRunner;
@@ -156,6 +157,7 @@ export function createFetchCookiecutterAction(options: {
     id: 'fetch:cookiecutter',
     description:
       'Downloads a template from the given URL into the workspace, and runs cookiecutter on it.',
+    examples,
     schema: {
       input: {
         type: 'object',