Gua Tester Actions

Important

From 2026-10-01, all users must update gua-tester to v3.2 because Gua has moved to gua-project/gua (and this action repository to gua-project/gua-tester). Update every action and reusable workflow reference to gua-project/gua-tester/...@v3.2 as shown below. This requirement is for gua-tester, not the Gua library version.

English | 日本語

GitHub Actions building blocks for running Gua UI tests in Godot 4.7 and Unity 6 projects.

This repository is not a sample game repository. It provides a Godot composite action, a Unity reusable workflow, and engine-neutral visual report tooling for consumer repositories.

Gua v1.2.0: choose a package that supports remote tests

Gua's library version and this Actions repository's revision are separate. Pin the addon/UPM and Gua.Testing.Godot or Gua.Testing.Unity to 1.2.0 together. Pin an action/workflow revision containing this integration too: selecting a new Gua library does not add new checks or inputs to an older action tag.

Purpose	Native setting value	Remote access
Ordinary user-facing release, without remote control	shipping	No remote implementation
Development / Editor testing	development	Explicitly enabled; Debug inspection ceiling
Testing a Release executable	qa	Explicitly enabled; Debug inspection ceiling
AI-player-enabled user-facing release	ai-player	Explicitly enabled; fixed Player ceiling

Debug/Release describes how code is built; the purpose above is a separate choice. The public v1.2.0 test SDK addon and UPM are development builds with remote access explicitly enabled, including the binaries named Release. They are not ordinary release packages without remote control. Native source builds require GUA_ENABLE_REMOTE_AUTOMATION=ON with the appropriate GUA_DISTRIBUTION_FLAVOR. Changing a game-side #if, environment variable, or Player profile cannot add remote code to a precompiled library. See the Gua build guide.

The all-in-one Godot action reads the actually loaded native build-info before running tests. An addon without remote capability fails with an explanation, rather than waiting for a connection timeout. The source commit must match the expected native source. By default this is resolved from the release tag; an asset mirror can supply the original upstream SHA through gua-source-commit. This optional input never disables capability, source, or hash checks. A Player-limited addon remains Player-limited; this action does not elevate its profile. Test only information and operations exposed by the host. For Gua versions before 1.2.0, legacy installation is retained, but missing build-info is explicitly reported as unverified.

The link-only action does not launch Godot or verify the loaded native capability. Use the all-in-one action for that check, or inspect get_build_info() in the game. Both installers expose gua-tag, gua-source-commit (v1.2.0+), and gua-asset-sha256; archive digests are checked when provided by GitHub.

The Unity workflow's gua-build-variant input defaults to development, matching the public test SDK. Choose qa or ai-player only with a package compiled for that purpose. The workflow checks the selected native files against their inspection records (manifest), source commit, and hashes, then passes the purpose to Unity's build command. Unity's prebuild guard additionally checks the actual native and managed capabilities. A manifest may describe files from the original combined archive; it does not mean every component or license must exist in each package's native directory. No remote test can operate an ordinary shipping build; test the absence of remote access separately.

Godot 4.7

The Godot action:

• Downloads the official Godot build matching the Windows x64, Linux x64, or macOS runner
• Downloads the latest stable gua-v* release containing a matching Godot addon asset from gua-project/gua
• Extracts the released addons/gua package, including the matching desktop GDExtension
• Copies the released addon into the consumer project's game/addons/gua
• Sets GODOT_EXECUTABLE and runs dotnet test

Gua.Testing.Godot is a .NET test host, but the launched Godot project can be a GDScript project. As long as the game starts the Gua addon bridge at ws://127.0.0.1:8765, external .NET tests can validate the live UI tree.

Minimal Godot Workflow

Place this in the consumer repository at .github/workflows/godot.yml.

name: Godot Gua UI Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  godot:
    runs-on: ubuntu-22.04 # windows-latest and macOS runners are also supported
    steps:
      - name: Check out game repository
        uses: actions/checkout@v4

      - name: Run Godot Gua tests
        uses: gua-project/gua-tester/godot@v3.2
        with:
          project-path: game
          test-project: tests/GuaTester.Tests.csproj
          godot-version: "4.7"
          godot-status: stable
          # Pin the addon to the test SDK version for reproducible tests.
          gua-plugin-tag: gua-v1.2.0

Pin production workflows to @v3.2. The root action was removed in v2; see the v2 migration section.

Godot Action Inputs

godot/action.yml is the all-in-one Godot action.

• project-path: Path to the Godot project. Default: game
• test-project: Path to the .NET test .csproj that references Gua.Testing.Godot
• godot-version: For example, 4.7
• godot-status: For example, stable, rc1, or dev1
• godot-executable-suffix: Legacy Windows-only override. Linux and macOS use their official archive names automatically
• dotnet-version: Default: 10.0.x
• gua-source-commit: Optional expected native source SHA (40 lowercase hex); empty resolves the release tag. For mirrored assets, specify the original Gua source commit.
• gua-repository: Default: gua-project/gua
• gua-plugin-tag: Specific Gua release tag, such as gua-v1.2.0. By default, the latest stable gua-v* release containing a matching addon asset is used. Legacy godot-plugin-* releases remain as a fallback.
• gua-plugin-asset-pattern: Default: gua-godot-addon-*.zip. The default also accepts the legacy Windows addon name for older Gua tags.
• configuration: Default: Release
• test-logger: Default: trx;LogFileName=godot.trx

Godot Component Actions

You can also use the smaller actions separately.

setup-godot

- uses: gua-project/gua-tester/setup-godot@v3.2
  with:
    godot-version: "4.7"
    godot-status: stable

This sets the GODOT_EXECUTABLE environment variable.

link-gua-gdscript-addon

- uses: gua-project/gua-tester/link-gua-gdscript-addon@v3.2
  with:
    project-path: game
    # Pin the addon to the test SDK version.
    gua-plugin-tag: gua-v1.2.0

This downloads the released gua-project/gua Godot plugin asset and copies its addons/gua directory to game/addons/gua.

Unity 6 desktop Mono

Unity uses a reusable workflow to build a Mono Player and exercise it through external NUnit tests on the matching runner. WindowsX64 remains the default; LinuxX64, MacOSX64, MacOSArm64, and MacOSUniversal are also supported.

name: Unity Gua UI Tests

on:
  pull_request:
  push:
    branches: [main]

jobs:
  unity:
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    uses: gua-project/gua-tester/.github/workflows/unity.yml@v3.2
    with:
      project-path: game
      scene-path: Assets/Scenes/Title.unity
      test-project: tests/GuaTester.Unity.Tests.csproj
      artifact-key: game
      platform: LinuxX64
      unity-version: auto
      gua-tag: gua-v1.2.0
    secrets:
      UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
      UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
      UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
      UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}

Professional licenses can pass UNITY_SERIAL instead of UNITY_LICENSE. Fork pull requests do not receive Actions secrets, so the calling workflow must skip the Unity job for untrusted forks. Do not use pull_request_target to run untrusted game code with Unity credentials. Gua v1.0.4 and later include the cross-platform native assets required by the Linux and macOS platform values.

Required inputs are project-path, scene-path, test-project, and a unique artifact-key for each reusable workflow invocation. Optional inputs are platform (WindowsX64), unity-version (auto), gua-repository (gua-project/gua), gua-tag, gua-build-variant (development; also qa or ai-player with matching packages), dotnet-version (10.0.x), configuration (Release), test-logger (trx;LogFileName=unity.trx), and artifact-path (artifacts/gua). checkout-repository and checkout-ref are advanced overrides used when the project and tests come from another repository. Use a matrix value or another stable caller-specific value for artifact-key when the reusable workflow is invoked more than once in the same workflow run.

The workflow installs the released com.link1345.gua-*.tgz as an embedded UPM package, builds the requested rendered Mono Player, and sets both GUA_UNITY_PLAYER and GUA_UNITY_ARTIFACT_PLAYER for dotnet test. Unity build logs, the Player, TRX results, and Gua diagnostic/visual artifacts are retained as workflow artifacts. Windows uses a fixed 1920x1080 display and Linux uses Xvfb. Unity 6000.5+ and Mono are required; IL2CPP, IMGUI, and EditorWindow automation are outside this workflow scope.

Keep the UPM release selected by gua-tag aligned with the Gua.Testing.Unity NuGet version used by the test project.

Visual reports

Gua.Testing.Visual writes comparison.json and the available PNG files for each comparison. A successful comparison includes its current actual.png, so a report with no visual differences can still show the current screen. The visual-report action converts that raw data into a public report.json, combines it with the bundled Astro-built static viewer, and uploads either a Pages artifact or a regular workflow artifact. Consumers do not install Astro, Node.js, or npm dependencies.

- name: Run Godot Gua tests
  id: gua-tests
  uses: gua-project/gua-tester/godot@v3.2
  with:
    project-path: game
    test-project: tests/GuaTester.Tests.csproj

- name: Prepare latest main visual report
  id: visual-report
  if: always() && github.event_name != 'pull_request'
  uses: gua-project/gua-tester/visual-report@v3.2
  with:
    artifact-path: artifacts/gua
    test-outcome: ${{ steps.gua-tests.outcome }}
    upload-target: pages

The action accepts:

• artifact-path: Visual artifact directory. Default: artifacts/gua
• test-outcome: Required test step outcome: success, failure, or cancelled
• include-comparisons-on-success: Also include failed comparison artifacts while keeping a successful report status. Matched current screens are always included. Default: false
• upload-target: pages or workflow. Default: pages
• pages-artifact-name: Pages artifact name. Default: github-pages
• workflow-artifact-name: Workflow artifact name. Default: gua-visual-report
• retention-days: Artifact retention period. Default: 7

It outputs comparison-count and artifact-id. Deployment remains a separate job owned by the consumer workflow, where pages: write, id-token: write, and the github-pages environment can be reviewed explicitly. Configure the repository's Pages source as GitHub Actions before the first deployment. See the complete examples/godot-ci.yml workflow. If pages-artifact-name is customized, pass the same value as artifact_name to actions/deploy-pages.

Use upload-target: pages for main or manually dispatched runs. On failed pull requests use upload-target: workflow; the downloaded artifact already contains the viewer and normalized report. Because the viewer loads report.json, serve the extracted directory over local HTTP rather than opening index.html through file:// (for example, python -m http.server). A successful main run publishes matched current screens but filters out failure artifacts unless include-comparisons-on-success is enabled, so a previous failure is not presented as current.

Warning

Screenshots can contain rendered secrets or personal information. Review the captured content before enabling Pages, especially for public repositories.

Godot Addon Linking

Git submodules work at repository granularity, so they cannot directly link only the subdirectory https://github.com/gua-project/gua/tree/main/examples/godot-gdscript/addons/gua.

For that reason, these actions download the matching Godot addon asset from a gua-v* release in gua-project/gua and copy only the released addons/gua directory into the consumer Godot project. Legacy godot-plugin-* releases are supported as a fallback. The release asset already includes the built Windows GDExtension DLLs, so the consumer workflow does not build the addon from source.

Godot Consumer Repository Requirements

• A Godot GDScript project
• Game-side code that starts the Gua bridge through the Gua addon
• A .NET test project that references Gua.Testing.Godot

Example test project:

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="Gua.Testing.Godot" Version="1.2.0" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
    <PackageReference Include="NUnit" Version="4.3.2" />
    <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
  </ItemGroup>

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <IsPackable>false</IsPackable>
  </PropertyGroup>
</Project>