Initial logic

Author: Alan Christie

.github/workflows/build.yaml

@@ -0,0 +1,47 @@
+---
+name: build
+
+# -----------------
+# Control variables (GitHub Secrets)
+# -----------------
+#
+# At the GitHub 'organisation' or 'project' level you must have the following
+# GitHub 'Repository Secrets' defined (i.e. via 'Settings -> Secrets'): -
+#
+# (none)
+#
+# -----------
+# Environment (GitHub Environments)
+# -----------
+#
+# Environment         (none)
+
+on:
+- push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+        - '3.10'
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install requirements
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install -r build-requirements.txt
+        pip install -r package-requirements.txt
+    - name: Test
+      run: |
+        pyroma .
+    - name: Build
+      run: |
+        python setup.py bdist_wheel

.github/workflows/publish.yaml

@@ -0,0 +1,52 @@
+---
+name: publish
+
+# Actions for any tag.
+
+# -----------------
+# Control variables (GitHub Secrets)
+# -----------------
+#
+# At the GitHub 'organisation' or 'project' level you must have the following
+# GitHub 'Repository Secrets' defined (i.e. via 'Settings -> Secrets'): -
+#
+# PYPI_USERNAME
+# PYPI_TOKEN
+#
+# -----------
+# Environment (GitHub Environments)
+# -----------
+#
+# Environment         (none)
+
+on:
+  push:
+    tags:
+    - '**'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+    - name: Inject slug/short variables
+      uses: rlespinasse/[email protected]
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.10'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r build-requirements.txt
+        pip install -r package-requirements.txt
+    - name: Build
+      run: |
+        pyroma .
+        python setup.py bdist_wheel
+    - name: Publish
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: ${{ secrets.PYPI_USERNAME }}
+        password: ${{ secrets.PYPI_TOKEN }}

.gitignore

@@ -0,0 +1,11 @@
+.idea
+.pytest_cache
+.coverage
+*.egg-info
+**/__pycache__
+venv
+build
+dist
+
+jote/data
+jote/data-manager

MANIFEST.in

@@ -0,0 +1 @@
+include LICENSE

README.rst

@@ -0,0 +1,72 @@
+Informatics Matters Job Tester
+==============================
+
+The Job Tester (``jote``) is used to run unit tests located in
+Data Manager Job implementation repositories against the Job's
+container image.
+
+Job implementations are required to provide a Job Definition (in the
+Job repository's ``data-manager`` directory) and at least one test, located in
+the repository's ``data-manager/tests`` directory. ``jote`` runs the tests
+but also ensures the repository structure meets the Data Manager requirements.
+
+Tests are dined in the Job definition file in the block where the the test
+is defined. Here's a snippet illustrating a test called ``simple-execution``
+that defines an input option defining a file and some other command
+options along with a ``checks`` section that defines the exit criteria
+of a successful test::
+
+    jobs:
+      [...]
+      shard:
+        [...]
+        tests:
+          simple-execution:
+            inputs:
+              inputFile: data/100000.smi
+            options:
+              outputFile: diverse.smi
+              count: 100
+            checks:
+              exitCode: 0
+              outputs:
+              - name: diverse.smi
+                exists: true
+                lineCount: 100
+
+Installation
+------------
+
+Pyconf is published on `PyPI`_ and can be installed from
+there::
+
+    pip install im-jote
+
+This is a Python 3 utility, so try to run it from a recent (ideally 3.10)
+Python environment.
+
+To use the utility you will need to have installed `Docker`_
+and `docker-compose`_.
+
+.. _PyPI: https://pypi.org/project/im-jote/
+.. _Docker: https://docs.docker.com/get-docker/
+.. _docker-compose: https://pypi.org/project/docker-compose/
+
+Running tests
+-------------
+
+Run ``jote`` from the root of a clone of the Data Manager Job implementation
+repository that you want to test::
+
+    jote
+
+You can display the utility's help with::
+
+    jote --help
+
+Get in touch
+------------
+
+- Report bugs, suggest features or view the source code `on GitHub`_.
+
+.. _on GitHub: https://github.com/informaticsmatters/data-manager-job-tester

build-requirements.txt

@@ -0,0 +1,3 @@
+pyroma == 3.2
+pytest == 6.2.5
+pytest-cov == 3.0.0

jote/__init__.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+
+"""An entry-point that allows the module to be executed.
+This also simplifies the distribution as this is the
+entry-point for the console script (see setup.py).
+"""
+
+import sys
+from .jote import main as jote_main
+
+
+def main():
+    """The entry-point of the component."""
+    return jote_main()
+
+
+if __name__ == '__main__':
+    sys.exit(main())

jote/__main__.py

@@ -0,0 +1,141 @@
+"""The Job Tester 'compose' module.
+
+This module is responsible for injecting a docker-compose file into the
+repository of the Data Manager Job repository under test. It also
+executes docker-compose and can remove the test directory.
+"""
+import os
+import shutil
+import subprocess
+from typing import Dict, Optional, Tuple
+
+_INSTANCE_DIRECTORY: str = '.instance-88888888-8888-8888-8888-888888888888'
+
+_COMPOSE_CONTENT: str = """---
+version: '3.8'
+services:
+  job:
+    image: {image}
+    command: {command}
+    environment:
+    - DM_INSTANCE_DIRECTORY={instance_directory}
+    volumes:
+    - {test_path}:{project_directory}
+    deploy:
+      resources:
+        limits:
+          cpus: 1
+          memory: 1G
+"""
+
+# A default, 30 minute timeout
+_DEFAULT_TEST_TIMEOUT: int = 30 * 60
+
+# The docker-compose version (for the first test)
+_COMPOSE_VERSION: Optional[str] = None
+
+
+def _get_docker_compose_version() -> str:
+
+    result: subprocess.CompletedProcess =\
+        subprocess.run(['docker-compose', 'version'],
+                       capture_output=True, timeout=4)
+
+    # stdout will contain the version on the first line: -
+    # "docker-compose version 1.29.2, build unknown"
+    # Ignore the first 23 characters of the first line...
+    return result.stdout.decode("utf-8").split('\n')[0][23:]
+
+
+def get_test_path(test_name: str) -> str:
+    """Returns the path to the root directory for a given test.
+    """
+    cwd: str = os.getcwd()
+    return f'{cwd}/data-manager/jote/{test_name}'
+
+
+def create(test_name: str,
+           image: str,
+           project_directory: str,
+           command: str) -> str:
+    """Writes a docker-compose file
+    and creates the test directory structure returning the
+    full path to the test (project) directory.
+    """
+    global _COMPOSE_VERSION
+
+    print('# Creating test environment...')
+
+    # Do we have the docker-compose version the user's installed?
+    if not _COMPOSE_VERSION:
+        _COMPOSE_VERSION = _get_docker_compose_version()
+        print(f'# docker-compose ({_COMPOSE_VERSION})')
+
+    # Make the test directory...
+    test_path: str = get_test_path(test_name)
+    project_path: str = f'{test_path}/project'
+    inst_path: str = f'{project_path}/{_INSTANCE_DIRECTORY}'
+    if not os.path.exists(inst_path):
+        os.makedirs(inst_path)
+
+    # Write the Docker compose content to a file to the test directory
+    variables: Dict[str, str] = {'test_path': project_path,
+                                 'image': image,
+                                 'command': command,
+                                 'project_directory': project_directory,
+                                 'instance_directory': _INSTANCE_DIRECTORY}
+    compose_content: str = _COMPOSE_CONTENT.format(**variables)
+    compose_path: str = f'{test_path}/docker-compose.yml'
+    with open(compose_path, 'wt') as compose_file:
+        compose_file.write(compose_content)
+
+    print('# Created')
+
+    return project_path
+
+
+def run(test_name: str) -> Tuple[int, str, str]:
+    """Runs the container for the test, expecting the docker-compose file
+    written by the 'create()'. The container exit code is returned to the
+    caller along with the stdout and stderr content.
+    A non-zero exit code does not necessarily mean the test has failed.
+    """
+
+    print('# Executing the test ("docker-compose up")...')
+
+    cwd = os.getcwd()
+    os.chdir(get_test_path(test_name))
+
+    timeout: int = _DEFAULT_TEST_TIMEOUT
+    try:
+        # Run the container
+        # and then cleanup
+        test: subprocess.CompletedProcess =\
+            subprocess.run(['docker-compose', 'up',
+                            '--exit-code-from', 'job',
+                            '--abort-on-container-exit'],
+                           capture_output=True,
+                           timeout=timeout)
+        _ = subprocess.run(['docker-compose', 'down'],
+                           capture_output=True,
+                           timeout=120)
+    finally:
+        os.chdir(cwd)
+
+    print(f'# Executed ({test.returncode})')
+
+    return test.returncode,\
+        test.stdout.decode("utf-8"),\
+        test.stderr.decode("utf-8")
+
+
+def delete(test_name: str, quiet: bool = False) -> None:
+    """Deletes a test directory created by 'crete()'.
+    """
+    print(f'# Deleting the test...')
+
+    test_path: str = get_test_path(test_name)
+    if os.path.exists(test_path):
+        shutil.rmtree(test_path)
+
+    print('# Deleted')