important

This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.

GitHub actions

We use github actions for doing PR checks.

Examples#

Core tests#

This is the workflow file: https://github.com/supertokens/supertokens-core/blob/master/.github/workflows/tests.yml

It's a manually run workflow because it requires to know the branch of the plugin interface that it should run against. So to start it, visit this link, and click on the "Run workflow" button on the top right. You will see a drop down using which you can supply the args for plugin interface branch and then run the workflow.

Once the workflow starts, it will setup the dev env and run the tests. If the tests pass, the workflow will pass, else it will fail.

A few notable points:

The core tests run in its own docker image, so if there is a db that needs to run, then that will run in its own docker image. Github connects the two containers via the docker network, so the core tests can refer to the db using its docker service name. For example, in the sql-plugin workflow, we edit the config yaml for the tests to make it point to the postgresql docker image instead of localhost.
If you are creating a new workflow, it needs to be added to the master / main branch of the github repo before you can run it via the actions tab for that repo. A recommended way to create a new manual workflow would be to fork the repo, add the workflow to that repo in the master branch directly (and iterate there), and once ready, issue a PR to the target repo.

Since this test is to be run manually, it cannot be automatically run in each PR. So for that, there is another github action called "Check if "Run tests" action succeeded". This action runs on each PR of the core and checks if the test was run manually against that PR's latest commit. If it was run manually, and succeeded, this check will succeed too. Else it will wait for it to run. If the manual test is not run in the first 1.5 mins of the PR push, this check will fail too (then it can be rerun manually).

The above action requires a JS script to work which can be found here. The contents of the "Check if "Run tests" action succeeded" action and its JS script would largely be the same across repos. The only difference would be:

linkToJob: This is the link to the manually run test.
testJobName: This is the name of the action that the user needs to run manually.