Homework 2: Testing an Express CRUD App

This assignment is due before class starts on Monday, October 16.

This assignment has three purposes:

  1. Gain further software engineering skills by writing tests.
  2. Familiarize yourself with writing tests for a web application.
  3. Develop further JavaScript skills through writing asynchronous tests.

The work will be split up as in Homework 1: for each of the six tasks as described in Homework 1, you are to write at least two test cases: one test of successful functionality, and one test of disallowed functionality (i.e. receiving an error message of some kind counts as success). I highly recommend planning your tests in plain English before writing them up and asking for feedback via the grading oracle. You may either write front end or back end tests (check Pete’s code and slides), and you can mix and match if you’d like.

Getting started with Mocha Tests

You are highly recommended to use Mocha but not required to do so for this assignment. Regardless of how you write your tests, you’ll need to make them run as a result of npm test: a quick guide for how to do so is available here.

Refactoring your code to make it testable

It is totally allowed that you modify your CRUD app to make it more easily testable. Rather than working with “business logic” directly in a given function, you can extract the required variables, and then pass them to a function that manipulates state.

On the other hand, “front end” tests are also completely acceptable, but it will be a bit more complicated to write the test acceptance code, as you’ll be extracting data from the DOM as it is returned to the testing code by your app.

Technicalities

All commits must be made with your UIC email address - we’ll be verifying contribution based on commit history. You can update the email address that git uses for your commits with the command git config --global user.email "yournetid@uic.edu. Each group member should contribute tests for 1/3 of all features for groups of size 3, and 1/2 of all features for groups of size 2. Academic integrity rules still apply here: you must write the code you commit. You can discuss how to do so with your group, but you must write your own code.

There will be no more exceptions made for students who cannot set their git commits to their UIC email address correctly.

You are free to use whatever published node modules you’d like as part of your application. You must list which ones you used and why in your design document. You do not need to document code that is provided by the Express application generator if you choose to use it.

For any given package, you can only use “starter”/”example” code from the package’s official documentation. Whenever you use this code (outside of the require statement and any use wiring), either a modified or unmodified version, you must provide a comment with a URL pointing to the documentation, and a plain English description of what the code does. For instance, if I wanted to use the csurf package to defend against cross site request forgery, I would need to have comments that looks like:

Deliverables

  • Design document (README.md) which describes, in plain English:
    • Any “how to run the app” explanation if it isn’t the default (see below).
    • A mapping between student and test cases written for each of the six test cases.
    • A plain English description of all twelve test cases, two per feature.
  • Testing code. Please include the location of test scripts and a plain English description of each test’s purpose in README.md
  • The actual code. If you need any node modules, they should be listed in package.json in the root of the repository. Furthermore, you must set the “start” property of the “scripts” object in package.json such that npm start will start your app. This is done automatically by the Express application generator. You may use multiple source code files, views, etc if you wish.

Grading

Grading will be done via manual inspection. The grader will:

  • Run npm install && npm test in a fresh HTML5 cloud9 instance. If you require the tester to do anything beyond that, explain clearly what they need to do within a fresh HTML5 cloud9 instance to run your app. You should listen on port 8080 to make running inside of cloud9 easy.
  • The tester will, in whatever order they choose, manually exercise each of the six features in your application. They may choose to do them in any order, they may do some tasks repeatedly.

Grading oracle

This assignment is due before class start time on Monday, October 16. Due to the manual and potentially subjective nature of grading, if you have any questions regarding whether you have sufficiently implemented a given feature, we will provide a grading oracle service. This will be similar to code reviews, but for grading. Each group is allowed, once every 24 hours (with the exception of the last 24 hours before the deadline - none will be accepted then), to send a review request. The process will work like this:

  • Write your contribution to the assignment in a repository fork. You can learn about the GitHub flavored forking model of software development here.
  • Add me and the TA as collaborators on your team repository.
  • Create a pull request on your team repository. Be as concise and descriptive as you can with what you’ve done, how to run it, and what feature you’d like tested.
  • Request a pull request review from us (at most once per 24 hours).
  • Wait at most 24 hours for us to respond. I make no guarantees of any response in any amount of time less than that.
  • If for any reason we can’t successfully test your code (we follow your instructions and node doesn’t start correctly, a file that’s needed for correct operation doesn’t exist in the repository…), we’ll let you know what error we got. We’ll be descriptive, but we won’t debug the process with you (outside of your next PR request). This expends your grading oracle request for that 24 hour period.
  • You’ll get a full credit/failed bit of information feedback at minimum. Any other feedback will be at our discretion.
  • You may only request one feature be tested at a time. If it takes me more than 2 minutes from clone to test complete, we reserve the right to tell you that the test timed out.
  • You are only guaranteed a response if you request review from both of us, and it’s up to us to decide who reviews it. If you get a review from one of us, the other won’t also test it.
  • We’re keeping track of the 24 hour limit manually for now. You’ll get one warning if your group sends more than one review request within a 24 hour window. A second “too soon” review request will lock your team out of oracle requests for the rest of the class.

Note that getting positive feedback here does not guarantee that you will get credit for that feature. Regressions are real. If you somehow introduce a regression later on, you could still lose those points.

Once the deadline has passed, the grading decision of the grader is final unless the decision is deemed completely unacceptable by us. The sooner you get started, the more you can take advantage of the oracle.