Update README with usage examples

Also fix typo + cleanup YAML

.github/workflows/ci.yml

@@ -22,14 +22,16 @@ jobs:
       - name: Checkout branch
         uses: actions/checkout@v4
 
-      - uses: ./actions/setup
+      - uses: ./setup
         with:
           toolchain: ${{ matrix.toolchain }}
 
       - name: Check formatting
+        working-directory: test-runner
         run: cargo fmt --all --verbose -- --check
 
       - name: Run clippy
+        working-directory: test-runner
         run: cargo 3ds clippy --color=always --verbose --all-targets
 
   test:
@@ -47,8 +49,6 @@ jobs:
       volumes:
         # So the test action can `docker run` the runner:
         - '/var/run/docker.sock:/var/run/docker.sock'
-        # So the built test artifacts end up on the host, not just inside the action container
-        - '/tmp:/tmp'
     steps:
       - name: Checkout branch
         uses: actions/checkout@v4
@@ -63,18 +63,18 @@ jobs:
           working-directory: test-runner
           args: -- -v
 
-      - name: Build and run doc tests
+      # TODO(#4): run these suckers
-        # Let's still run doc tests even if lib/integration tests fail:
+      # - name: Build and run doc tests
-        if: ${{ !cancelled() }}
+      #   # Let's still run doc tests even if lib/integration tests fail:
-        env:
+      #   if: ${{ !cancelled() }}
-          # This ensures the citra logs and video output gets put in a directory
+      #   env:
-          # where we can upload as artifacts
+      #     # This ensures the citra logs and video output gets put in a directory
-          RUSTDOCFLAGS: " --persist-doctests target/armv6k-nintendo-3ds/debug/doctests"
+      #     # where we can upload as artifacts
-        uses: ./run-tests
+      #     RUSTDOCFLAGS: " --persist-doctests ${{ env.GITHUB_WORKSPACE }}/target/armv6k-nintendo-3ds/debug/doctests"
-        with:
+      #   uses: ./run-tests
-          working-directory: test-runner
+      #   with:
-          # TODO(#4): run them suckers
+      #     working-directory: test-runner
-          args: --doc --no-run -- -v
+      #     args: --doc -- -v
 
       - name: Upload citra logs and capture videos
         uses: actions/upload-artifact@v3

README.md

@@ -6,13 +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
+  * `setup`: action for setting up the Rust 3DS toolchain in workflows
-    workflows
+  * `run-tests`: action for running test executables with Citra in workflows
-  * `.github/actions/citra`: action for running test executables with Citra in
-    workflows
 
 ## Usage
 
-<!-- TODO -->
+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/action.yml

@@ -30,7 +30,7 @@ runs:
     - name: Build test-runner image
       uses: docker/build-push-action@v4
       with:
-        contest: ${{ github.action_path }}
+        context: ${{ github.action_path }}
         tags: ${{ inputs.runner-image }}:latest
         push: false
         load: true
@@ -49,9 +49,13 @@ runs:
         cd ${{ inputs.working-directory }}
         export CARGO_TARGET_ARMV6K_NINTENDO_3DS_RUNNER="
             docker run --rm
-                -v /tmp:/tmp
+                -v ${{ runner.temp }}:${{ runner.temp }}
                 -v ${{ github.workspace }}/target:/app/target
-                -v ${GITHUB_WORKSPACE}:${GITHUB_WORKSPACE}
+                -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 }}

setup/action.yml

@@ -17,13 +17,13 @@ runs:
       with:
         components: clippy, rustfmt, rust-src
         toolchain: ${{ inputs.toolchain }}
-        cache: "false" # We set up our own cache manually in the next step
+        cache: false # We set up our own cache manually in the next step
         rustflags: ""
 
     - name: Set up Rust cache
       uses: Swatinem/rust-cache@v2
       with:
-        cache-on-failure: "true"
+        cache-on-failure: true
 
     - name: Install build tools for host
       shell: bash