# Walkthroughs

> Two complete examples: one long-running machine, and testing a fleet.

## Walkthrough 1: one long-running machine

Here one machine stays up all day while you change a Windows application. After each change you copy in the new build, start it, drive it, take screenshots and check the results, without rebuilding an image or restarting Windows.

1. **Launch the machine once.** Use the one-service Compose file from [Deploying a single machine](/docs/by-hand/deploying/#deploying-a-single-machine), with no main process, so that the machine keeps running:

   ```sh
   endia compose up --wait
   shots=$(mktemp -d)   # screenshots stay outside the project
   ```

2. **Deploy the build.** Build the application on your side, create its folder in the machine, then copy it in:

   ```sh
   endia exec orders-dev-dev-1 cmd /c "if not exist C:\app mkdir C:\app"
   endia cp ./publish/. orders-dev-dev-1:C:/app
   ```

3. **Run it on the desktop** and keep its process ID:

   ```sh
   pid=$(endia desktop launch orders-dev-dev-1 C:\\app\\Orders.exe | jq -r .processId)
   ```

4. **Interact with it.** Read the window's elements, then drive them:

   ```sh
   endia desktop inspect orders-dev-dev-1 "$pid" > ui.json
   endia desktop set-value orders-dev-dev-1 "$pid" "Window[Orders]/Edit#CustomerName" "Ada"
   endia desktop invoke orders-dev-dev-1 "$pid" "Window[Orders]/Button[Save]"
   ```

5. **Take screenshots** of the state you want to keep:

   ```sh
   endia desktop screenshot --pid "$pid" orders-dev-dev-1 > "$shots/after-save.png"
   ```

6. **Validate.** Run the test suite inside the machine and fetch its results, or call the application through its published port:

   ```sh
   endia exec orders-dev-dev-1 C:\\app\\tests\\run-tests.cmd
   endia cp orders-dev-dev-1:C:/app/tests/results ./results
   curl http://127.0.0.1:18080/health
   ```

7. **Fix and redeploy.** Stop the running application, change the code, and start again from step 2:

   ```sh
   endia process stop orders-dev-dev-1 "$pid"
   ```

When you finish, `endia compose down` removes the machine. If the machine gets into a bad state, `endia compose down` followed by `endia compose up --wait` gives a fresh one from the image in a few minutes.

## Walkthrough 2: testing a fleet

Here a test checks several machines working as one system. It builds an image with the software under test and its Windows settings, and starts several machines from that image at once. It then tests them together, collects their results and shuts everything down.

1. **Build the layer.** Build the image from `app.Endiafile` in [Built images](/docs/by-hand/building-images/#built-images). That recipe copies the application in, opens its firewall port, adds a hosts entry and sets a registry value:

   ```sh
   endia build -t lab/app:dev -f app.Endiafile .
   ```

2. **Describe the fleet.** Use the Compose file from [Deploying many machines](/docs/by-hand/deploying/#deploying-many-machines): one server with a health check and three clients that wait for it, on one private network.

3. **Launch the fleet.** Give each run its own project name, so that runs side by side do not collide. A trap makes sure the fleet is always removed:

   ```sh
   set -e
   project="orders-test-$$"
   trap 'endia compose -p "$project" down -v' EXIT
   endia compose -p "$project" up --wait --wait-timeout 900   # seconds: 15 minutes
   ```

   `up --wait` exits with 1 if a machine becomes unhealthy, its main process exits, or the time-out passes.

4. **Run the coordinated test.** Start the clients' work and wait for each:

   ```sh
   pids=()
   for i in 1 2 3; do
     endia compose -p "$project" exec -T --index "$i" client C:\\app\\Client.exe --orders 100 &
     pids+=($!)
   done
   status=0
   for pid in "${pids[@]}"; do
     wait "$pid" || status=1
   done
   exit $status
   ```

   `-T` attaches no terminal, which suits a script. Each `exec` exits with the client program's exit code, and `wait` with a process ID returns that code. A bare `wait` returns 0 whatever the programs did, so the script names each process ID.

5. **Capture the results.** Copy each machine's result files out, and keep the server's output:

   ```sh
   for i in 1 2 3; do
     endia compose -p "$project" cp --index "$i" client:C:/app/results "./results/client-$i"
   done
   endia compose -p "$project" cp server:C:/app/logs ./results/server-logs
   endia compose -p "$project" logs server > ./results/server.log
   ```

6. **Shut the fleet down.** The shell's `trap` line from step 3 runs `endia compose -p "$project" down -v` when the script ends, whether it passed or failed. That removes the machines, the private network and the named volumes.
