Developing

This wiki page assumes that you have a working Dev Container as discussed in the Setup guide.

_{As usual, by "command" we refer to a command in the VSCode Command Palette.}

Tip

If you have problems with the setup, refer to the Dev Container Help section.

Working in a Dev Container

Once your Dev Container is built, you have a working environment. You can freely use git and even the GitHub CLI gh. Switch to any branches you want, no need to rebuild the container (even if a VSCode prompt asks you to because it "detected changes").

Only when you want to rebuild your container (hopefully not that often since it takes some time), you have to be on a branch that has a valid Dev Container setup. Once built, do anything you want in your environment. Except for one thing: don't stop or restart the MaMpf app container itself as this is the principal Dev Container. If you stop it, you have to reconnect again (e.g. restart VSCode, or maybe you even have to rebuild the container in this case).

Starting the MaMpf app

The Dev Container is started inside the main container where the MaMpf Rails app itself can be run. There are also other containers, e.g. a database container and an nginx container, but they should have already been started for you. To check this, go to the Containers pane.

All that is left to do, is to fill the database with some initial dummy data ("pre-seeding") and to start the MaMpf Rails server afterwards. You can do so by using the respective VSCode tasks. Use the command Run Task to do so (the tasks should have self-explanatory names). The task to start the MaMpf app is a special build task that you can also invoke via Ctrl+Shift+B.

Alternatively, and especially in other IDEs, you can seed the database and start the app via the terminal: just seed, then just up. In fact, all that the VSCode tasks do is to invoke these commands.

Finally, go to the ports pane by using the Toggle Ports command. The ports are labeled and should be self-explanatory. Click on the world icon to open the local address. Access every port in the Browser and find out what it does. Also see this FAQ.

Also keep in mind that especially when you've started the MaMpf App for the first time, it might take a few seconds until the initial views are correctly rendered. In our dummy developer database, use the following users with the password dockermampf: student1@mampf.edu, until student4@mampf.edu, teacher@mampf.edu and admin@mampf.edu.

✨ Congratulations, you are now ready to change MaMpf code, see how it affects the app locally, and then commit the changes in a new branch to finally create a Pull Request (PR).

Debugging

Debugging is essential to understand the control flow and to quickly fix errors. You can easily debug the backend Ruby on Rails code. Access the Debug pane and start the config named "Debug MaMpf Backend" (press F5). Set a breakpoint somewhere, e.g. at the beginning of the MainController:start method. When you then navigate to the respective page in the browser, the debugger should halt. Learn more about debugging in the VSCode docs.

Testing (unit tests)

We use RSpec to unit-test our Ruby on Rails backend. Navigate to a model test in the spec/models folder. Click on the "Play button" next to the test definitions to run the respective test. Learn more about running and debugging tests in the VSCode docs. Note that we also run through all unit tests in GitHub Actions when you make a pull request.

For all tests to run through correctly, you will have to start up the MaMpf app first. Otherwise, you will encounter errors related to Vite. _{This is because we also run the Vite server inside the app container. See more on this advanced topic on the Vite page.}

Testing (integration tests)

While unit tests are very important, we also want to test our app from a user's point of view, i.e. in the browser. There we make sure that certain scenarios don't fail, e.g. logging in as a user, registering to a lecture etc.

We use Cypress for these integration tests. Access it on the respective port to run through the tests. We also run through all integration tests in GitHub Actions when you make a pull request.

Cypress has some downsides which is why we are currently migrating to Playwright e2e tests. These should be the new default when you write new tests. Find the test files in the e2e/ folder. Playwright comes with a wide range of tooling that you can use (please read their docs, they are very comprehensive and they have lots of nice tutorials):

• The Playwright VSCode extension is automatically installed for you. With it, you should be able to easily run any test by clicking on the play button next to it. See more about how to use it in the great Playwright docs.

• In the test pane, you get a Playwright section where you can select different options:

  

  • No options. If you just want to run through the test and see if they still work, don't activate any option. This will result in the fastest test runs. Tests will run in a headless Chromium browser.

  • Show trace viewer. This is probably the checkbox that you should have activated most of the time. It will open a local server (browser should open automatically) that allows you to replay any test. It is however only a trace of the test, i.e. it is static and you cannot interact with the page in any way (it's a static capture of the DOM).

  • Show browser. This will launch a real (non-headless, i.e. headful) Chromium browser and replays the tests there. This is especially useful for multiple things:

    • Interact with the site after the test is finished.
    • Debug your tests, see also the docs.
    • Recording tests by clicking on elements in the browser, see also the docs. This is just mindblowing to me. You can even write a little code, then start recording at your cursor position.

    The only downside is that Playwright needs to launch a real browser that they can control. So you have to install any VNC viewer, e.g. RealVNC, and connect to localhost:5933. You should see a simple Desktop environment (a bar on the bottom of the page). Whenever you start a Playwright test, you should see the browser opening here. Currently, the browser closes immediately after the test is run. This is probably a bug, see my comment here.

  • On top of all of this, Playwright also offers its custom UI Mode. Start it with the respective VSCode task (or via just playwright-ui in the terminal). This will launch a server (browser should open automatically) where you can start different tests. In my opinion, you don't need this mode since you can easily run the tests via the VSCode extension and see the trace via the Show trace viewer checkbox. Still nice to know it exists and it could be handy on a second monitor.

  • The option Pick locator will require you to have the browser opened via Show browser from a last test run (not working right now, see my comment above). However, you can also pick a locator in the trace viewer as well as the UI mode.

  • You will probably never need the following buttons/options: Run global setup, Run global teardown, Run global setup on each run Update snapshots Update method.