This is your starter code for Lab 3 on Fullstack Development. The main goal here, as described in LABTASKS, is to explore and implement client-side or frontend aspects of the client/server architecture as part of a fullstack project (Fullstack is just a fancy way of saying you will developing both the frontend and the backend aspects of the project, as well as testing that the frontend and backend are working together). You'll also add functionality to support 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 MongoDB database.
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:
- Go into the
databasedirectory and enter./mongoseed.shto run the script that will seed the database. - Go into the
serverdirectory and enter./gradlew runto run your server. - In a different terminal, go into the
clientdirectory and enterng serveto make the client available. - You can then go to
localhost:4200in your favorite web browser and see your nifty Angular app.
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 installed, as described in the system setup
documentation from the
beginning of the semester (but, maybe a newer version around 7.0.16). If you're unsure if it's set up and
working correctly, try running mongosh.
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 :
Or, you might simply get a message saying the command can't be found. If everything's good you should get something like this:
Current Mongosh Log ID: 67a47dc2c810acdbd78b945c
connecting to: mongodb://127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.3.8
Using MongoDB: 7.0.16
Using Mongosh: 2.3.8
Type exit or ^D to exit out of the mongo shell tool.
⚠️ For various reasons we're running a slightly older version of Mongo in the lab (v7, when the current version is v8). This generally won't affect things, but there may be features that v7 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 v8 feature.When looking things up in the MongoDB docs, it's probably wise to use the v7.0 documentation.
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.
Before you start working you will need to install the dependencies for the client.
- Move into the
clientdirectory (cd client) - Run
npm install
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.
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.
dev database
whenever you run them to ensure that those tests happen in a predictable
state, so be prepared for that.
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.
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.
You have the ability to test the client (component testing with Karma), the server (JUnit testing and Mockito), or both (E2E testing).
From the client directory:
ng testruns 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 testprocess and close the generated Chrome window. - You can add
ng test --no-watchif you just want to run the tests once instead of going into the "run forever" mode.
ng test --code-coverageruns 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.htmland selectCopy pathand paste it into your browser of choice. You can also drag and dropindex.htmlonto the tab area of your browser and it will open it.
- It generates a coverage report you can find in your client directory
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.
From the server directory:
./gradlew testruns the server tests once.- It generates a report you can find in
server/build/reports/tests/test/index.html.
- It generates a report you can find in
./gradlew test jacocoTestReportruns the server tests once and creates a coverage report- It generates a coverage report you can find in
server/build/jacocoHtml/index.htmlin addition to the regular report generated by thetesttask.
- It generates a coverage report you can find in
.gradlew checkruns 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 Thunder Client GitHub extension can be quite useful here; see THUNDER_CLIENT.md for more details and examples.
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 e2eboth builds and serves the client and runs through all the Cypress end-to-end tests once.ng e2e --watchbuilds 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 serveandnpm run cy:open(ornpx cypress open) at the same time. If you are already runningng serveit will be easier to runnpx cypress openrather than closing yourng serve, runningng e2e, and restartingng serve.
- This is the same as running
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 "Selected Resources" section below or in the Resources markdown file.
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)
We have a much longer list of links in Resources, but here are a few I think you'll find especially helpful since they relate to new things or things that were not well documented in the previous lab: