From b2c0e23e36f123db06d7c590c38957852a85df65 Mon Sep 17 00:00:00 2001
From: Gnuxie <50846879+Gnuxie@users.noreply.github.com>
Date: Wed, 23 Nov 2022 10:55:00 +0000
Subject: [PATCH] Update CONTRIBUTING.md to show how to debug mjolnir. (#433)

---
 CONTRIBUTING.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++--
 package.json    |  2 ++
 2 files changed, 73 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 794abc6..3ad9382 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,13 +15,82 @@ relevant project on github, and then [create a pull request](
 https://help.github.com/articles/using-pull-requests/) to ask us to pull
 your changes into our repo.
 
-We use [Buildkite](https://buildkite.com/matrix-dot-org/mjolnir) for continuous
-integration. If your change breaks the build, this will be shown in GitHub, so
+We use Github Actions for continuous integration.
+If your change breaks the build, this will be shown in GitHub, so
 please keep an eye on the pull request for feedback.
 
+## Development
+
 To run unit tests in a local development environment, you can use `yarn test`
 and `yarn lint`.
 
+### mx-tester
+
+For integration testing, and spinning up a local synapse we use
+[mx-tester](https://github.com/matrix-org/mx-tester).
+While not required for basic changes, it is strongly recommended
+to use mx-tester or have the ability to spin up your own
+development Synapse to develop mjolnir interactively.
+
+To install `mx-tester` you will need the [rust toolchain](https://rustup.rs/)
+and Docker. You should refer to your linux distribution's documentation
+for installing both, and do not naively follow the instructions
+from rustup.rs without doing so first.
+Then you will be able to install `mx-tester` with `cargo install mx-tester`.
+Updating mx-tester can be done by installing `cargo install cargo-update`
+and using `cargo install-update mx-tester`, though you may skip
+this step until it is necessary to update `mx-tester`.
+
+#### Usage
+
+You can then start a local synapse using `mx-tester build`,
+followed by `mx-tester up`. You can then use `up`, `down` as many
+times as you like.
+If for some reason you need to get a clean Synapse database,
+you can just use `mx-tester down build`.
+
+### Debugging
+
+For debugging mx-tester it is recommended to use Visual Studio Code.
+If you open the project in visual studio code, press `F1`,
+type `Debug: JavaScript Debug Terminal`
+(see the [documentation](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_javascript-debug-terminal)),
+and you should get a terminal from which node will always connect to
+Visual Studio Code.
+
+The following sections assume that a Synapse is running
+and `config/harness.yaml` has been configured to connect to it.
+If you are using `mx-tester` and you use `mx-tester up`, this will
+already be the case.
+
+#### Debugging and reproducing an issue
+
+If you need to debug an issue that is occurring through use in matrix,
+say the unban command has stopped working, you can launch
+mjolnir from the JavaScript Debug Terminal using `yarn test:manual`.
+This will launch mjolnir using the config found in `config/harness.yaml`.
+You can now open https://app.element.io, change the server to `localhost:8081`,
+and then create an account.
+From here you can join the room `#moderators:localhost:9999` (you will also be
+able to find it in the rooms directory) and interact with mjolnir.
+
+It is recommended to set breakpoints in the editor while interacting
+and switch the tab to "DEBUG CONSOLE" (within Visual Studio Code)
+to evaluate arbitrary expressions in the currently paused context (when
+a breakpoint has been hit).
+
+#### Debugging an integration test
+
+To debug the integration test suite from the JavaScript Debug Terminal,
+you can start them using `yarn test:integration`.
+However, more often than not there is a specific section of
+code you will be working on that has specific tests. Running
+the entire suite is therefore unnecessary.
+To run a specific test from the JavaScript Debug Terminal,
+you can use the script `yarn test:integration:single test/integration/banListTest.ts`,
+where `test/integration/banListTest.ts` is the name of the integration test you
+want to run.
+
 ## Code style
 
 All Matrix projects have a well-defined code-style - and sometimes we've even
diff --git a/package.json b/package.json
index 1612026..99f3696 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,9 @@
     "start:dev": "yarn build && node --async-stack-traces lib/index.js",
     "test": "ts-mocha --project ./tsconfig.json test/commands/**/*.ts",
     "test:integration": "NODE_ENV=harness ts-mocha --async-stack-traces --require test/integration/fixtures.ts --timeout 300000 --project ./tsconfig.json \"test/integration/**/*Test.ts\"",
+    "test:integration:single": "NODE_ENV=harness npx ts-mocha --require test/integration/fixtures.ts --timeout 300000 --project ./tsconfig.json",
     "test:appservice:integration": "NODE_ENV=harness ts-mocha --async-stack-traces --timeout 300000 --project ./tsconfig.json \"test/appservice/integration/**/*Test.ts\"",
+    "test:appservice:integration:single": "NODE_ENV=harness npx ts-mocha --timeout 300000 --project ./tsconfig.json",
     "test:manual": "NODE_ENV=harness ts-node test/integration/manualLaunchScript.ts",
     "version": "sed -i '/# version automated/s/[0-9][0-9]*\\.[0-9][0-9]*\\.[0-9][0-9]*/'$npm_package_version'/' synapse_antispam/setup.py && git add synapse_antispam/setup.py && cat synapse_antispam/setup.py"
   },