Proof on pull requests

Every pull request built on a phone, the flows it changed run and recorded, and a link your reviewers open to try the build.

Add the workflow

Make an API key on the Keys page and add it to the repository as the secret NOMAC_API_KEY. Then add this workflow:

.github/workflows/proof.yml

name: Proof
on:
  pull_request:
    types: [opened, synchronize, reopened, closed]
permissions:
  contents: read
  pull-requests: write
concurrency:
  group: proof-${{ github.event.pull_request.number }}
  cancel-in-progress: true
jobs:
  proof:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        if: github.event.action != 'closed'
      - uses: NoMac-app/actions/proof@v1
        with:
          api-key: ${{ secrets.NOMAC_API_KEY }}

It runs on ubuntu-latest: the phone builds the app, so the runner only sends requests. A push while a run goes cancels it, and its phone stops.

Write a flow

A flow is what a reviewer would do to check a change, one step a line, in a file in .nomac/flows. # paths: names the files it covers, so a pull request runs only the flows its changes touch.

.nomac/flows/checkout.flow

# Add an item, check out.
# paths: Sources/Cart/**, Sources/Shop/**
launch
tap #add-Espresso
tap "Cart"
wait "1 item"
tap #checkout
wait "Order placed"

launch: Starts the app fresh, with launch arguments if you add them (launch -Demo YES).
open: Opens a link or a deep link.
look: Puts the screen, as text, in the comment.
anything else: A step of phone_ui_act: tap, fill, type, scroll, swipe, wait, gone, back. The first that fails ends the flow.

A flow without # paths: runs on every pull request, and run: all runs them all. With no flow, the app is built and launched, and its first screen recorded.

Open a pull request

The pull request's commit goes into the repository's own workspace on NoMac, kept between runs, so Xcode rebuilds only what changed. One comment on the pull request, edited on every push, shows:

the build, with its errors as file:line when it fails;
each flow's result, with a recording that opens at that flow, kept 7 days;
the last screen as text, and what the run cost;
a link that opens this build on a phone, with no sign-in.

The phone link

The link starts a phone only when someone opens it: it restores the build the run saved, opens the app, and gives the viewer control. Each push makes a new link that works for 7 days, but all of a pull request's links share one budget: at most 3 phones in all, one at a time, each stopping after 15 minutes or 5 minutes without a tap or a key. At $0.90 an hour that is at most 67.5¢ for the pull request, and the comment says so. phone-link-phones and phone-link-minutes change the bounds. Closing the pull request deletes the build, and revoking the API key ends its links, so they start no more phones.

A phone the link starts counts against the account's phones at once. While all are in use, the page waits for one.

What a run costs

A phone's price, 1.5¢ a minute ($0.90 an hour), billed per minute from the phone's start to its stop. A run of 3 minutes costs 4.5¢. Saving the build for the phone link adds about a minute. max-cost caps a run (1 dollar by default) and max-minutes its length (30).

Public repositories and forks

A public repository's comment has no link that opens without sign-in: the recordings are on your NoMac dashboard, and there is no phone link. public-links: true puts them in anyway.
A pull request from a fork gets no secrets, so it is skipped. Building forks needs pull_request_target and forks: true, and then anyone who opens a pull request spends your credit.

Inputs

path, scheme: The project's folder (. by default) and its scheme, when it has several.
configuration, env: Debug or Release, and the app's launch variables, as "API_URL=https://staging.example".
flows, flow, run: A folder of .flow files or one file, steps inline instead, and changed or all.
device: iphone, ipad or iphone-pro-max.
phone-link: auto (on in private repositories), on or off.
max-cost, max-minutes, wait-minutes: A run's spend cap in dollars, its longest time, and how long it waits while the account's phones are all in use.

The Action, a sample app and its flows are in NoMac-app/actions.