homework 1: Test-Driven Development for the web

Our long term goal in these early homeworks is to build a polished, secure web application. Very often in CS courses, the specification is a grading rubric, or a solution, or something else, and a lot of the time we just write the code and hope it works the way we expect it. There’s gotta be a better way!

Enter test-driven development.

Fail first

In test-driven development, first you write the tests. They should fail - because the code that implements them isn’t there yet! In a quick application like this, it’s a great way to set out a roadmap for actually completing what it is you sat down at the terminal to write. We’ll be using this introduction to test driven development as your first meaningful introduction to writing web-focused JavaScript.

Unit and integration tests

Unit tests test specific functionality within an app. Once we start adding “business logic” to our application, then we can write some unit tests. These will typically interact with the controllers that expose the functionality of our app, and completely ignore the HTTP/web part of the application. For now, we’re only going to be using integration tests. These test the entire app straight through, as if a real user is using it. For a web app, this means making full HTTP requests directly to a running server.

Ok yeah I’m ready to go but how many tests are we talking here

Each student in your group must write at least six tests. Each of the six categories (registration, login, logging out, etc.) must have at least n tests, where n is the number of students in your group. Each student doesn’t have to write one per category - you can split the categories up by team member however you’d like. Four is probably a good number of tests per category to shoot for though, as these tests might come in handy in later assignments.

The tests will have two components - the English description, and the code implementing the test. As I showed you in class, you should probably write the specific test descriptions before you start in on the code implementing them. You can use the four in the skeleton file under registration as a freebie.

Your tests should be written in such a way that if the app as presented were fully functional, all of the tests would pass. In other words, you cannot assume the existence of additional routes that expose other server side functionality - you need to write tests that will succeed or fail based on the format of each of the loggedin.html and loggedout.html pages.

Restrictions

Because part of this assignment and class is to learn good software engineering habits, each team’s master branch will be protected, and require code review on pull requests. This means that you are literally not allowed to git push origin master. Instead, you’ll need to create a new branch, make all of your changes, push that branch to GitHub, and then use a pull request with a code review to successfully merge something into master. We will only be grading the master branch. If you are not comfortable with using git, get started early. Your code review can be from me/the TA using the grading oracle, but the standard code review should come from someone else in your team.

Grading

Grading will be done manually. If a student writes more than six tests, the score for the highest six will be the earned score. Scores will be shared among all team members rather than individual.

For each test written, the grade breakdown will be:

  • 60%: code functionality for the test. This will either be full credit or a zero in almost ALL cases.
  • 20%: meaningful English description that enumerates a sufficient list of tests for the functionality described in each category. Use the pending “registration” tests as a guide.
  • 20%: good faith effort to write meaningful commit messages / pull request text / review text. Google’s code review best practices are a great place to start learning about code reviews. We won’t be looking for beautiful paragraphs of insightful prose, but mainly evidence that you took the process seriously.

The distribution of code reviews will not be graded - if one person really wants to do all of the reviews, that’s ok with me.

The number of points for each assignment is arbitrary - all homework assignments will be scaled to the same amount of points when they are added to your final grade.

Getting started

Your actual tests will need to send POST requests to the server rather than just GET requests that the skeleton code sends. The axios github page has multiple examples for how to do this. You can also open the browser’s devtools “Network” page to watch your browser make the POST requests that a real client would make - that should help you understand what your axios requests should look like.

Each axios instance will have its own cookie jar - keeping track of its identity as it logs in and logs out. You are allowed to create a new instance to test things that would require more than one user to be interacting with the site.

Grading Oracle

As the Google code review page mentions:

Tests do not test themselves, and we rarely write tests for our tests - a human must ensure that tests are valid.

Along those lines, grading for this assignment will be manual, and unless there is an egregious oversight (i.e. a test would work exactly as you intend it to, even if we thought it wouldn’t), final grades will be final. To compensate for this, we’ll be offering the grading oracle service - if you add me and/or Awais the TA to the code review request, we will review one PR per 24 hours (up until 24h before the deadline). This means that getting started early will give you a MASSIVE BOOST to your grade. I highly recommend getting started right away. Whenever possible we will try to give meaningful feedback/hints if we think something is wrong. You’re still more than welcome to use Piazza to ask questions - don’t use a review request to get feedback on a half complete test, but only on something you think is ready to be graded.

Style points

You can get style points on this assignment by:

  • Adding a test that enforces a style guide on your code.
  • Adding anything particularly useful to .vscode/: auto-linting comes to mind.
  • Sign your commits with GPG.
  • Make the html less ugly (WITHOUT changing anything about the forms/inputs) via a pull request to the skeleton repository. (Note: changes here will not be reflected in your student repositories.)
  • Isolate tests better by running an individual server per test. This howto looks like a good step in that direction.
  • Other cool stuff that you think of. Don’t worry about adding application functionality/routes/tests for functionality besides what’s on the page right now, that will come in later assignments.

Remember, style points do not factor into your final grade in any way, but are meant to be ways for people interested in web development to explore further and learn more.

Submitting your code

Your team GitHub repository is your turnin for this assignment. You can accept this assignment here. Note that working in a group is required. Your new repository should have the master branch protected from direct commits, requiring code review to merge pull requests into master. If not, you still need to do that and any commits directly to master will incur a penalty.

This assignment is due Tuesday, February 4th, 11:59 PM.