Merge pull request #83 from UMM-CSci-3601/update-writeup-for-S24

Update writeup for s24

.vscode/settings.json

@@ -9,10 +9,12 @@
     ],
     "cSpell.words": [
       "Bson",
+      "Checkstyle",
       "compat",
       "CSCI",
       "dont",
       "floogulinc",
+      "gradlew",
       "Ibmers",
       "invalidemail",
       "invalidrole",

LABTASKS.md

@@ -10,29 +10,29 @@
 
 ## Getting started
 
-- Remember to set up GitHub Projects with your stories and estimates
-- Turn in the URL of the GitHub repository for your group in Canvas. This will make it easier for us to figure out which team is "Snoozing Llamas".
+- [ ] Remember to set up your project on GitHub Projects with your stories and estimates
+- [ ] Turn in the URL of the GitHub repository for your group in Canvas. This will make it easier for us to figure out which team is "Snoozing Llamas".
 
 Definitely ask if you're ever confused about what you need to do for a given task.
 
 ## Exploring the project
 
 The structure of this project should be nearly identical to that of Lab 3, and as such there really isn't much excitement in that department.
 
-The server is, for the most part, the same as it has been in the past two labs. The difference to look for here is in how the server gets the data it sends out in reply to requests.
+The structure of the server is, for the most part, the same as it has been in the past two labs. The difference to look for here is in how the server gets the data it sends out in reply to requests.
 
 Spend some time looking over the project with these questions in mind. (Unlike the previous labs, however, you do _not_ need to write up and turn in your answers to these questions.)
 
-1. What do we do in the `Server` and `UserController` constructors
-   to set up our connection to the development database?
-1. How do we retrieve a user by ID in the `UserController.getUser(String)` method?
-1. How do we retrieve all the users with a given age
-   in `UserController.getUsers(Context...)`? What's the role of
-   the variable `filters` in that method?
-1. What is happening in the `UserControllerSpec.setUpEach()` method?
-1. What's being tested in `UserControllerSpec.canGetUsersWithAge37()`?
-   How is that test implemented?
-1. Follow the process for adding a new user. What role does `UserController` play in the process?
+- [ ] What do we do in the `Main`, `Server` and `UserController` classes
+- [ ] to set up our connection to the development database?
+- [ ] How do we retrieve a user by ID in the `UserController.getUser(Context...)` method?
+- [ ] How do we retrieve all the users with a given age
+- [ ] in `UserController.getUsers(Context...)`? What's the role of
+- [ ] the variables `combinedFilter` and `sortingOrder` in that method?
+- [ ] What is happening in the `UserControllerSpec.setUpEach()` method?
+- [ ] What's being tested in `UserControllerSpec.canGetUsersWithAge37()`?
+- [ ] How is that test implemented?
+- [ ] Follow the process for adding a new user. What role does `UserController` play in the process?
 
 ## Overview of the lab
 
@@ -45,23 +45,23 @@ Spend some time looking over the project with these questions in mind. (Unlike t
 
 ### Features to implement
 
-- Filter todos by status
-- Filter todos by owner
-- Filter todos by contents of the body
-- Filter todos by category
-- Combinations of filters
-- Sort by a todo field (status, owner, body contents, or category)
-- Limit the number of todos returned
-- Ability to add new todos. This requires:
-  - An Angular form/page that allows the user to enter the information for a new todo with reasonable controls and validation.
-  - A new endpoint on the server that allows clients to add new todos.
-  - Logic in the server to add that new todo to the database and return the new ID.
-- Testing of all of the above.
-- Display the todos in a reasonable way using at least two nifty Angular Material features from [here](https://material.angular.io/components/categories)!
+- [ ] Filter todos by status
+- [ ] Filter todos by owner
+- [ ] Filter todos by contents of the body
+- [ ] Filter todos by category
+- [ ] Combinations of filters
+- [ ] Sort by a todo field (status, owner, body contents, or category)
+- [ ] Limit the number of todos returned
+- [ ] Ability to add new todos. This requires:
+  - [ ] An Angular form/page that allows the user to enter the information for a new todo with reasonable controls and validation.
+  - [ ] A new endpoint on the server that allows clients to add new todos.
+  - [ ] Logic in the server to add that new todo to the database and return the new ID.
+- [ ] Testing of all of the above.
+- [ ] Display the todos in a reasonable way using at least two nifty Angular Material features from [here](https://material.angular.io/components/categories)!
 
 ## Workflow and Continuous Integration
 
-You should organize your work into features, where each feature is an (small) epic or a single story in GitHub Projects. Each feature should "slice the cake", including server implementation and testing, Angular implementation and testing, and end-to-end testing.
+You should organize your work into features, where each feature is a (small) story in GitHub Projects. Each feature should "slice the cake", including server implementation and testing, Angular implementation and testing, and end-to-end testing.
 
 :warning: Keep the features as small and focussed as
 possible. Otherwise things like code reviews become a huge burden,
@@ -83,7 +83,7 @@ where you replace the name ("Connie Stewart") and email
 ("conniestewart@ohmnet.com") with the name and email of the
 person you're pairing with.
 
-- As you work, create a branch for a new feature.
+- [ ] As you work, create a branch for each new feature.
   - Write tests for the server actions for the feature you added. Run
     them to make sure they fail. Then write the server code that
     makes those tests pass.
@@ -93,21 +93,26 @@ person you're pairing with.
     using Karma. Run them to make sure they also fail. Then write the
     Angular code that makes those unit and integration/e2e tests pass.
   - Address failing builds.
-- Perform code reviews especially if you're not pair programming.
+- [ ] Perform code reviews, especially if you're not pair programming.
   _Ask (your partner, the class, the instructor) about things you don't understand!_
-- Use pull requests to
+- [ ] Use pull requests to
   merge things into `main` when a feature is working
   and is tested (with passing tests and decent coverage).
 
 ## Writing todos to the Database
 
-- We have included an example of writing to the database with `addUser` functionality. Add to both the front-end and back-end to make it possible to add todos so that they appear both in your list and in the database.
+- We have included an example of writing to the database with `addUser` functionality. Add
+  functionality to both the front-end and back-end to make it possible to add todos so that
+  they appear both in your list and in the database.
 
 ## Display todos
 
 You should use Angular to display todos in attractive, readable, and useful ways that are helpful for understanding the nature of a todo.
 
-- Use the Angular Material Design tools you've learned about to build a nice interface for
+- [ ] Use the Angular Material Design tools you've learned about to build a nice interface for
   accessing these APIs:
-  - You must use at least two nifty Angular Material features from [here](https://material.angular.io/components/categories)!
+  - [ ] You must use at least two nifty Angular Material features from [here](https://material.angular.io/components/categories)!
   - There are many interesting tools - we encourage you to try several.
+  - Feel free to borrow ideas and (preferably small bits of) code from the previous labs, but make
+    sure you understand it. Also feel free to use this as an opportunity to improve the UI, perhaps
+    taking advantages of ideas you had earlier but weren't able to implement then.

README.md

@@ -1,9 +1,5 @@
 # CSCI 3601 Lab 4 - MongoDB <!-- omit in toc -->
 
-[![Server Build Status](../../actions/workflows/server.yml/badge.svg)](../../actions/workflows/server.yml)
-[![Client Build Status](../../actions/workflows/client.yaml/badge.svg)](../../actions/workflows/client.yaml)
-[![End to End Build Status](../../actions/workflows/e2e.yaml/badge.svg)](../../actions/workflows/e2e.yaml)
-
 - [Setup](#setup)
   - [Make sure you have Mongo running on your (lab) computer](#make-sure-you-have-mongo-running-on-your-lab-computer)
   - [Open the project in VS Code](#open-the-project-in-vs-code)
@@ -26,7 +22,7 @@
 This is your starter code for Lab 4. The main goal here, as
 described in [LABTASKS](./LABTASKS.md), is to update the server
 code to actually use the MongoDB database instead of using the fixed
-set of users and todos in Labs 2 and 3.
+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,
@@ -35,13 +31,15 @@ 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 the command line or GitKraken:
+group using GitHub classroom, you can clone your repository using your tools of choice.
 
-1. From the file menu, choose **Clone Repo**
-2. Choose GitHub.com in the middle column (as the source location of your repo)
-3. Browse to the location you'd like to put the local copy of this project repo
-4. Select the correct repo from the list of repositories
-5. Select **Clone the repo!**
+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`](http://localhost:4200) in your favorite web browser and see
+   your nifty Angular app.
 
 ### Make sure you have Mongo running on your (lab) computer
 
@@ -71,12 +69,12 @@ MongoDB server version: 5.0.14
 
 Type `exit` or `^D` to exit out of the `mongo` shell tool.
 
-> :warning: For various reasons we're running a slightly
+> :warning: For various reasons we're running an
 older version of Mongo in the lab (v5, when the current version
-is v6). This generally won't affect things, but there may be features that
+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 v6 feature.
+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](https://www.mongodb.com/docs/v5.0/).
@@ -115,24 +113,17 @@ 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`](http://localhost:4567).
-- The **build** task will _build_ the server (including running
-  Checkstyle and the tests), but not run it.
+The **run** Gradle task (`./gradlew run` in the `server` directory) will still run your Javalin
+server, which is available at [`localhost:4567`](http://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`](http://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 lab #3 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.
+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:
-
-To recap, **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`](http://localhost:4200) in your favorite web browser and see
-   your nifty Angular app.
+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
 
@@ -161,6 +152,11 @@ You can explore the databases and collections here. You can click a record to vi
 
 ![Screenshot of displaying the users in the sample MongoDB database in VS Code](https://user-images.githubusercontent.com/1300395/109005447-91882c00-766f-11eb-994e-9a326deee21b.png)
 
+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
@@ -194,6 +190,9 @@ From the `server` directory:
   - 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.
 
 ### End to end testing
 
@@ -204,9 +203,13 @@ We use [Cypress](https://www.cypress.io/) for our end-to-end tests. There are a
 
 - `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 do this rather than closing it and running `ng e2e`.
+  - 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 main page of Cypress looks like this:
+:warning: 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:
 
 ![image](https://user-images.githubusercontent.com/1300395/109009410-22f99d00-7674-11eb-9469-dd6a09710813.png)
 
@@ -222,9 +225,7 @@ There are three GitHub Actions workflows set up in your repo:
 
 - [Server Java](../../actions/workflows/server.yml) - JUnit tests for the server (`gradle-build`)
 - [Client Angular](../../actions/workflows/client.yaml) - Karma tests (`ng-test`) and ESLint linting (`ng-lint`) for the client
-- [End to End](../../actions/workflows/e2e.yaml) - Cypress tests for end-to-end testing
-
-There are badges above that show the status of these checks on the master branch.
+- [End to End](../../actions/workflows/e2e.yaml) - Cypress tests for end-to-end testing (`ng-e2e`)
 
 ## Resources