Tests branch update to upstream HEAD

.github/workflows/beta.yml

@@ -1,28 +1,29 @@
 name: Push beta branch
-on: 
+on:
   schedule:
     - cron: '0 0 * * 5'
   push:
     branches:
-      - 'master'
+      - master
   workflow_dispatch:
 jobs:
   push-beta:
+    if: github.repository == 'PathOfBuildingCommunity/PathOfBuilding'
     runs-on: ubuntu-22.04
     steps:
-            - name: Set line endings
-              run: git config --global core.autocrlf true
-            - name: Checkout
-              uses: actions/checkout@v3
-              with:
-                ref: 'dev'
-            - name: Configure bot user
-              run: |
-                git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
-                git config --global user.name "github-actions[bot]"
-            - name: Update manifest.xml
-              run: python3 update_manifest.py --quiet --in-place
-            - name: Push to beta branch
-              run: |
-                  git commit -am "Weekly beta release" --allow-empty --author="github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
-                  git push origin HEAD:beta --force
+      - name: Set line endings
+        run: git config --global core.autocrlf true
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: dev
+      - name: Configure bot user
+        run: |
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+      - name: Update manifest.xml
+        run: python3 update_manifest.py --quiet --in-place
+      - name: Push to beta branch
+        run: |
+          git commit -am "Weekly beta release" --allow-empty --author="github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>"
+          git push origin HEAD:beta --force

.github/workflows/builddocker.yml

@@ -0,0 +1,42 @@
+name: Build and publish busted tests docker image
+on:
+ workflow_dispatch:
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Generate docker image metadata
+        uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: |
+            ghcr.io/${{ github.repository_owner }}/busted-tests
+          labels: |
+            org.opencontainers.image.description=A docker image packaged with the correct verions of tools to run PathOfBuilding busted tests. Includes emmylua debugger files. Refer to https://github.com/${{ github.repository_owner }}/PathOfBuilding/blob/tests-rework/CONTRIBUTING.md#setting-up-a-development-environment for usage instructions.
+            org.opencontainers.image.licenses=https://opensource.org/licenses/MIT
+          tags: |
+            type=sha
+            type=raw,value=latest
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/buildtest.yml

@@ -0,0 +1,93 @@
+---
+name: Run Tests
+on:
+  pull_request:
+    branches:
+      - dev
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  run_build_diff:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout HEAD
+        uses: actions/checkout@v4
+      - name: Fetch Dev branch
+        id: get-dev-ref
+        run: |
+            git fetch --depth=1 origin dev
+            echo "devref=$(git rev-parse origin/dev)" >> $GITHUB_OUTPUT
+      - name: Download Dev branch cache
+        id: download-dev-ref-cache
+        uses: dawidd6/action-download-artifact@3ecf4024886f219d9290351234889bfb45d1b9da
+        with:
+          name: cache-devref-${{ steps.get-dev-ref.outputs.devref }}
+          path: /tmp/cache/
+          if_no_artifact_found: warn
+          search_artifacts: true
+      # Dev ref cache contains the build list and build xmls. Use that one to keep tests reproducible
+      - name: Update static builds list from cache
+        if: ${{ steps.download-dev-ref-cache.outputs.found_artifact == 'true' }}
+        run: cat /tmp/cache/builds.txt > spec/builds.txt
+      - name: Download latest build list
+        if: ${{ steps.download-dev-ref-cache.outputs.found_artifact == 'false' }}
+        id: download-build-list
+        uses: dawidd6/action-download-artifact@3ecf4024886f219d9290351234889bfb45d1b9da
+        with:
+          name: builds.txt
+          path: /tmp/latestbuildlist/
+          workflow: updatebuildlist.yml
+          if_no_artifact_found: warn
+          search_artifacts: true
+      - name: Update static builds list
+        if: ${{ steps.download-dev-ref-cache.outputs.found_artifact == 'false' && steps.download-build-list.outputs.found_artifact == 'true' }}
+        run: cat /tmp/latestbuildlist/builds.txt > spec/builds.txt
+      - name: Download latest build xmls
+        if: ${{ steps.download-dev-ref-cache.outputs.found_artifact == 'false' }}
+        uses: dawidd6/action-download-artifact@3ecf4024886f219d9290351234889bfb45d1b9da
+        with:
+          name: build-xmls
+          path: /tmp/cache/
+          if_no_artifact_found: warn
+          search_artifacts: true
+      - name: Calculate build xmls and differences between them
+        run: |
+            mkdir /tmp/cache || true # Make sure /tmp/cache exists. Ignore exit code
+            chmod -R 777 /tmp/cache && docker compose run -v '/tmp/cache/:/cache' -e 'CACHEDIR=/cache' busted-diff | tee /tmp/dockerlog
+      - name: Generate artefact
+        run: |
+          sed -n '/Runtime comparison for/,/Savefile Diff for/{/Savefile Diff for/!p;}' /tmp/dockerlog > /tmp/artefact
+          sed -n '/Savefile Diff for/, $p' /tmp/dockerlog >> /tmp/artefact
+          [ -s /tmp/artefact ] || rm /tmp/artefact
+      - name: Upload artefact
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-diff-output
+          path: /tmp/artefact
+      - name: Save used build list into cache
+        if: ${{ steps.download-dev-ref-cache.outputs.found_artifact == 'false' }}
+        run: cp spec/builds.txt /tmp/cache/
+      - name: Move xmls found in builds.txt to a new directory
+        if: ${{ steps.download-dev-ref-cache.outputs.found_artifact == 'false' && steps.download-build-list.outputs.found_artifact == 'true' }}
+        run: |
+          mkdir new-build-xmls
+          while IFS= read -r line; do
+              FILENAME="/tmp/cache/${line//[^a-zA-Z0-9]/}.xml"
+              if [ -f "$FILENAME" ]; then
+                  mv "$FILENAME" "./new-build-xmls/"
+              fi
+          done < "spec/builds.txt"
+      - name: Upload new build xmls
+        if: ${{ steps.download-dev-ref-cache.outputs.found_artifact == 'false' && steps.download-build-list.outputs.found_artifact == 'true' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-xmls
+          path: './new-build-xmls/*'
+      - name: Upload dev ref cache
+        if: ${{ steps.download-dev-ref-cache.outputs.found_artifact == 'false' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: cache-devref-${{ steps.get-dev-ref.outputs.devref }}
+          path: /tmp/cache/

.github/workflows/unittest.yml

@@ -0,0 +1,17 @@
+name: Run Unit Tests
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - dev
+  pull_request:
+    branches:
+      - dev
+jobs:
+  run_unit_tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Run busted tests
+        run: docker compose run --no-TTY busted-tests

.github/workflows/updatebuildlist.yml

@@ -0,0 +1,37 @@
+---
+name: Update build list for tests
+on:
+  schedule:
+    - cron: '20 4 * * *'
+  workflow_dispatch:
+jobs:
+  update-builds-list:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout HEAD
+        uses: actions/checkout@v4
+      - name: Install moreutils
+        run: sudo apt-get install -y moreutils
+      - name: Download latest build list
+        uses: dawidd6/action-download-artifact@3ecf4024886f219d9290351234889bfb45d1b9da
+        with:
+          name: builds.txt
+          if_no_artifact_found: warn
+          path: /tmp/latestbuildlist/
+      - name: Update list
+        run: >
+            cat spec/builds.txt /tmp/latestbuildlist/builds.txt
+            <({ curl "https://pobarchives.com/api/builds?q=latest" & curl "https://pobarchives.com/api/builds?q=trending"; }
+            | jq -r '.builds[].build_info.build_link')
+            | tail -n 500
+            | sort -u
+            | sponge builds.txt
+      - name: Print new builds list
+        run: cat builds.txt
+      - name: Save new build list
+        uses: actions/upload-artifact@v4
+        with:
+          name: builds.txt
+          path: builds.txt
+          overwrite: true
+          retention-days: 3

.lua-format

@@ -0,0 +1,8 @@
+column_limit: 160
+indent_width: 1
+use_tab: true
+tab_width: 4
+continuation_indent_width: 4
+spaces_before_call: 1
+keep_simple_control_block_one_line: false
+keep_simple_function_one_line: false

.luacheckrc

@@ -0,0 +1,4 @@
+globals = { "round", "modLib", "LoadModule", "data", "ModFlag", "KeywordFlag", "SkillType", "launch", "IsKeyDown", "copyTable", "main", "colorCodesA"}
+read_globals = {"DrawString", "SetDrawLayer", "GetDrawLayer", "ConPrintf", "SetDrawColor", "DrawStringWidth", "GetCursorPos", "SetViewport", "GetTime", "DrawImage", "NewFileSearch", "MakeDir"}
+max_line_length = false
+exclude_files = { "src\\TreeData", "src\\Data"}

CONTRIBUTING.md

@@ -48,7 +48,7 @@ Feature requests are always welcome. Note that not all requests will receive an
 ### When submitting a pull request:
 * **Pull requests must be created against the `dev` branch**, as all changes to the code are staged there before merging to `master`.
 * Make sure that the changes have been thoroughly tested!
-* Make sure not to commit `./src/Data/ModCache.lua`. This is a very large, automatically generated file that is updated in the repository for releases only.
+* Make sure to commit `./src/Data/ModCache.lua` if your changes cause it to differ. This will generally be caused by editing `./src/Modules/ModParser.lua`.
 * There are many more files in the `./src/Data` directory that are automatically generated. This is indicated by the header 
   `-- This file is automatically generated, do not edit!`. To change these, instead change the scripts in the `./src/Export` directory and rerun the exporter.
   For your PR, please include all relevant changes to both the scripts and data files.
@@ -158,7 +158,7 @@ To do this in VSCode find the Java installation folder on your computer as displ
 -- This is the path to emmy_core.dll. The ?.dll at the end is intentional.
 package.cpath = package.cpath .. ";C:/Users/someuser/.vscode/extensions/tangzx.emmylua-0.5.19/debugger/emmy/windows/x64/?.dll"
 local dbg = require("emmy_core")
--- This port must match the Visual Studio Code configuration. Default is 9966.
+-- This port must match the IDE configuration. Default is 9966.
 dbg.tcpListen("localhost", 9966)
 -- Uncomment the next line if you want Path of Building to block until the debugger is attached
 --dbg.waitIDE()
@@ -200,34 +200,38 @@ If you're on windows, consider downloading [git for windows](https://git-scm.com
 
 If you're using linux you can run the ./runtime/Path{space}of{space}Building.exe executable with wine. You will need to provide a valid wine path to the emmy lua debugger directory.
 
-
 ## Testing
+Pob uses two types of tests. Unit tests that test specific calculations or mechanics and "build diff" tests that calculate the effect the changes have on a given list of builds.
+While both can be ran locally it's recommended to use the provided docker image for both ease of use and to keep everyone on the same page.
 
-PoB uses the [Busted](https://olivinelabs.com/busted/) framework to run its tests.  Tests are stored under `spec/System` and run automatically when a PR is modified.
-More tests can be added to this folder to test specific functionality, or new test builds can be added to ensure nothing changed that wasn't intended. 
-
-### Running tests
-1. Install [LuaRocks](https://luarocks.org/)
-2. Run `luarocks install busted`
-3. Run `busted --lua=luajit` from the command line.  You may need to add `luajit` to your PATH
+To run the unit tests run `docker compose up busted-tests`. This option uses the [Busted](https://olivinelabs.com/busted/) framework to test values returned by specific functions. For more details see the implementation of the tests in `spec/System/`.
 
-Docker alternative:
+To run the build difference tests run `docker compose up busted-diff`. `busted-diff` busted diff first computes a list of builds found in `spec/builds.txt` and `spec/TestBuilds/` while checked out to the current working changes. Then it uses git to checkout the branch specified by `DEVREF` or `dev` by default and computes the same builds. Lastly it finds the differences in the outputs generated from both, does some post processing, and prints all of the information out.
 
-1. Install [Docker](https://www.docker.com/get-started)
-2. Run `docker-compose up -d` from the command line
-3. View last results in `spec/test_results.log`
+`busted-diff` supports the following options through environment variables:
+- `DEVREF`: Defines the branch to use as the reference against which to compare builds computed with new changes.
+- `HEADREF`: Defines the branch which contains the changes to be tested.
 
-### Creating new test builds or fixing an existing build
+The following variables are meant to be internal only and only ever used with the `-e` option of docker compose, but are worth documenting nevertheless:
+- `CACHEDIR`: Defines the directory where the cache of computed builds using `DEVREF` should be stored.
 
-Sometimes a change will be made that intends to change the stats garnered by PoB, which will break our tests.
-1. Add the new build XML (if applicable) to the `TestBuilds` folder
-2. Run `busted --lua=luajit -r generate` to generate a LUA file that contains the current stats of that build
-3. Run `busted --lua=luajit` and the tests should pass
+#### Saving output
+By default the output is not saved to a file but you can do so some your shell by either using `docker compose up busted-tests > log` (platform agnostic) or `docker compose up busted-tests | tee log` which will also allow you to see the output as it's being printed out (powershell/linux).
 
-Docker alternative:
+Additionally, the output from `busted-diff` can be quite noisy. If you'd like to only get a specific part of the output you can use to following:
+- `sed -n '/Runtime comparison for/,/Savefile Diff for/{/Savefile Diff for/!p;}' log` to only print out runtime information or nothing if nothing interesting is to be shown.
+- `sed -n '/Savefile Diff for/, $p' /tmp/dockerlog` to print out parsed output mismatch information as well as raw text diff of the generated build xml.
 
-1. Add the new build XML (if applicable) to the `TestBuilds` folder
-2. Run `docker-compose up -d` to generate a LUA file that contains the current stats of that build and run the tests
+### Debugging tests
+When running tests with a docker container it is possible to use emmylua for debugging. Paste in the following right under `function launch:OnInit()` in `./src/Launch.lua`:
+```lua
+package.cpath = package.cpath .. ";/usr/local/bin/?.so"
+local dbg = require("emmy_core")
+-- This port must match the IDE Code configuration. Default is 9966.
+dbg.tcpListen("localhost", 9966)
+dbg.waitIDE()
+```
+After running `docker-compose up busted-tests` the code will wait at the `dbg.waitIDE()` line until a debugger is attached. This will allow stepping through any code that is internal to POB but will not work for busted related code. Note that this only works for unit tests described above.
 
 ## Path of Building development tutorials