Merge pull request #1 from discoverygarden/implementation

DDST-754, FDSF-221: Initial implementation

Author: nchiasson-dgi

README.md

@@ -1,54 +1,43 @@
-[![tests](https://github.com/ddev/ddev-addon-template/actions/workflows/tests.yml/badge.svg)](https://github.com/ddev/ddev-addon-template/actions/workflows/tests.yml) ![project is maintained](https://img.shields.io/maintenance/yes/2025.svg)
+[![tests](https://github.com/discoverygarden/ddev-dgi-playwright/actions/workflows/tests.yml/badge.svg)](https://github.com/discoverygarden/ddev-dgi-playwright/actions/workflows/tests.yml) ![project is maintained](https://img.shields.io/maintenance/yes/2025.svg)
 
-# DDEV add-on template <!-- omit in toc -->
+# DGI-PLAYWRIGHT
 
-* [What is DDEV add-on template?](#what-is-ddev-add-on-template)
-* [Components of the repository](#components-of-the-repository)
-* [Getting started](#getting-started)
-* [How to debug in Github Actions](./README_DEBUG.md)
+Playwright integration for DGI projects, adapted from and using [Lullabot/ddev-playwright](https://github.com/Lullabot/ddev-playwright).
 
-## What is DDEV add-on template?
+## Enable
 
-This repository is a template for providing [DDEV](https://ddev.readthedocs.io) add-ons and services.
+Setup process should be straight forward. Download add-on, run install script, and tests will be immediately accessible to run:
 
-In DDEV, add-ons can be installed from the command line using the `ddev add-on get` command, for example, `ddev add-on get ddev/ddev-redis` or `ddev add-on get ddev/ddev-solr`.
+```
+# Installs the add-on
+ddev add-on get discoverygarden/ddev-dgi-playwright
 
-This repository is a quick way to get started. You can create a new repo from this one by clicking the template button in the top right corner of the page.
+# Installs playwright with dgi additions
+ddev install-dgi-playwright
+```
 
-![template button](images/template-button.png)
+## Use playwright
 
-## Components of the repository
+```
+# Runs playwright using playwrights `test` command.
+ddev playwright test
 
-* The fundamental contents of the add-on service or other component. For example, in this template there is a [docker-compose.addon-template.yaml](docker-compose.addon-template.yaml) file.
-* An [install.yaml](install.yaml) file that describes how to install the service or other component.
-* A test suite in [test.bats](tests/test.bats) that makes sure the service continues to work as expected.
-* [Github actions setup](.github/workflows/tests.yml) so that the tests run automatically when you push to the repository.
+# Runs playwright with access to the UI accessible at <siteuri>:9324
+ddev playwright-ui
 
-## Getting started
+## Runs playwright in codegen mode
+ddev playwright codegen
+```
 
-1. Choose a good descriptive name for your add-on. It should probably start with "ddev-" and include the basic service or functionality. If it's particular to a specific CMS, perhaps `ddev-<CMS>-servicename`.
-2. Create the new template repository by using the template button.
-3. Globally replace "addon-template" with the name of your add-on.
-4. Add the files that need to be added to a DDEV project to the repository. For example, you might replace `docker-compose.addon-template.yaml` with the `docker-compose.*.yaml` for your recipe.
-5. Update the `install.yaml` to give the necessary instructions for installing the add-on:
+## Composer Package Type Details
 
-   * The fundamental line is the `project_files` directive, a list of files to be copied from this repo into the project `.ddev` directory.
-   * You can optionally add files to the `global_files` directive as well, which will cause files to be placed in the global `.ddev` directory, `~/.ddev`.
-   * Finally, `pre_install_commands` and `post_install_commands` are supported. These can use the host-side environment variables documented [in DDEV docs](https://ddev.readthedocs.io/en/stable/users/extend/custom-commands/#environment-variables-provided).
+We define and make use of two "types" of composer project:
+* `dgi-playwright-core`: Defining the core Playwright config, including `playwright.config.ts` and including `package.json`/`package-lock.json` indicating the Node.js packages needed; and,
+* `dgi-playwright-tests`: Defining a set of tests to run.
 
-6. Update `tests/test.bats` to provide a reasonable test for your repository. Tests will run automatically on every push to the repository, and periodically each night. Please make sure to address test failures when they happen. Others will be depending on you. Bats is a testing framework that just uses Bash. To run a Bats test locally, you have to install [bats-core](https://bats-core.readthedocs.io/en/stable/installation.html) and its [libraries](https://github.com/ztombol/bats-docs) first. Then you download your add-on, and finally run `bats ./tests/test.bats` within the root of the uncompressed directory. To learn more about Bats see the [documentation](https://bats-core.readthedocs.io/en/stable/).
-7. When everything is working, including the tests, you can push the repository to GitHub.
-8. Create a [release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) on GitHub.
-9. Test manually with `ddev add-on get <owner/repo>`.
-10. You can test PRs with `ddev add-on get https://github.com/<user>/<repo>/tarball/<branch>`.
-11. You can test add-ons locally without GitHub by downloading them, making changes and running `ddev add-on get /path/to/add-on-directory`.
-12. Update the `README.md` header, adding the machine name of the add-on, for example `# ddev-redis`, not `# DDEV Redis`.
-13. Update the `README.md` to describe the add-on, how to use it, and how to contribute. If there are any manual actions that have to be taken, please explain them. If it requires special configuration of the using project, please explain how to do those. Examples in [ddev/ddev-solr](https://github.com/ddev/ddev-solr), [ddev/ddev-memcached](https://github.com/ddev/ddev-memcached), and (advanced) [ddev-platformsh](https://github.com/ddev/ddev-platformsh).
-14. Add a good short description to your repo, and add the [topic](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) "ddev-get". It will immediately be added to the list provided by `ddev add-on list --all`.
-15. When it has matured you will hopefully want to have it become an "official" maintained add-on. Open an issue in the [DDEV queue](https://github.com/ddev/ddev/issues) for that.
+We expect only one `dgi-playwright-core` package to be installed in a project (into `test/playwright`), and any number of `dgi-playwright-tests` packages (which should get installed into `test/playwright-tests/{$name}`, where `{$name}` is the name of the package without its namespace, as per [`composer/installers`](https://github.com/composer/installers)).
 
-Add-ons were covered in [DDEV Add-ons: Creating, maintaining, testing](https://www.youtube.com/watch?v=TmXqQe48iqE) (part of the [DDEV Contributor Live Training](https://ddev.com/blog/contributor-training)).
+## Additional Resources
 
-Note that more advanced techniques are discussed in [Advanced Add-On Techniques](https://ddev.com/blog/advanced-add-on-contributor-training/) and [DDEV docs](https://ddev.readthedocs.io/en/stable/users/extend/additional-services/).
-
-**Contributed and maintained by `@CONTRIBUTOR`**
+* [Playwright basic usage docs](https://playwright.dev/docs/intro)
+* [Lullabot/ddev-playwright](https://github.com/Lullabot/ddev-playwright)

README_DEBUG.md

@@ -0,0 +1,36 @@
+#!/bin/bash
+#ddev-generated
+
+ENV_FILE=".ddev/.env.dgi-playwright"
+
+if ! [ "$(ddev dotenv get $ENV_FILE --composer-installed 2> /dev/null)" == "true" ] ; then
+  # Add base .gitignore
+  mkdir -p $DDEV_APPROOT/test
+  echo "playwright" >> $DDEV_APPROOT/test/.gitignore
+  echo "playwright-tests" >> $DDEV_APPROOT/test/.gitignore
+
+  # Adding the new dgi-playwright-tests installer type and path
+  ddev composer require --no-update "oomphinc/composer-installers-extender:^2.0"
+  ddev composer config --merge --json -- extra.installer-types '["dgi-playwright-core", "dgi-playwright-tests"]'
+  ddev composer config --merge --json -- extra.installer-paths.test/playwright '["type:dgi-playwright-core"]'
+  ddev composer config --merge --json -- 'extra.installer-paths.test/playwright-tests/{$name}' '["type:dgi-playwright-tests"]'
+
+  # Installing the new basic playwright tests
+  ddev composer require --dev --no-update \
+    "discoverygarden/playwright-testing-core:^1" \
+    "discoverygarden/playwright-testing-sample-tests:^1"
+
+  ddev composer update oomphinc/composer-installers-extender \
+    discoverygarden/playwright-testing-core \
+    discoverygarden/playwright-testing-sample-tests
+
+  ddev dotenv set $ENV_FILE --composer-installed true
+fi
+
+if ! diff -q $DDEV_APPROOT/.ddev/web-build/disabled.Dockerfile.playwright $DDEV_APPROOT/.ddev/web-build/Dockerfile.playwright ; then
+  # ddev errors out on subsequent builds if we symlink these files. Instead, we
+  # copy them each time.
+  echo "Rebuilding web service with playwright dependencies..."
+  cp $DDEV_APPROOT/.ddev/web-build/disabled.Dockerfile.playwright $DDEV_APPROOT/.ddev/web-build/Dockerfile.playwright
+  ddev restart
+fi

commands/host/install-dgi-playwright

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+#ddev-generated
+## Description: Shortcut command to run playwright in the ui
+## Usage: playwright-ui
+
+set -e
+
+ddev playwright test --ui-host 0.0.0.0 --ui-port 9323
+## Afterwards, navigate to `<hostURI>:9324` to run tests with the UI.
+## Setting the port here in reference to the container_port value from the config
+## https://github.com/discoverygarden/ddev-dgi-playwright/blob/main/config.playwright.yml#L28

commands/host/playwright-ui

@@ -0,0 +1,18 @@
+#!/bin/bash
+#ddev-generated
+
+#  When initially starting the container, the NSS DB is not populated, so
+# let's pre-populate it so we can `mkcert -install` the cert into it.
+# Note that the DB would be created after attempting to run the tests once,
+# when the browser(s) start.
+NSSDB=$HOME/.pki/nssdb
+if ! [[ -d $NSSDB ]] ; then
+  mkdir -p $NSSDB
+  certutil -d $NSSDB -N --empty-password
+fi
+mkcert -install
+
+export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"
+export NODE_PATH=$NODE_PATH:$DDEV_COMPOSER_ROOT/test/playwright/node_modules
+cd test/playwright || exit 1
+npm ci && exec npx playwright "$@"

commands/web/playwright

@@ -0,0 +1,36 @@
+#ddev-generated
+hooks:
+  pre-start:
+    # If Playwright is enabled, make sure we get any changes.
+    - exec-host: |
+        ([[ -f .ddev/web-build/Dockerfile.playwright ]] && \
+          cp .ddev/web-build/disabled.Dockerfile.playwright .ddev/web-build/Dockerfile.playwright) || true
+    - exec-host: |
+        if [[ -f .ddev/web-build/Dockerfile.playwright ]]
+        then
+          rm -rf .ddev/web-build/playwright
+          cp -r test/playwright .ddev/web-build/
+        fi
+  post-start:
+    # Clean up the playwright directory copied for builds.
+    # We want to remove this otherwise future ddev get's will not copy in
+    # changes to the web-build directory.
+    - exec-host: rm -rf .ddev/web-build/playwright
+web_environment:
+  - DISPLAY=:1
+  - DGI_PLAYWRIGHT_TESTS_DIR=$DDEV_COMPOSER_ROOT/test/playwright-tests
+  - DGI_PLAYWRIGHT_TEST_URL=$DDEV_PRIMARY_URL
+# We add the sleep so this doesn't error out when not using playwright.
+web_extra_daemons:
+  - name: "kasmvnc"
+    command: "kasmvncserver -fg || sleep infinity"
+    directory: /var/www/html
+web_extra_exposed_ports:
+  - name: playwright
+    container_port: 9323
+    http_port: 8323
+    https_port: 9324
+  - name: kasmvnc
+    container_port: 8444
+    http_port: 8443
+    https_port: 8444

config.playwright.yml

@@ -1,6 +1,4 @@
-# Details about the install.yaml file are at https://ddev.readthedocs.io/en/stable/users/extend/additional-services/#sections-and-features-of-ddev-get-add-on-installyaml
-
-name: addon-template
+name: dgi-playwright
 
 # pre_install_actions - list of actions to run before installing the addon.
 # Examples would be removing an extraneous docker volume,
@@ -59,14 +57,17 @@ pre_install_actions:
 # If you use directories, they must be directories that are managed
 # by this add-on, or removal could remove things that are not owned by it
 project_files:
-  - docker-compose.addon-template.yaml
-  # - commands/web/add-on-command
-  # - commands/host/add-on-command-host
-  # - web-build/Dockerfile.addon-template
-  # - some-directory/file1.txt
-  # - some-directory/file2.txt
-  # - extra_files_dir_created_by_this_template/
-  # - somefile.sh
+  - commands/host/playwright-ui
+  - commands/host/install-dgi-playwright
+  - commands/web/playwright
+  - web-build/.gitignore
+  - web-build/disabled.Dockerfile.playwright
+  - web-build/Dockerfile.task
+  - web-build/install-task.sh
+  - web-build/install-kasmvnc.sh
+  - web-build/kasmvnc.yaml
+  - web-build/xstartup
+  - config.playwright.yml
 
 # List of files and directories that are copied into the global .ddev directory
 # DDEV environment variables can be interpolated into these filenames
@@ -85,7 +86,7 @@ ddev_version_constraint: '>= v1.24.2'
 
 # List of add-on names that this add-on depends on
 dependencies:
-  # - redis
+   # - redis
 
 # DDEV environment variables can be interpolated into these actions.
 # post_install_actions are executed in the context of the target project's .ddev directory.
@@ -98,15 +99,9 @@ post_install_actions:
 # Files listed in project_files section will be automatically removed here if they contain #ddev-generated line.
 # removal_actions are executed in the context of the target project's .ddev directory.
 removal_actions:
-  # - rm ~/.ddev/commands/web/somecommand
-  # - |
-  #   if [ -f ${DDEV_APPROOT}/.ddev/docker-compose.addon-template_extras.yaml ]; then
-  #     if grep -q '#ddev-generated' ${DDEV_APPROOT}/.ddev/docker-compose.addon-template_extras.yaml; then
-  #       rm -f ${DDEV_APPROOT}/.ddev/docker-compose.addon-template_extras.yaml
-  #     else
-  #       echo "Unwilling to remove '${DDEV_APPROOT}/.ddev/docker-compose.addon-template_extras.yaml' because it does not have #ddev-generated in it; you can manually delete it if it is safe to delete."
-  #     fi
-  #   fi
+  - |
+    #ddev-description:Deleting generated Dockerfile.
+    if grep "#ddev-generated" web-build/Dockerfile.playwright 2>/dev/null; then rm web-build/Dockerfile.playwright; fi
 
 # Advanced usage - YAML files can be read in and then used as go template actions
 # in pre_install_actions and post_install_actions