CSCI 3601 Lab 4 - MongoDB

• Setup
  • Make sure you have Mongo running on your (lab) computer
  • Open the project in VS Code
  • Installing the client dependencies
  • Seeding the Database
• Running your project
  • MongoDB in VS Code
• Testing and Continuous Integration
  • Testing the client
    • Linting the client
  • Testing the server
  • End to end testing
  • GitHub Actions
• Resources
  • Angular (client)
  • Javalin (server)
  • MongoDB (database)
  • Cypress (end-to-end testing)

This is your starter code for Lab 4. The main goal here, as described in LABTASKS, is to update the server code to actually use the MongoDB database instead of using the fixed set of users and todos we used in Labs 2 and 3. You'll also add functionality to do things like adding new todos; this will require making changes all the way through from the Angular client, through the Java(lin) server, to the database.

Setup

As in the previous labs, you'll be using VS Code and GitKraken. Once you've all joined your group using GitHub classroom, you can clone your repository using your tools of choice.

As a reminder, here are the steps needed to run the project:

1. Go into the database directory and enter ./mongoseed.sh to run the script that will seed the database.
2. Go into the server directory and enter ./gradlew run to run your server.
3. In a different terminal, go into the client directory and enter ng serve to make the client available.
4. You can then go to localhost:4200 in your favorite web browser and see your nifty Angular app.

Make sure you have Mongo running on your (lab) computer

For all of this to work, it's critical that you have Mongo installed and working. We should have that running on all the lab computers (although it's good to confirm that). If you also want to do development on your own computer you'll need to make sure you have MongoDB install, as described in the system setup documentation from the beginning of the semester. If you're unsure if it's set up and working correctly, try running mongo.

If your MongoDB server isn't installed you'll likely get an error message like:

Error: couldn't connect to server 127.0.0.1:27017, connection attempt failed: SocketException: Error connecting to 127.0.0.1:27017 :: caused by :: Connection refused :

If everything's good you should get something like this:

MongoDB shell version v5.0.14
connecting to: mongodb://127.0.0.1:27017
MongoDB server version: 5.0.14

Type exit or ^D to exit out of the mongo shell tool.

⚠️ For various reasons we're running an older version of Mongo in the lab (v5, when the current version is v7). This generally won't affect things, but there may be features that v5 doesn't support. If you're trying something you found online and it doesn't seem to work as advertised, you might check and see if it's a v7 feature.

When looking things up in the MongoDB docs, it's probably wise to use the v5.0 documentation.

Open the project in VS Code

Launch Visual Studio Code, and then choose File -> Open Folder…. Navigate to your clone of the repo and choose Open.

You may see a dialog that looks like this if you don't already have the recommended extensions:

Don't worry if you don't get the dialog, it is probably because you already have them all installed.

Like in previous labs, click "Install All" to automatically install them.

Installing the client dependencies

Before you start working you will need to install the dependencies for the client.

1. Move into the client directory (cd client)
2. Run npm install

Seeding the Database

To give yourself some data to work with instead of starting with an empty database in our development environment, you need to 'seed' the database with some starter data. Seed data and the seed script are stored in the top level directory database. To seed the database, move into that directory and run ./mongoseed.sh (on Mac/Linux) or ./mongoseed.bat (on Windows). This will take each of the JSON files in database/seed/ and insert their elements into the dev database.

⚠️ Shell scripts (.sh) will not run on Windows machines, and Batch scripts (.bat) will not run on Unix-like machines. Be sure that you are running the correct script for your operating system.

These scripts also drop the database before seeding it so it is clean. You should run this after first cloning the project and again anytime you want to reset the database or you add new seed data to the database/seed/ directory.

⚠️ Our E2E tests also reseed the dev database whenever you run them to ensure that those tests happen in a predictable state, so be prepared for that.

Running your project

The run Gradle task (./gradlew run in the server directory) will still run your Javalin server, which is available at localhost:4567. The build task will build the server (including running Checkstyle and the tests), but not run it.

Once you have successfully run npm install, in order to serve up the client side of your project, you will run ng serve (from the client directory as well). The client will be available by default at localhost:4200. If your server is running, you will be able to see data for users if you navigate to the right place in the project.

The major difference between this lab and the previous labs is that, here, your data (users and todos) will be stored in a database rather than as "flat" JSON files within the server source code.

For the most part, you will be using a local installation of Mongo as a dev (development) database. You don't really need to worry about how this is set up, but you do need to know a couple of tricks to help you use it effectively.

MongoDB in VS Code

We have included the MongoDB for VS Code in the recommended extensions. This extension allows you to view and edit things in the Mongo database.

Expand for setup instructions

When installed you will see a new icon in the sidebar, click it and click "Add Connection".

That will open a new tab with some options. Click "Open form" under "Advanced Connection Settings"

You can leave all the default settings and click the green "Connect" button to add the connection.

You will then have the MongoDB server in the sidebar.

You can explore the databases and collections here. You can click a record to view and edit it.

You can also create a MongoDB Playground in VSCode, which allows you to experiment with queries in a more interactive way than is possible when you're working with your Java code. Once you have a query working the way you want it, you can then export the query in different programming languages, include Java.

Testing and Continuous Integration

You have the same testing options as before: you can test the client, or the server or both.

Testing the client

From the client directory:

• ng test runs the client tests
  • This will pop up a Chrome window with the results of the tests.
  • This will run "forever", updating both in your terminal and in the Chrome window that gets generated. Typing CTRL-C in the terminal window will end the ng test process and close the generated Chrome window.
  • You can add ng test --no-watch if you just want to run the tests once instead of going into the "run forever" mode.
• ng test --code-coverage runs the client tests and generates a coverage report
  • It generates a coverage report you can find in your client directory client/coverage/client/index.html.
  • Right click on index.html and select Copy path and paste it into your browser of choice. You can also drag and drop index.html onto the tab area of your browser and it will open it.

Linting the client

We have included a tool called ESLint which helps analyze the client TypeScript and template HTML code and catch various errors and concerns. You will most likely see it directly in VS Code as yellow and red underlines. You can also directly run the linter on the entire client by running ng lint in the terminal in the client directory. This will check the whole client project and tell you if there are any issues.

Testing the server

From the server directory:

• ./gradlew test runs the server tests once.
  • It generates a report you can find in server/build/reports/tests/test/index.html.
• ./gradlew test jacocoTestReport runs the server tests once and creates a coverage report
  • It generates a coverage report you can find in server/build/jacocoHtml/index.html in addition to the regular report generated by the test task.
• .gradlew check runs the tests and the Checkstyle checks
  • This is useful to avoid having annoying build fails on GitHub because Checkstyle didn't like your layout somewhere.

You might find it useful to be able to generate HTTP requests "by hand" and see what the output is. The Thunderclient GitHub extension can be quite useful here; see THUNDER_CLIENT.md for more details and examples.

End to end testing

End to end (E2E) testing involves the whole software stack rather than one part of it. Our E2E tests look at the behavior of both the client, the server, and the database, and how they interact by simulating how a real user would interact with the app.

We use Cypress for our end-to-end tests. There are a few ways to run the E2E tests. They are all started from the client directory and require the server be running at the same time (./gradlew run in the server directory).

• ng e2e both builds and serves the client and runs through all the Cypress end-to-end tests once.
• ng e2e --watch builds and serves the client but just opens Cypress for you to be able to run the tests you want without closing automatically.
  • This is the same as running ng serve and npm run cy:open (or npx cypress open) at the same time. If you are already running ng serve it will be easier to run npx cypress open rather than closing your ng serve, running ng e2e, and restarting ng serve.

⚠️ The Cypress screenshots below are a little out of date, but you should get the idea.

The main page of Cypress looks something like this:

You can click on any of the integration test files to run their tests or run them all. When you run a set of tests you will see something like this:

There are a lot of neat things you can do here like inspect each test and find which selectors to use in the tests you are writing. We encourage you to look through some of the Cypress documentation linked in the "Resources" section below.

GitHub Actions

There are three GitHub Actions workflows set up in your repo:

• Server Java - JUnit tests for the server (gradle-build)
• Client Angular - Karma tests (ng-test) and ESLint linting (ng-lint) for the client
• End to End - Cypress tests for end-to-end testing (ng-e2e)

Resources

Angular (client)

• Angular Unit Testing (Karma)
• Angular Routing
• Angular Forms
• Angular Material
• What are environments in Angular
• Angular CLI

Javalin (server)

• Javalin Documentation
• Javalin Tutorials
  • Testing Javalin Applications

MongoDB (database)

• The MongoDB Manual
• MongoDB Java Drivers
  • MongoDB Driver 4.8 Documentation
  • Documentation specific to the driver
• MongoJack
• JSON Generator for generating seed data for testing

Cypress (end-to-end testing)

• Cypress Docs
• Cypress Best Practices
• Introduction to Cypress
• Interacting with Elements in Cypress