mirror of
https://github.com/matrix-org/mjolnir.git
synced 2024-06-28 23:52:06 +00:00
Update CONTRIBUTING.md to show how to debug mjolnir. (#433)
This commit is contained in:
parent
410ceebd62
commit
b2c0e23e36
|
@ -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
|
https://help.github.com/articles/using-pull-requests/) to ask us to pull
|
||||||
your changes into our repo.
|
your changes into our repo.
|
||||||
|
|
||||||
We use [Buildkite](https://buildkite.com/matrix-dot-org/mjolnir) for continuous
|
We use Github Actions for continuous integration.
|
||||||
integration. If your change breaks the build, this will be shown in GitHub, so
|
If your change breaks the build, this will be shown in GitHub, so
|
||||||
please keep an eye on the pull request for feedback.
|
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`
|
To run unit tests in a local development environment, you can use `yarn test`
|
||||||
and `yarn lint`.
|
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
|
## Code style
|
||||||
|
|
||||||
All Matrix projects have a well-defined code-style - and sometimes we've even
|
All Matrix projects have a well-defined code-style - and sometimes we've even
|
||||||
|
|
|
@ -14,7 +14,9 @@
|
||||||
"start:dev": "yarn build && node --async-stack-traces lib/index.js",
|
"start:dev": "yarn build && node --async-stack-traces lib/index.js",
|
||||||
"test": "ts-mocha --project ./tsconfig.json test/commands/**/*.ts",
|
"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": "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": "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",
|
"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"
|
"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"
|
||||||
},
|
},
|
||||||
|
|
Loading…
Reference in New Issue
Block a user