diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index fbe371905..6119bd6b2 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -38,7 +38,7 @@ There are many ways to use Disco.js: from a browser, a CLI, by importing `discoj ### Running TypeScript -As a contributor, you will certainly end up having to run TypeScript scripts. A practical way to do so is to use on ts-node: +As a contributor, you will certainly end up having to run TypeScript scripts. A practical way to do so is to use `ts-node`: ``` npm i -g ts-node # globally to run scripts from anywhere @@ -104,6 +104,69 @@ npm -w webapp test The webapp tests rely on `cypress` and the test suite is located in the `webapp/cypress` folder. +Note that you can also run test interactively in the browser of your choice. To do so, run +``` +cd webapp +VITE_SERVER_URL=http://server npx start-server-and-test start http://localhost:8081 'cypress open --e2e' +``` +which should open the Cypress UI and let you choose the browser you wand to use and which tests to run. More information on [the Cypress docs](https://docs.cypress.io/app/get-started/open-the-app). + +#### Cypress and Github Actions + +It is possible to record the cypress tests ran in the Github Actions CI and visualize them in the [Cypress Cloud](cloud.cypress.io). It is currently used only when needed (because the free plan has a limited number of recordings). The [cypress documentation](https://docs.cypress.io/app/continuous-integration/github-actions) describes how to set up the recordings. + +1. A Disco project has been created in the Cypress Cloud and you need to be added to the project to be able to visualize the recordings. + +2. In `webapp/cypress.config.ts` you need to add the project ID, which is currently: +```js + projectId: "aps8et" +``` + +3. Finally, we can set the Cypress parameters in the Github Actions workflow `.github/workflows/lint-test-build.yml`, for example: +```yaml +test-webapp: + needs: [build-lib, build-lib-web, download-datasets] + runs-on: ubuntu-latest + # Runs tests in parallel with matrix strategy https://docs.cypress.io/guides/guides/parallelization + # https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs + # Also see warning here https://github.com/cypress-io/github-action#parallel + strategy: + fail-fast: false # https://github.com/cypress-io/github-action/issues/48 + matrix: + containers: [1, 2] # Uses 2 parallel instances + steps: + - uses: actions/checkout@v4 + with: + lfs: true + submodules: true + - uses: actions/cache@v4 + with: + path: datasets + key: datasets-${{ hashFiles('datasets/**') }} + - uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + cache: npm + - run: npm ci + - run: npm --workspace={discojs,discojs-web} run build + - run: npm --workspace=webapp run test:unit + - uses: cypress-io/github-action@v6 + with: + working-directory: webapp + install: false + start: npm start + wait-on: 'http://localhost:8081' # Waits for above + # Records to Cypress Cloud + # https://docs.cypress.io/guides/cloud/projects#Set-up-a-project-to-record + record: true + parallel: true # Runs test in parallel using settings above + env: + VITE_SERVER_URL: http://server + CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }} +``` + +Note that `CYPRESS_RECORD_KEY` is a repository secret which has already been added. + ### Contributing to `discojs` If you are brought to modify the `discojs` folder have a look at [DISCOJS.md](./DISCOJS.md) which explains some of the concepts internal to the library. @@ -147,6 +210,37 @@ Similarly to the server, any file ending with `.spec.ts` will be ran in the test Currently, the `discojs-node` project is available as the `@epfml/discojs-node` NPM package, which can be installed with `npm i @epfml/discojs-node` and the `discojs-web` as the `@epfml/discojs-web`. + +### Debugging + +> [!TIP] +> If your code changes don't seem to be effective, close everything, rebuild everything and restart. For example, changes in `discojs/src/default_tasks` requires rebuilding `discojs` and restarting the `server` to be effective. + +In Disco, we rely on the widely used [`debug` library](https://github.com/debug-js/debug). To use it, we first import debug and instantiate the debug object: +```js +import createDebug from "debug"; +const debug = createDebug("discojs:models:gpt:model"); // use nested namespaces +const logs = { loss: 0.01, accuracy: 0.56} +debug("Here are the GPT logs: %o", logs) +``` + +#### In the terminal +To visualize the logs in the command line, we need to set the `DEBUG` environment variable to choose the namespaces from which you want to see the debug statements. For example: +```bash +DEBUG='discojs:models:gpt*' npm -w cli run benchmark_gpt +``` +will print the debug statement from above. Similarly if we set `DEBUG='*'`. + +The server debug statements are visualized the same way, for example: +```bash +DEBUG='server*,discojs*' npm -w server start +``` +shows the debug statements from anywhere in the server and in discojs. + +#### Webapp + +To visualize debug statements in the browser, you need to open the console (Inspect element > Console) and set the `localStorage.debug` to the namespace of your choice, for example `localStorage.debug='webapp*,discojs*'` to visualize both the debug statements from anywhere in the webapp and in discojs. Note that you may need to refresh the page for changes to localStorage to be effective. + ## Contributing conventions The procedure for working on a feature is the following: