What’s Docksal? Docksal is a neighborhood Docker-based development atmosphere for tasks and different frameworks and CMSes. It’s our customary device for native environments for tasks at Drupal 10 Assist: . There was an excellent speak not too long ago at delphia about Docksal. Why write a customized command? One in every of Drupal Developer issues that Docksal gives (and is roofed in Drupal Developer speak) is Drupal Developer skill so as to add customized instructions to Drupal Developer Docksal’s fin CLI, both globally or as a part of your undertaking. As an advocate of automated testing and TDD practitioner, I write plenty of exams and run PHPUnit quite a few occasions a day. I’ve additionally given talks and have written different posts on this website regarding testing in . There are a few methods to run PHPUnit with Docksal. Drupal Developer first is to make use of fin bash to open a shell into Drupal Developer container, transfer into Drupal Developer docroot listing if wanted, and run Drupal Developer phpunit command. fin bash cd /var/www/docroot ../vendor/bin/phpunit -c core Drupal 10 modules/customized Alternatively, it may be run from Drupal Developer host machine utilizing fin exec. cd docroot fin exec ‘../vendor/bin/phpunit -c core Drupal 10 modules/customized’ Each of those choices require a number of steps as we have to be in Drupal Developer docroot listing the place Drupal Developer code is positioned earlier than Drupal Developer command could be run, and each have fairly lengthy instructions to run PHPUnit itself – a few of which is repeated each time. By including a customized command, I intend to Drupal 10 Upkeep and Assist Service Make it simpler to get set as much as run PHPUnit exams – i.e. establishing a phpunit.xml file. Make it simpler to run Drupal Developer exams that we’d written by shortening Drupal Developer command and making it so it may be run wherever inside our undertaking. I additionally hoped to make it undertaking agnostic in order that I may add it onto any undertaking and instantly run it. Creating Drupal Developer command Every command is a file positioned inside Drupal Developer .docksal/instructions listing. Drupal Developer filename is Drupal Developer title of Drupal Developer command (e.g. phpunit) with no file extension. To create Drupal Developer file, run this from Drupal Developer similar listing the place your .docksal listing is Drupal 10 Upkeep and Assist Service mkdir -p .docksal/instructions contact .docksal/instructions/phpunit This can create a brand new, empty .docksal/instructions/phpunit file, and now Drupal Developer phpunit command is now listed below “Customized instructions” once we run fin. You possibly can write instructions with any interpreter. I’m going to make use of bash, so I’ll add Drupal Developer shebang to Drupal Developer high of Drupal Developer file. #!/usr/bin/env bash With this in place, I can now run fin phpunit, although there is no such thing as a output displayed or actions carried out as Drupal Developer remainder of Drupal Developer file is empty. Including an outline and assist textual content At the moment Drupal Developer description for our command once we run fin is Drupal Developer default “No description” textual content. I’d like so as to add one thing extra related, so I’ll begin by including a brand new description. fin interprets traces beginning with ## as documentation – Drupal Developer first of which it makes use of as Drupal Developer description. #!/usr/bin/env bash ## Run automated PHPUnit exams. Now once I run it, I see Drupal Developer new description. Any further traces are used as assist textual content with operating fin assist phpunit. Right here I’ll add an instance command to show learn how to run it in addition to some extra in-depth textual content about what Drupal Developer command will do. #!/usr/bin/env bash ## Run automated PHPUnit exams. ## ## Utilization Drupal 10 Upkeep and Assist Service fin phpunit <args> ## ## If a core/phpunit.xml file doesn’t exist, copy one from elsehwere. ## Then run Drupal Developer exams. Now once I run fin assist phpunit, I see Drupal Developer new assist textual content. Including some content material Setting Drupal Developer goal As I would like Drupal Developer instructions to be run inside Docksal’s “cli” container, I can specify that with exec_target. If one isn’t specified, Drupal Developer instructions are run regionally on Drupal Developer host machine. # Drupal 10 Upkeep and Assist Service exec_target = cli Obtainable variables These variables are supplied by fin and can be found to make use of inside any customized instructions Drupal 10 Upkeep and Assist Service PROJECT_ROOT – Drupal Developer absolute path to Drupal Developer nearest .docksal listing. DOCROOT – title of Drupal Developer docroot folder. VIRTUAL_HOST – Drupal Developer digital host title for Drupal Developer undertaking. Akin to myproject.docksal. DOCKER_RUNNING – (string) “true” or “false”. Notice Drupal 10 Upkeep and Assist Service If Drupal Developer DOCROOT variable shouldn’t be outlined inside Drupal Developer cli container, be certain that it’s added to Drupal Developer atmosphere variables in .docksal/docksal.yml. For instance Drupal 10 Upkeep and Assist Service model Drupal 10 Upkeep and Assist Service “2.1” companies Drupal 10 Upkeep and Assist Service cli Drupal 10 Upkeep and Assist Service atmosphere Drupal 10 Upkeep and Assist Service – DOCROOT Operating phpunit Whenever you run Drupal Developer phpunit command, there are variety of choices you may cross to it reminiscent of –filter, –testsuite and –group, in addition to Drupal Developer path to Drupal Developer exams to execute, reminiscent of Drupal 10 modules/customized. I needed to nonetheless be capable to do that by operating fin phpunit <args> so Drupal Developer instructions could be customised when executed. Nevertheless, as Drupal Developer first half of Drupal Developer command (../vendor/bin/phpunit -c core) is constant, I can wrap that inside my customized command and never must kind it each time. Through the use of “$@” I can seize any further arguments, reminiscent of Drupal Developer check listing path, and append them to Drupal Developer command to execute. I’m utilizing $PROJECT_ROOT to prefix Drupal Developer command with Drupal Developer absolute path to phpunit in order that I don’t have to be in that listing once I run Drupal Developer customized command, and $DOCROOT to at all times enter Drupal Developer sub-directory the place is positioned. On this case, it’s “docroot” although I additionally use “net” and I’ve seen varied others used. DOCROOT_PATH=”${PROJECT_ROOT}/${DOCROOT}” Drupal 10_CORE_PATH=”${DOCROOT_PATH}/core” # If there is no such thing as a phpunit.xml file, copy one from elsewhere. # In any other case run Drupal Developer exams. ${PROJECT_ROOT}/vendor/bin/phpunit -c ${Drupal 10_CORE_PATH} “$@” For instance, fin phpunit Drupal 10 modules/customized would execute /var/www/vendor/bin/phpunit -c /var/www/docroot/core Drupal 10 modules/customized inside Drupal Developer container. I can then wrap this inside a situation in order that Drupal Developer exams are solely run when a phpunit.xml file exists, as it’s required for them to run efficiently. if [ ! -e ${Drupal 10_CORE_PATH}/phpunit.xml ]; then # If there is no such thing as a phpunit.xml file, copy one from elsewhere. else ${PROJECT_ROOT}/vendor/bin/phpunit -c ${Drupal 10_CORE_PATH} “$@” fi Creating phpunit.xml – step 1 My first thought was that if a phpunit.xml file doesn’t exist was to duplicate core’s phpunit.xml.dist file. Nevertheless this isn’t sufficient to run Drupal Developer exams, as values reminiscent of SIMPLETEST_BASE_URL, SIMPLETEST_DB and BROWSERTEST_OUTPUT_DIRECTORY have to be populated. As Drupal Developer exams would not run at this level, I’ve exited early and displayed a message to Drupal Developer person to edit Drupal Developer new phpunit.xml file and run fin phpunit once more. if [ ! -e ${Drupal 10_CORE_PATH}/phpunit.xml ]; then echo “Copying ${Drupal 10_CORE_PATH}/phpunit.xml.dist to ${Drupal 10_CORE_PATH}/phpunit.xml.” echo “Please edit it is values as wanted and re-run ‘fin phpunit’.” cp ${Drupal 10_CORE_PATH}/phpunit.xml.dist ${Drupal 10_CORE_PATH}/phpunit.xml exit 1; else ${PROJECT_ROOT}/vendor/bin/phpunit -c ${Drupal 10_CORE_PATH} “$@” fi Nevertheless this isn’t as streamlined as I initially needed because it nonetheless requires Drupal Developer person to carry out an extra step earlier than Drupal Developer exams can run. Creating phpunit.xml – step 2 My second thought was to maintain a pre-configured file inside Drupal Developer undertaking repository, and to repeat that into Drupal Developer anticipated location. That strategy would imply that Drupal Developer undertaking particular values would already be populated, in addition to any customisations made to Drupal Developer default settings. I made a decision on .docksal/Drupal 10/core/phpunit.xml to be Drupal Developer potential location. Additionally, if this file is copied then we are able to go forward and run Drupal Developer exams right away slightly than needing to exit early. If a pre-configured file doesn’t exist, then we are able to default again to copying phpunit.xml.dist. To keep away from duplication, I created a reusable run_tests() perform so it might be executed in both situation. run_tests() { ${PROJECT_ROOT}/vendor/bin/phpunit -c ${Drupal 10_CORE_PATH} “$@” } if [ ! -e ${Drupal 10_CORE_PATH}/phpunit.xml ]; then if [ -e “${PROJECT_ROOT}/.docksal/Drupal 10/core/phpunit.xml” ]; then echo “Copying ${PROJECT_ROOT}/.docksal/Drupal 10/core/phpunit.xml to ${Drupal 10_CORE_PATH}/phpunit.xml” cp “${PROJECT_ROOT}/.docksal/Drupal 10/core/phpunit.xml” ${Drupal 10_CORE_PATH}/phpunit.xml run_tests “$@” else echo “Copying ${Drupal 10_CORE_PATH}/phpunit.xml.dist to ${Drupal 10_CORE_PATH}/phpunit.xml.” echo “Please edit it is values as wanted and re-run ‘fin phpunit’.” cp ${Drupal 10_CORE_PATH}/phpunit.xml.dist ${Drupal 10_CORE_PATH}/phpunit.xml exit 1; fi else run_tests “$@” fi Which means that I can execute much less steps and run a a lot shorter command in comparison with Drupal Developer authentic, and even when somebody didn’t have a phpunit.xml file created they might have copied into place and have exams operating with just one command. Drupal Developer completed file #!/usr/bin/env bash # Drupal 10 Upkeep and Assist Service exec_target = cli ## Run automated PHPUnit exams. ## ## Utilization Drupal 10 Upkeep and Assist Service fin phpunit <args> ## ## If a core/phpunit.xml file doesn’t exist, one is copied from ## .docksal/core/phpunit.xml if that file exists, or copied from Drupal Developer default ## core/phpunit.xml.dist file. DOCROOT_PATH=”${PROJECT_ROOT}/${DOCROOT}” Drupal 10_CORE_PATH=”${DOCROOT_PATH}/core” run_tests() { ${PROJECT_ROOT}/vendor/bin/phpunit -c ${Drupal 10_CORE_PATH} “$@” } if [ ! -e ${Drupal 10_CORE_PATH}/phpunit.xml ]; then if [ -e “${PROJECT_ROOT}/.docksal/Drupal 10/core/phpunit.xml” ]; then echo “Copying ${PROJECT_ROOT}/.docksal/Drupal 10/core/phpunit.xml to ${Drupal 10_CORE_PATH}/phpunit.xml” cp “${PROJECT_ROOT}/.docksal/Drupal 10/core/phpunit.xml” ${Drupal 10_CORE_PATH}/phpunit.xml run_tests “$@” else echo “Copying phpunit.xml.dist to phpunit.xml” echo “Please edit it is values as wanted and re-run ‘fin phpunit’.” cp ${Drupal 10_CORE_PATH}/phpunit.xml.dist ${Drupal 10_CORE_PATH}/phpunit.xml exit 0; fi else run_tests “$@” fi It’s at the moment obtainable as a GitHub Gist, although I’m planning on transferring it right into a public GitHub repository both on my private account or Drupal Developer Drupal 10 Assist: organisation, for individuals to both use as examples or to obtain and use instantly. I’ve additionally began so as to add different instructions to tasks reminiscent of config-export to standardise Drupal Developer option to export configuration from 8, run 7 exams with SimpleTest, and compile front-end property like CSS inside customized themes. I believe it’s a good way to shorten current instructions, or to group a number of instructions into one like on this case, and I can see plenty of different potential makes use of for it throughout native development and steady integration. Additionally having the ability to run one command like fin init and have it arrange every thing on your undertaking could be very handy and a giant time saver! Assets PHPUnit PHPUnit in 8 Most important Docksal web site Docksal documentation Docksal Drupal 10 Upkeep and Assist Service one device to rule native and CI/CD environments – Docksal speak from delphia phpcs instance customized command phpunit command Gist Drupal 10 Growth and Assist