Test and debug a custom application

Last update: June 27, 2024

CREATED FOR:

  • Developer

Run unit tests for a custom application

Install Docker Desktop on your machine. To test a custom worker, run the following command at the root of the application:

$ aio app test

This command runs a custom unit test framework for Asset Compute application actions in the project as described below. It is hooked up through a configuration in the package.json file. It is also possible to have JavaScript unit tests such as Jest. The aio app test runs both.

The aio-cli-plugin-asset-compute plugin is embedded as a development dependency in the custom application app so that it doesn’t need to be installed on build/test systems.

Application unit test framework

The Asset Compute application unit test framework lets you test applications without writing any code. It relies on the source to rendition file principle of applications. A certain file and folder structure has to be set up to define test cases with test source files, optional parameters, expected renditions and custom validation scripts. By default, the renditions are compared for byte equality. Furthermore, external HTTP services can be easily mocked using simple JSON files.

Add tests

Tests are expected inside the test folder at the root level of the project. The test cases for each application should be in the path test/asset-compute/<worker-name>, with one folder for each test case:

action/
manifest.yml
package.json
...
test/
  asset-compute/
    <worker-name>/
        <testcase1>/
            file.jpg
            params.json
            rendition.png
        <testcase2>/
            file.jpg
            params.json
            rendition.gif
            validate
        <testcase3>/
            file.jpg
            params.json
            rendition.png
            mock-adobe.com.json
            mock-console.adobe.io.json

Have a look at example custom applications for some examples. Below is a detailed reference.

Test output

The build directory at the root of the Adobe Developer App Builder app houses the detailed test results and logs of the custom application. These details are also displayed in the output of the aio app test command.

Mock external services

You can simulate external service calls within your actions by creating mock-<HOST_NAME>.json files for your test scenarios, with HOST_NAME being the specific host you intend to imitate. An example use case is an application that makes a separate call to S3. The new test structure would look like this:

test/
  asset-compute/
    <worker-name>/
      <testcase3>/
        file.jpg
        params.json
        rendition.png
        mock-<HOST_NAME1>.json
        mock-<HOST_NAME2>.json

The mock file is a JSON formatted http response. For more information, see this documentation. If there are multiple host names to mock, define multiple mock-<mocked-host>.json files. Below is a sample mock file for google.com named mock-google.com.json:

[{
    "httpRequest": {
        "path": "/images/hello.txt"
        "method": "GET"
    },
    "httpResponse": {
        "statusCode": 200,
        "body": {
          "message": "hello world!"
        }
    }
}]

The example worker-animal-pictures contains a mock file for the Wikimedia service that it interacts with.

Share files across test cases

Adobe recommends using relative symlinks if you share file.*, params.json or validate scripts across multiple tests. They are supported with Git. Make sure to give your shared files a unique name, since you might have different ones. In the example below the tests are mixing and matching a few shared files, and their own:

tests/
    file-one.jpg
    params-resize.json
    params-crop.json
    validate-image-compare

    jpg-png-resize/
        file.jpg    - symlink: ../file-one.jpg
        params.json - symlink: ../params-resize.json
        rendition.png
        validate    - symlink: ../validate-image-compare

    jpg2-png-crop/
        file.jpg
        params.json - symlink: ../params-crop.json
        rendition.gif
        validate    - symlink: ../validate-image-compare

    jpg-gif-crop/
        file.jpg    - symlink: ../file-one.jpg
        params.json - symlink: ../params-crop.json
        rendition.gif
        validate

Test expected errors

Error tests cases should not contain an expected rendition.* file and should define the expected errorReason inside the params.json file.

NOTE
If a test case does not contain an expected rendition.* file and does not define the expected errorReason inside the params.json file, it is assumed to be an error case with any errorReason.

Error Test Case Structure:

<error_test_case>/
    file.jpg
    params.json

Parameter file with error reason:

{
    "errorReason": "SourceUnsupported",
    // ... other params
}

See a complete list and description of Asset Compute error reasons.