From fb6ae2d0d0fa10466f88149a284a3baeefae45bc Mon Sep 17 00:00:00 2001 From: Guillaume Tardif Date: Tue, 13 Jun 2023 11:04:02 +0200 Subject: [PATCH] Add doc to setup continuous integration E2E tests for extensions Signed-off-by: Guillaume Tardif --- _data/toc.yaml | 2 + .../build/frontend-extension-tutorial.md | 1 + .../build/minimal-frontend-extension.md | 1 + .../dev/continuous-integration.md | 82 +++++++++++++++++++ desktop/extensions-sdk/dev/test-debug.md | 3 +- desktop/extensions-sdk/quickstart.md | 3 + 6 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 desktop/extensions-sdk/dev/continuous-integration.md diff --git a/_data/toc.yaml b/_data/toc.yaml index 3bd16abe10..9f641ab6c0 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1272,6 +1272,8 @@ manuals: section: - title: "Test and debug" path: /desktop/extensions-sdk/dev/test-debug/ + - title: "Continuous integration" + path: /desktop/extensions-sdk/dev/continuous-integration/ - title: CLI reference path: /desktop/extensions-sdk/dev/usage/ - sectiontitle: Extension APIs diff --git a/desktop/extensions-sdk/build/frontend-extension-tutorial.md b/desktop/extensions-sdk/build/frontend-extension-tutorial.md index 491dedaa67..7e3eab4588 100644 --- a/desktop/extensions-sdk/build/frontend-extension-tutorial.md +++ b/desktop/extensions-sdk/build/frontend-extension-tutorial.md @@ -387,6 +387,7 @@ when you need to debug it. - Add a [backend](./backend-extension-tutorial.md) to your extension. - Learn how to [test and debug](../dev/test-debug.md) your extension. +- Learn how to [setup CI for your extension](../dev/continuous-integration.md). - Learn more about extensions [architecture](../architecture/index.md). - For more information and guidelines on building the UI, see the [Design and UI styling section](../design/design-guidelines.md). - If you want to set up user authentication for the extension, see [Authentication](../guides/oauth2-flow.md). diff --git a/desktop/extensions-sdk/build/minimal-frontend-extension.md b/desktop/extensions-sdk/build/minimal-frontend-extension.md index b916636bb7..91b949da50 100644 --- a/desktop/extensions-sdk/build/minimal-frontend-extension.md +++ b/desktop/extensions-sdk/build/minimal-frontend-extension.md @@ -103,4 +103,5 @@ The left-hand menu displays a new tab with the name of your extension. - Build a more [advanced frontend](./frontend-extension-tutorial.md) extension. - Learn how to [test and debug](../dev/test-debug.md) your extension. +- Learn how to [setup CI for your extension](../dev/continuous-integration.md). - Learn more about extensions [architecture](../architecture/index.md). diff --git a/desktop/extensions-sdk/dev/continuous-integration.md b/desktop/extensions-sdk/dev/continuous-integration.md new file mode 100644 index 0000000000..a744c90484 --- /dev/null +++ b/desktop/extensions-sdk/dev/continuous-integration.md @@ -0,0 +1,82 @@ +--- +title: "Continuous Integration" +description: Automatically test and validate your extension. +keywords: Docker, Extensions, sdk, CI, test, regression +--- + +In order to help validating your extension and ensure it's functional, the Extension SDK provides a set of tools to help you set continuous integration for your extension. + +> The github action and the extension-test-helper library are both [experimental](https://docs.docker.com/release-lifecycle/#experimental). +{: .important } + + +## Setup CI environment with Github action + +You need Docker Desktop to be able to install and validate your extension. +You can start Docker Desktop in Github Actions using the [Docker Desktop Action](https://github.com/docker/desktop-action), with the following step: + +```yaml +steps: + - id: start_desktop + uses: docker/desktop-action/start@v0.1.0 +``` + +> This action supports only Github Action macOS runners at the moment ; you need to specify `runs-on: macOS-latest` for your end to end tests. +{: .important } + +Once the step has executed, the next steps can use Docker Desktop and the Docker CLI to install an test the extension + +## Validating your extension with puppeteer + +Once Docker Desktop is started in the CI, you can build, install and validate your extension with jest and puppeteer. + +First, build and install your extension from your test: + +```ts +import { DesktopUI } from "@docker/extension-test-helper"; +import { exec as originalExec } from "child_process"; +import * as util from "util"; + +export const exec = util.promisify(originalExec); + +// keep a handle on the app to stop it at the end of tests +let dashboard: DesktopUI; + +beforeAll(async () => { + await exec(`docker build -t my/extension:latest .`, { + cwd: "my-extension-src-root", + }); + + await exec(`docker extension install -f my/extension:latest`); +}); +``` + +Then open the Docker Desktop Dashboard and run some tests in your extension UI: + +```ts +describe("Test my extension", () => { + test("should be functional", async () => { + dashboard = await DesktopUI.start(); + + const eFrame = await dashboard.navigateToExtension("my/extension"); + + // use puppeteer APIs to manipulate the UI, click on buttons, expect visual display and validate your extension + await eFrame.waitForSelector("#someElementId"); + }); +}); +``` + +Finally, shutdown the Docker Dashboard and uninstall your extension: + +```ts +afterAll(async () => { + dashboard?.stop(); + await exec(`docker extension uninstall my/extension`); +}); +``` + +## What's next + +- Build an [advanced frontend](../build/frontend-extension-tutorial.md) extension. +- Learn more about extensions [architecture](../architecture/index.md). +- Learn how to [publish your extension](../extensions/index.md). diff --git a/desktop/extensions-sdk/dev/test-debug.md b/desktop/extensions-sdk/dev/test-debug.md index a574bd3d3e..e7f627e1be 100644 --- a/desktop/extensions-sdk/dev/test-debug.md +++ b/desktop/extensions-sdk/dev/test-debug.md @@ -60,7 +60,6 @@ If your extension is composed of one or more services running as containers in t 1. In Docker Desktop, navigate to **Settings**. 2. Under the **Extensions** tab, select the **Show Docker Desktop Extensions system containers** option. You can now view your extension containers and their logs. - ## Clean up To remove the extension, run: @@ -75,4 +74,4 @@ $ docker extension rm - Learn more about extensions [architecture](../architecture/index.md). - Explore our [design principles](../design/design-principles.md). - Take a look at our [UI styling guidelines](../design/index.md). -- Learn how to [publish your extension](../extensions/index.md). +- Learn how to [setup CI for your extension](./continuous-integration.md). diff --git a/desktop/extensions-sdk/quickstart.md b/desktop/extensions-sdk/quickstart.md index 60081a05ed..40d8173943 100644 --- a/desktop/extensions-sdk/quickstart.md +++ b/desktop/extensions-sdk/quickstart.md @@ -48,6 +48,7 @@ $ docker build -t . ```console ? Hub repository (eg. namespace/repository on hub): john/my-extension` ``` + The `docker build` generates an image with name `john/my-extension`. ## Step three: Install and preview the extension @@ -79,11 +80,13 @@ To remove the extension, run: ```console $ docker extension rm ``` + {% include extensions-form.md %} ## What's next - Build a more [advanced frontend](build/frontend-extension-tutorial.md) for your extension. - Learn how to [test and debug](dev/test-debug.md) your extension. +- Learn how to [setup CI for your extension](dev/continuous-integration.md). - Learn more about extensions [architecture](architecture/index.md). - Learn more about [designing the UI](design/design-guidelines.md).