The retool-onpremise repository can be configured to run the application tests in your continuous integration environment. You should be on v2.86 or later to use Testing in CI.

Setup

Clone the retool-onpremise repository. Edit the Dockerfile, picking the specific version of Retool you run in production.

Next, clone the repository containing your Retool applications into the retool folder at the top level of the retool-onpremise repository.

The test runner assumes that your Retool applications are laid out in the following structure:

retool
├── .git
├── apps
│   └── Example.yml
└── config
    ├── settings
        │   └── organization.yml
            └── users
                    └── admin.yml

The test runner requires that the retool folder be a valid Git repository.

You may also need to change the permissions on the retool folder to ensure that Docker can access the folder. The easiest way to do this is via chmod

chmod -R 777 retool

Copy the docker.env.testing file to docker.env and update it with any environment variables you need.

Start Retool using Docker Compose. Make sure to use the testing profile to start the test runner.

docker-compose --profile testing up -d

Once that's started, the tests need to be generated and run (eventually we will bundle up the following commands into 1 command):

cd testing/
npm install && set -euf -o pipefail && mkdir ms-playwright && node ./generate.js

Once localhost:3000 running the instance of Retool is spun up, run the following:

cd testing/ms-playwright/
npx playwright install && npx playwright test

Here's the output of a successful test run:

  ✓  [chromium] › example.spec.ts:67:1 › Example (8s)
  ✓  [chromium] › example-2.spec.ts:49:1 › Example 2 (5s)

2 passed (13s)

Providers

GitHub Actions

We've encoded the steps detailed above into a YAML (see below) for Github Actions that can be placed in your Github repository (in ./.github/workflows/) to run Retool tests in CI. Note that the YAMLs are slightly different depending on whether you're using Source Control or git syncing.

For Source Control (recommended)

To run CI on Source Control, ensure that you are using v2.86 or later of Retool! With Source Control, your tests will run automatically whenever you open a PR to update an app, so you can confidently update and maintain your Retool applications.

# Source Control GitHub Actions YAML

# Run Retool Tests in CI (Source Control)

name: Retool App Tests
on:
  # run on opening a PR
  pull_request:
    types: [opened, reopened]

  # run on push
  push:

  # allows CI runs of tests to be manually triggered
  # workflow_dispatch:

  # runs suite of tests regularly
  # schedule:
  #   - cron:  '*/30 * * * *'
jobs:
  retool-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout tryretool/retool-onpremise
        uses: actions/[email protected]
        with:
          repository: "tryretool/retool-onpremise"
      - name: "Use a specific release of Retool"
        run: sed -i 's/backend:X.Y.Z/backend:2.86.10/g' Dockerfile
      - name: Checkout Retool apps and configuration
        uses: actions/[email protected]
        with:
          path: "retool-source-control-repo"
      - run: chmod -R 777 retool-source-control-repo
      - name: Use Node.js
        uses: actions/[email protected]
        with:
          node-version: "12.x"
      - name: Set up environment variables to bootstrap Retool instance for tests
        run: cp docker.env.testing docker.env && echo "BOOTSTRAP_FROM_SOURCE=1" >> docker.env
      - name: Start Retool in Docker Compose
        run: BOOTSTRAP_SOURCE=./retool-source-control-repo docker-compose --profile testing up -d
      - name: Setup
        run: npm install && set -euf -o pipefail && mkdir ms-playwright && USING_SOURCE_CONTROL=1 [email protected] RETOOL_TEST_PASSWORD=password node ./generate.js
        working-directory: ./testing
      - name: Wait for localhost
        uses: nev7n/[email protected]
        with:
          url: "http://localhost:3000/"
          responseCode: 200
          timeout: 600000
          interval: 500
      - name: Run Tests
        run: npx playwright install && npx playwright test
        working-directory: ./testing/ms-playwright
      # optional if you want to view artifacts upon test failures
      - uses: actions/[email protected]
        if: ${{ success() || failure() }}
        with:
          name: Recordings
          path: testing/ms-playwright/test-results/

For Git Syncing

# Git Syncing Github Actions YAML

# Run Retool Tests in CI (Git Syncing)

name: Retool App Tests
on:
  # run on push
  push:

  # allows CI runs of tests to be manually triggered
  # workflow_dispatch:

  # runs suite of tests regularly
  # schedule:
  #   - cron:  '*/30 * * * *'
jobs:
  retool-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout tryretool/retool-onpremise
        uses: actions/[email protected]
        with:
          repository: "tryretool/retool-onpremise"
      - name: "Use a specific release of Retool"
        run: sed -i 's/backend:X.Y.Z/backend:2.86.10/g' Dockerfile
      - name: Checkout tryretool/adminprotected
        uses: actions/[email protected]
        with:
          path: "retool/apps"
      - name: Move Retool configuration into the correct spot
        run: mv retool/apps/.retool/config retool/config
      - run: git init
        working-directory: retool
      - run: chmod -R 777 retool
      - name: Use Node.js
        uses: actions/[email protected]
        with:
          node-version: "12.x"
      - run: cp docker.env.testing docker.env
      - name: Start Retool in Docker Compose
        run: BOOTSTRAP_SOURCE=./retool docker-compose --profile testing up -d
      - name: Setup
        run: npm install && set -euf -o pipefail && mkdir ms-playwright && node ./generate.js
        working-directory: ./testing
      - name: Wait for localhost
        uses: nev7n/[email protected]
        with:
          url: "http://localhost:3000/"
          responseCode: 200
          timeout: 600000
          interval: 500
      - name: Run Tests
        run: npx playwright install && npx playwright test
        working-directory: ./testing/ms-playwright
      # optional if you want to view artifacts upon test failures
      - uses: actions/[email protected]
        if: ${{ success() || failure() }}
        with:
          name: Recordings
          path: testing/ms-playwright/test-results/

Instance Configuration

The Retool CI instance is configured via YAML files in the config directory. Organizations, users, and resources can be created using these files. Note: this is currently only support for git syncing, support for source control is upcoming!

Organization

Organization settings are defined in config/settings/organization.yml. The only required field is the organization name.

name: example.com

Users

Each user gets is defined by a YAML file in the config/users folder. The sid field can be any string. The password is stored bcrypt-hashed value. The default value, included below, is password.

# config/users/admin.yml

email: [email protected]
firstName: Retool
hashedPassword: $2a$12$kTIo.9CtypGP.3jXfqBLXevG.ef/F7OEePj9oBqNfTzyvLlmlpUBS
lastName: Test
sid: user_4e5fb6e0b3cd4e39b518f09a3480e6ca
userName: retool-test

Resources

Currently not supported -- but email [email protected] if you're interested.