Running Dyalog ]dtest in Docker and GitHub Actions

Workshop aims

The aims of this workshop is to demonstrate how you can get your tests to run automatically for you 'in the clouds' using Docker and the GitHub Actions continous integration (CI) framework. This means that every time you make a change and push this to the main branch of your repository, your tests will run, and the results will become visible in the GitHub web interface without any further actions from you.

If you're not used to using GitHub to host your APL code, worry not -- we'll work it through together. Even if you prefer another source code revisioning system, or another CI framework (like circle or jenkins), the broad strokes of the approach we'll cover here should hopefully still be relevant to you.

GitHub Actions is free to use for public repositories, and private repositories get a limited, but generous, allocation of free minutes of runner time.

Pre-requisites

To make the most of this workshop, check that

you have Docker desktop installed
you have Dyalog APL v18.2 installed
you have a GitHub account you can create repositories in
you have git installed on your computer

If you're on a Mac, install the follwing shell alias to make it easier to run Dyalog from the command line:

alias dyalog="/Applications/Dyalog-18.2.app/Contents/Resources/Dyalog/mapl"

Place this in your shell's expected config file (~/.bashrc or ~/.bash_profile if you use bash or ~/.zshrc if you use zsh) and run source {your-shell-config-file}.

These are the minimum requirements.

Optionally, there are plenty of auxiliary tools that make working with git and GitHub more streamlined if you're not a fan of the git command line. Some examples are:

GitHub CLI
GitHub Desktop.
Mac users may want to consider installing GitUp

Many popular IDEs and code editors have excellent git and GitHub integration, e.g. Visual Studio Code.

If you do intend to use the GitHub CLI (note: optional), it might be a good idea to get that installed and set up before the day. Same with using git over SSH (a good idea, but also optional) -- ensure you have working SSH keys installed prior to the workshop.

Get set up

Now let's get this repository into your own account, and then onto your computer.

Fork this repository into your own GitHub account, either using
- the GitHub web interface, or
- the GitHub CLI: gh repo fork dyalog-training/2023-TP1b
Clone your fork to your local machine, using one of the following methods:
- Git SSH: git clone --recursive git@github.com:{YOUR-GITHUB-ACCOUNT}}/2023-TP1b.git
- Git HTTPS: git clone --recursive https://github.com/{YOUR-GITHUB-ACCOUNT}/2023-TP1b.git
- GitHub Desktop

Repository contents

This repository contains:

A test runner, run.aplf
A single function under test (for demo purposes), mysum.aplf
A directory containing two demo unit tests, written using ]dtest, tests
A Dockerfile, capable of executing the unit tests
A yaml file test-runner.yml, which will use the Dockerfile to run the unit tests as a GitHub Actions workflow.

Any push to the main branch of this repository should trigger the unit tests to run in the workflow.

Link the code into your workspace

]link.create # {/path/to}/2023-TP1b/src

Replace {/path/to} with the actual path to the 2023-TP1b you cloned.

Trigger the tests manually

]dtest {/path/to}/2023-TP1b/tests

Running tests from the command line

The source directory contains a test runner that enables us to trigger the tests from the command line:

% dyalog -b -s LOAD=src

That command exits with a 0 if all went OK, and 11 otherwise.

Build the Docker container

docker build -t dytest .

Run the unit tests inside the Docker container

Mac/Linux:

docker run --rm \
  -v "$(pwd)/DBuildTest/DyalogBuild.dyalog:/home/dyalog/MyUCMDs/DyalogBuild.dyalog" \
  -v "$(pwd)/src:/src" \
  -v "$(pwd)/tests:/tests" \
  dytest

In Windows PowerShell:

docker run --rm `
  -v "${PWD}/DBuildTest/DyalogBuild.dyalog:/home/dyalog/MyUCMDs/DyalogBuild.dyalog" `
  -v "${PWD}/src:/src" `
  -v "${PWD}/tests:/tests" `
  dytest

Using the Windows Command Prompt:

docker run --rm -v "%cd%\DBuildTest\DyalogBuild.dyalog:/home/dyalog/MyUCMDs/DyalogBuild.dyalog" -v "%cd%\src:/src" -v "%cd%\tests:/tests" dytest

xpqz/testws