Core concepts

East India runs Windows virtual machines the way Docker runs containers, for automated tests, development and build machines, and any other work that needs a clean Windows. One Windows PC with Hyper-V runs the East India service. You and your agent talk to the service with the endia command line, which takes Docker's commands and options wherever Docker has one.

Key terms

Commands reach into a machine through two programs that every image holds: a guest service, which runs programs and copies files, and a desktop helper, which controls the screen, keyboard and mouse in testuser's session.

Before you start

To connect to the service you need three things:

  1. A context file, <name>.eastindiacontext, which holds the service's address and a client certificate.
  2. Network access to the service. From a Docker sandbox on the PC, the service is at host.docker.internal:7443, and the sandbox's policy must allow localhost:7443.
  3. The endia command line for your platform; for Linux, endia-linux-x64.

Connecting an agent's sandbox shows how to set up all three. Then, in your environment:

Terminal
endia context import pc <name>.eastindiacontext
endia context use pc
endia version     # prints the command line's and the service's versions
endia images      # lists the images you can start machines from

The six steps

A test follows the same steps every time:

  1. Build an image with the application installed, or start from an image you built earlier, such as your tools layer, and copy the application in later.
  2. Start the machines with endia compose up --wait.
  3. Install or start the parts that the image does not already run.
  4. Act and check: call the application over the network, run programs in the machine, drive its desktop.
  5. Collect evidence: screenshots, files, logs, event-log entries.
  6. Remove the machines with endia compose down -v, whether the test passed or not.

A test can also tell the developer what its fleet is for, with a purpose, and how far its work has got, with counts it reports itself; the desktop app's Home page shows both. Purpose and progress shows the commands.

Give each run a project name of its own, so that runs side by side never touch each other's machines, and remove the fleet from a shell trap:

Terminal
set -euo pipefail
run="mytest-$(date -u +%Y%m%d-%H%M%S)"
trap 'endia compose -p "$run" down -v' EXIT
endia compose -p "$run" up --wait --wait-timeout 900

Machines are named <project>-<service>-<n>. In that run, the first machine of the client service is therefore $run-client-1. up builds a service's image from its build section when the image is missing. --no-build builds nothing, so a missing image fails with NOT_FOUND; --build builds every service that has build, even if its image exists.

Exit codes and errors

Every command exits with 0 on success, 1 on a failure, 125 when the command line itself was wrong (nothing was sent) and 130 after Ctrl+C. On a failure, standard error says why:

--format json turns any listing into JSON for a program to read.

Python and Node clients

A test written in Python can call the service through the endia package instead of running the command line:

Terminal
pip install endia
Python
from endia import EastIndiaClient

with EastIndiaClient.from_env() as client:
    for machine in client.machines.list():
        print(machine)

EastIndiaClient.from_env() connects as endia does, trying these in order:

  1. EASTINDIA_HOST and EASTINDIA_CERT_PATH, when they are set;
  2. the context that EASTINDIA_CONTEXT names;
  3. the current context, from EASTINDIA_CONFIG or ~/.eastindia.

The Python package needs Python 3.10 or later. For Node 20 and later, npm install endia gives the same client.