Merge pull request #172 from jupyterlab/fcollonval-patch-1

Add information on how examples are tested

Author: jtpio

README.md

@@ -3,6 +3,34 @@
 [![Github Actions Status](https://github.com/jupyterlab/extension-examples/workflows/CI/badge.svg)](https://github.com/jupyterlab/extension-examples/actions?query=workflow%3ACI)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jupyterlab/extension-examples/master?urlpath=lab)
 
+1. [Goal](#tldr)
+2. [Develop by Examples](#develop-by-examples)
+   1. [Commands](#commands)
+   2. [Command Palette](#command-palette)
+   3. [Context Menu](#context-menu)
+   4. [Custom Log Console](#custom-log-console)
+   5. [Datagrid](#datagrid)
+   6. _[Hello World](#hello-world)_
+   7. [Kernel Messaging](#kernel-messaging)
+   8. [Kernel Output](#kernel-output)
+   9. [Launcher](#launcher)
+   10. [Log Messages](#log-messages)
+   11. [Main Menu](#main-menu)
+   12. [React Widget](#react-widget)
+   13. _[Server Hello World](#server-hello-world)_
+   14. [Settings](#settings)
+   15. [Signals](#signals)
+   16. [State](#state)
+   17. [Toolbar Item](#toolbar-item)
+   18. [Widgets](#widgets)
+3. [Prerequisites](#prerequisites)
+4. [Develop and Use the Examples](#develop-and-use-the-examples)
+5. [Test the Examples](#test-the-examples)
+6. [Install a Published Extension](#install-a-published-extension)
+7. [About JupyterLab](#about-jupyterlab)
+8. [Credits](#credits)
+9. [Community Guidelines and Code of Conduct](#community-guidelines-and-code-of-conduct)
+
 ## TL;DR
 
 The goal of this repository is to show how to develop extensions for [JupyterLab](https://github.com/jupyterlab/jupyterlab), presented as short tutorial series.
@@ -178,7 +206,7 @@ Use State persistence in an extension.
 
 [![State](state/preview.gif)](state)
 
-### [Toolbar item](toolbar-button)
+### [Toolbar Item](toolbar-button)
 
 Add a new button to the notebook toolbar.
 
@@ -275,6 +303,20 @@ and you can refresh your browser to see your changes.
 
 We are using [embedme](https://github.com/zakhenry/embedme) to embed code snippets into the markdown READMEs. If you make changes to the source code, ensure you update the README and run `jlpm embedme` from the root of the repository to regenerate the READMEs.
 
+## Test the Examples
+
+The examples are automatically tested for:
+
+- Homogeneous configuration:  
+  Configuration files are compared to the reference ones of the _hello-world_ example
+- TypeScript code lint
+- Installation in JupyterLab:  
+  The installation is checked by listing the installed extension and running JupyterLab with the helper `python -m jupyterlab.browser_check`
+- Integration test:  
+  Those tests are emulating user action in JupyterLab to check the extension is behaving as expected.  
+  The tests are defined in the `ui-tests` subfolder within each example.
+  This is possible thanks to a tool called [playwright](https://playwright.dev/).
+
 ## Install a Published Extension
 
 Once your extension is published on [pypi.org](https://pypi.org/) (outside of this scope), you can install it

command-palette/ui-tests/README.md

@@ -2,7 +2,7 @@
 
 The test will produce a video to help debugging and check what happened.
 
-To execute integration tests, you can two options:
+To execute integration tests, you have two options:
 
 - use docker-compose (cons: needs to know and use docker) - this is a more reliable solution.
 - run tests locally (cons: will interact with your JupyterLab user settings)
@@ -16,12 +16,12 @@ jlpm install
 jlpm run build:prod
 ```
 
-2. Execute the docker stack (`extension-path` needs to be set accordingly):
+2. Execute the docker stack in the example folder:
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env build
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm e2e
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env down
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env build
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm e2e
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env down
 ```
 
 ## Test locally
@@ -63,7 +63,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**
@@ -96,7 +96,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**

commands/ui-tests/README.md

@@ -2,7 +2,7 @@
 
 The test will produce a video to help debugging and check what happened.
 
-To execute integration tests, you can two options:
+To execute integration tests, you have two options:
 
 - use docker-compose (cons: needs to know and use docker) - this is a more reliable solution.
 - run tests locally (cons: will interact with your JupyterLab user settings)
@@ -16,12 +16,12 @@ jlpm install
 jlpm run build:prod
 ```
 
-2. Execute the docker stack (`extension-path` needs to be set accordingly):
+2. Execute the docker stack in the example folder:
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env build
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm e2e
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env down
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env build
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm e2e
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env down
 ```
 
 ## Test locally
@@ -63,7 +63,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**
@@ -96,7 +96,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**

context-menu/ui-tests/README.md

@@ -2,7 +2,7 @@
 
 The test will produce a video to help debugging and check what happened.
 
-To execute integration tests, you can two options:
+To execute integration tests, you have two options:
 
 - use docker-compose (cons: needs to know and use docker) - this is a more reliable solution.
 - run tests locally (cons: will interact with your JupyterLab user settings)
@@ -16,12 +16,12 @@ jlpm install
 jlpm run build:prod
 ```
 
-2. Execute the docker stack (`extension-path` needs to be set accordingly):
+2. Execute the docker stack in the example folder:
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env build
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm e2e
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env down
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env build
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm e2e
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env down
 ```
 
 ## Test locally
@@ -63,7 +63,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**
@@ -96,7 +96,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**

custom-log-console/ui-tests/README.md

@@ -2,7 +2,7 @@
 
 The test will produce a video to help debugging and check what happened.
 
-To execute integration tests, you can two options:
+To execute integration tests, you have two options:
 
 - use docker-compose (cons: needs to know and use docker) - this is a more reliable solution.
 - run tests locally (cons: will interact with your JupyterLab user settings)
@@ -16,12 +16,12 @@ jlpm install
 jlpm run build:prod
 ```
 
-2. Execute the docker stack (`extension-path` needs to be set accordingly):
+2. Execute the docker stack in the example folder:
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env build
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm e2e
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env down
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env build
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm e2e
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env down
 ```
 
 ## Test locally
@@ -63,7 +63,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**
@@ -96,7 +96,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**

datagrid/ui-tests/README.md

@@ -2,7 +2,7 @@
 
 The test will produce a video to help debugging and check what happened.
 
-To execute integration tests, you can two options:
+To execute integration tests, you have two options:
 
 - use docker-compose (cons: needs to know and use docker) - this is a more reliable solution.
 - run tests locally (cons: will interact with your JupyterLab user settings)
@@ -16,12 +16,12 @@ jlpm install
 jlpm run build:prod
 ```
 
-2. Execute the docker stack (`extension-path` needs to be set accordingly):
+2. Execute the docker stack in the example folder:
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env build
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm e2e
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env down
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env build
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm e2e
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env down
 ```
 
 ## Test locally
@@ -63,7 +63,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**
@@ -96,7 +96,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**

hello-world/ui-tests/README.md

@@ -2,7 +2,7 @@
 
 The test will produce a video to help debugging and check what happened.
 
-To execute integration tests, you can two options:
+To execute integration tests, you have two options:
 
 - use docker-compose (cons: needs to know and use docker) - this is a more reliable solution.
 - run tests locally (cons: will interact with your JupyterLab user settings)
@@ -16,12 +16,12 @@ jlpm install
 jlpm run build:prod
 ```
 
-2. Execute the docker stack (`extension-path` needs to be set accordingly):
+2. Execute the docker stack in the example folder:
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env build
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm e2e
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env down
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env build
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm e2e
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env down
 ```
 
 ## Test locally
@@ -63,7 +63,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**
@@ -96,7 +96,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**

kernel-messaging/ui-tests/README.md

@@ -2,7 +2,7 @@
 
 The test will produce a video to help debugging and check what happened.
 
-To execute integration tests, you can two options:
+To execute integration tests, you have two options:
 
 - use docker-compose (cons: needs to know and use docker) - this is a more reliable solution.
 - run tests locally (cons: will interact with your JupyterLab user settings)
@@ -16,12 +16,12 @@ jlpm install
 jlpm run build:prod
 ```
 
-2. Execute the docker stack (`extension-path` needs to be set accordingly):
+2. Execute the docker stack in the example folder:
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env build
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm e2e
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env down
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env build
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm e2e
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env down
 ```
 
 ## Test locally
@@ -63,7 +63,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**
@@ -96,7 +96,7 @@ jlpm run build:prod
 **Using docker**
 
 ```
-docker-compose -f ./end-to-end-tests/docker-compose.yml --env-file ./extension-path/ui-tests/.env run --rm -p 8888:8888 lab
+docker-compose -f ../end-to-end-tests/docker-compose.yml --env-file ./ui-tests/.env run --rm -p 8888:8888 lab
 ```
 
 **Using local installation**