Merge pull request #8 from ian-h-chamberlain/fix/refactor-simplify-ac…

…tion

.github/workflows/ci.yml

@@ -9,10 +9,6 @@ on:
       - main
   workflow_dispatch:
 
-env:
-  # actions-rust-lang/setup-rust-toolchain sets some default RUSTFLAGS, which we don't want to use
-  RUSTFLAGS: ""
-
 jobs:
   lint:
     strategy:
@@ -24,18 +20,19 @@ jobs:
     container: devkitpro/devkitarm
     steps:
       - name: Checkout branch
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
-      - uses: ./.github/actions/setup
+      - uses: ./setup
         with:
           toolchain: ${{ matrix.toolchain }}
 
       - name: Check formatting
+        working-directory: test-runner
         run: cargo fmt --all --verbose -- --check
 
       - name: Run clippy
-        # We have to build the test crate here since it's not included in build-std by default
-        run: cargo 3ds clippy -Zbuild-std=std,test --color=always --verbose --all-targets
+        working-directory: test-runner
+        run: cargo 3ds clippy --color=always --verbose --all-targets
 
   test:
     strategy:
@@ -47,38 +44,44 @@ jobs:
 
     continue-on-error: ${{ matrix.toolchain == 'nightly' }}
     runs-on: ubuntu-latest
-    container: devkitpro/devkitarm
+    container:
+      image: devkitpro/devkitarm
+      volumes:
+        # So the test action can `docker run` the runner:
+        - '/var/run/docker.sock:/var/run/docker.sock'
     steps:
       - name: Checkout branch
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
-      - uses: ./.github/actions/setup
+      - uses: ./setup
         with:
           toolchain: ${{ matrix.toolchain }}
 
-      - name: Build lib tests
-        run: cargo 3ds test --no-run --lib
-
-      - name: Build integration tests
-        run: cargo 3ds test --no-run --test integration
-
-      - name: Build doc tests
-        run: cargo 3ds test --no-run --doc
-
-      - name: Run lib + integration tests
-        uses: ./.github/actions/citra
+      - name: Build and run tests (unit + integration)
+        uses: ./run-tests
         with:
-          executable:  ./target/armv6k-nintendo-3ds/debug/deps/*.elf
-
-      # TODO: run doc tests. We might be able to do something with e.g.
-      # cargo's "runner" configuration, but it seems we also need a test
-      # runtime and stuff for that to work.
+          working-directory: test-runner
+          args: -- -v
+
+      # TODO(#4): run these suckers
+      # - name: Build and run doc tests
+      #   # Let's still run doc tests even if lib/integration tests fail:
+      #   if: ${{ !cancelled() }}
+      #   env:
+      #     # This ensures the citra logs and video output gets put in a directory
+      #     # where we can upload as artifacts
+      #     RUSTDOCFLAGS: " --persist-doctests ${{ env.GITHUB_WORKSPACE }}/target/armv6k-nintendo-3ds/debug/doctests"
+      #   uses: ./run-tests
+      #   with:
+      #     working-directory: test-runner
+      #     args: --doc -- -v
 
       - name: Upload citra logs and capture videos
         uses: actions/upload-artifact@v3
-        if: success() || failure()
+        # We always want to upload artifacts regardless of previous success/failure
+        if: ${{ !cancelled() }}
         with:
           name: citra-logs-${{ matrix.toolchain }}
           path: |
-            target/armv6k-nintendo-3ds/debug/deps/*.txt
-            target/armv6k-nintendo-3ds/debug/deps/*.webm
+            target/armv6k-nintendo-3ds/debug/**/*.txt
+            target/armv6k-nintendo-3ds/debug/**/*.webm

README.md

@@ -6,11 +6,60 @@ A set of tools for running automated Rust tests against Citra (3DS emulator).
 ## Components
 
 * `test-runner`: a Rust crate for writing tests for 3DS homebrew
-* `Dockerfile`: builds a container for running test executables with Citra.
 * GitHub Actions:
-  * `.github/actions/setup`: action for setting up the Rust 3DS toolchain in
-    workflows
-  * `.github/actions/citra`: action for running test executables with Citra in
-    workflows
+  * `setup`: action for setting up the Rust 3DS toolchain in workflows
+  * `run-tests`: action for running test executables with Citra in workflows
 
-<!-- TODO: usage section for github actions -->
+## Usage
+
+First the test runner to your crate:
+
+```sh
+cargo add --dev test-runner --git https://github.com/ian-h-chamberlain/test-runner-3ds
+```
+
+In `lib.rs` and any integration test files:
+
+```rs
+#![feature(custom_test_frameworks)]
+#![test_runner(test_runner::run_gdb)]
+```
+
+Then use the `setup` and `run-tests` actions in your github workflow. This
+example shows the default value for each of the inputs:
+
+```yml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: devkitpro/devkitarm
+      volumes:
+        # This is required so the test action can `docker run` the runner:
+        - '/var/run/docker.sock:/var/run/docker.sock'
+        # This is required so doctest artifacts are accessible to the action:
+        - '/tmp:/tmp'
+
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v4
+
+      - name: Setup Rust3DS toolchain
+        uses: ian-h-chamberlain/test-runner-3ds/setup@v1
+        with:
+          # Optionally use a more specific nightly toolchain here if desired
+          toolchain: nightly
+
+      - name: Build and run tests
+        uses: ian-h-chamberlain/test-runner-3ds/run-tests@v1
+        with:
+          # Optionally add arguments to pass to `cargo 3ds test`
+          args: ''
+          # Optionally set the name of the built test-runner docker image
+          runner-image: test-runner-3ds
+          # Optionally change to a given directory before running tests. Note
+          # that this should use the environment variable ${GITHUB_WORKSPACE}
+          # rather than ${{ github.workspace }} to avoid the issue described in
+          # https://github.com/actions/runner/issues/2058
+          working-directory: ${GITHUB_WORKSPACE}
+```

run-tests/Dockerfile

@@ -0,0 +1,54 @@
+FROM buildpack-deps:latest as builder
+
+WORKDIR /tmp
+COPY ./docker/download_citra.sh /usr/local/bin/download_citra
+RUN apt-get update -y && apt-get install -y jq
+
+ARG CITRA_CHANNEL=nightly
+ARG CITRA_RELEASE=1995
+RUN download_citra ${CITRA_CHANNEL} ${CITRA_RELEASE}
+
+FROM devkitpro/devkitarm:latest as devkitarm
+
+# For some reason, citra isn't always happy when you try to run it for the first time,
+# so we build a simple dummy program to force it to create its directory structure
+RUN cd /opt/devkitpro/examples/3ds/graphics/printing/hello-world && \
+    echo 'int main(int, char**) {}' > source/main.c && \
+    make && \
+    mv hello-world.3dsx /tmp/
+
+FROM ubuntu:latest
+
+RUN --mount=type=cache,sharing=locked,target=/var/cache/apt \
+    apt-get update -y && \
+    apt-get install -y \
+        libswscale5 \
+        libsdl2-2.0-0 \
+        libavformat58 \
+        libavfilter7 \
+        xvfb
+
+COPY --from=devkitarm /opt/devkitpro /opt/devkitpro
+# There's no way to copy ENV values from other stages properly:
+# https://github.com/moby/moby/issues/37345
+# Luckily in this case we know exactly what the values should be:
+ENV DEVKITPRO=/opt/devkitpro
+ENV DEVKITARM=${DEVKITPRO}/devkitARM
+ENV PATH=${DEVKITARM}/bin:${PATH}
+
+COPY --from=builder /tmp/citra.AppImage /usr/local/bin/citra
+COPY --from=devkitarm /tmp/hello-world.3dsx /tmp/
+# We run citra once before copying our config file, so it should create its
+# necessary directory structure and run once with defaults
+RUN xvfb-run citra --appimage-extract-and-run /tmp/hello-world.3dsx; \
+    rm -f /tmp/hello-world.3dsx
+# Initial run seems to miss this one directory so just make it manually
+RUN mkdir -p /root/.local/share/citra-emu/log
+
+COPY ./docker/sdl2-config.ini /root/.config/citra-emu/
+COPY ./docker/test-runner.gdb /app/
+COPY ./docker/entrypoint.sh /app/
+
+WORKDIR /app
+
+ENTRYPOINT [ "/app/entrypoint.sh" ]

run-tests/action.yml

@@ -0,0 +1,61 @@
+name: Cargo 3DS Test
+description: >
+  Run `cargo 3ds test` executables using Citra. Note that to use this action,
+  you must mount `/var/run/docker.sock:/var/run/docker.sock` and `/tmp:/tmp` into
+  the container so that the runner image can be built and doctest artifacts can
+  be found, respectively.
+
+inputs:
+  args:
+    description: Extra arguments to pass to `cargo 3ds test`
+    required: false
+    default: ''
+
+  runner-image:
+    description: The name of the container image to build for running tests in
+    required: false
+    default: test-runner-3ds
+
+  working-directory:
+    description: Change to this directory before running tests. Defaults to $GITHUB_WORKSPACE
+    required: false
+    default: ${GITHUB_WORKSPACE}
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Build test-runner image
+      uses: docker/build-push-action@v4
+      with:
+        context: ${{ github.action_path }}
+        tags: ${{ inputs.runner-image }}:latest
+        push: false
+        load: true
+
+    - name: Ensure docker is installed in the container
+      shell: bash
+      run: apt-get update -y && apt-get install docker.io -y
+
+    - name: Run cargo 3ds test
+      shell: bash
+      # Set a custom runner for `cargo test` commands to use.
+      # Use ${GITHUB_WORKSPACE} due to
+      # https://github.com/actions/runner/issues/2058, which also means
+      # we have to export this instead of using the env: key
+      run: |
+        cd ${{ inputs.working-directory }}
+        export CARGO_TARGET_ARMV6K_NINTENDO_3DS_RUNNER="
+            docker run --rm
+                -v ${{ runner.temp }}:${{ runner.temp }}
+                -v ${{ github.workspace }}/target:/app/target
+                -v ${{ github.workspace }}:${GITHUB_WORKSPACE}
+                ${{ inputs.runner-image }}:latest"
+        env
+        cargo 3ds -v test ${{ inputs.args }}
+      env:
+        # Ensure that doctests get built into a path which is mounted on the host
+        # as well as in this container (via the bind mount in the RUNNER command)
+        TMPDIR: ${{ runner.temp }}

docker/download_citra.sh → run-tests/docker/download_citra.sh

@@ -9,7 +9,7 @@ RELEASE_API="https://api.github.com/repos/citra-emu/citra-${CITRA_CHANNEL}/relea
 
 curl "${RELEASE_API}" |
     jq --raw-output '.assets[].browser_download_url' |
-    grep -E 'citra-linux-.*.tar.gz' |
+    grep -E 'citra-linux-.*[.]tar.gz' |
     xargs wget -O citra-linux.tar.gz
 
 tar --strip-components 1 -xvf citra-linux.tar.gz