DocCode "Teaching Tests"

DocCode is the code companion to the Breeze documentation. Every code snippet you read should be present as a working example somewhere in the DocCode. Please let us know if we missed one.

DocCode helps you experience Breeze features as running code. It consists of a battery of QUnit automated tests we call "Teaching Tests". You can add new tests to explore aspects of Breeze that interest you. If you think your new Teaching Test could benefit others, please send it to us and we’ll put it in a nice spot, with kudos to you. The Breeze community thanks you in advance.

Video

The following video shows you how to use the DocCode sample.

The video is slightly dated. The "Basic Breeze" test modules make use of the Todo Sample application's model and server-side controller. A copy of the Todo application used to be embedded in DocCode. Rather than maintain two copies of the same application, we removed the client-side Todo app from DocCode. We refer you now to the single, stand-alone version of the Todo sample application.

The first part of the video explains the Todo application which is the context for the "Basic Breeze" tests; the DocCode  test framework walk-through begins at 4:58.

Setup

  1. Open the DocCode solution in Visual Studio 2010 or 2012.
  2. Build it. It may take a while to download the NuGet packages.
  3. Look at the output window when it’s finished building. There should be no errors, warnings or messages.

Run the tests

Start the app, either with debugging (F5) or without debugging (Ctrl-F5). The browser launches, displaying test results as shown in this snapshot:

QUnit lists each test by its module name and test name. Clicking the test row opens a window showing the message output by each of the test’s asserts in the test … as seen in this close up.

Double click the test name or click the faint Rerun link on the right to run just that one test.

Tests are grouped in modules. Each module is dedicated to a topic or theme such as entityTests. Run just the tests of a single module by picking it from the combo-box in the upper right of the toolbar:

Click the title, “Breeze Documentation Test Suite”, to get back to the full suite.

Tests are grouped in modules. Each module is dedicated to a topic or theme such as “entityTests”. Each module is in its own JavaScript file in the tests folder.

The test scripts were within the Scripts/tests folder prior to Breeze release v.1.2.2. They've been promoted to the root for greater clarity.

Open tests/testRunner.js and scroll down to a require method call that looks a bit like this:

require(["testFns" // always first

    // The test modules to run (prefix with comma):  
    , "basicTodoTests"
    , "queryTests"
    , "entityTests"
    // ... more test module names

], function (testFns) {
    // Configure testfns as needed prior to running any tests

    QUnit.start(); //Tests loaded, run tests
});

Each entry in the array is a module name that concentrates on a particular facet of application development. The module name also corresponds to a JavaScript file in the tests folder.  You can learn more about the structure of our test modules later; for now we’ll just peek inside a module and look at a typical test.

Open tests/basicTodoTests.js. There’s a bunch of setup ceremony at the top that shouldn’t concern us right now. 

Scroll to the first test, which might be

test("get all todos (condensed)", 1, function () {

    var query = new EntityQuery("Todos");

    verifyQuery(newEm, query, "all todos query");
});

The string “get all todos (condensed)” is the test name. It appears in the test output and it strives to be meaningful. We hope you will scroll through the tests to find the ones that interest you.

This test only has two lines: a query definition followed by a testFns helper that runs the query and makes sure it returned something.

Many tests have more lines because they are trying to both show you how to execute the query and explore the consequences. Even so,  most of the time in this documentation we pick out just the one key line:

var query = new EntityQuery("Todos");

The surrounding test code is your opportunity to see that one line in context. Add some breakpoints and step through it. Make a copy, add your own twists, and see if it still runs. A later topic will cover testing Breeze applications with QUnit in more detail so you can see what’s happening under the hood.

Sample Code Persistence Services

The sample code relies on two backend persistence services, both implemented as ASP.NET Web API controllers [1].

The first is the Web API TodosController from the Breeze Todos application. The controller calls upon an Entity Framework “code first” model with a single entity, mapped to the Todos database which only has one table. While patently simplistic, it does have two virtues from our point of view: it’s easy to understand and it’s easy to rebuild. After messing it up with saved changes, we can quickly restore it to a known state.

The second service controller is the NorthwindController. It also talks to a “code first” Entity Framework model but this one is backed by the “Northwind” SQL Server database [2] which has 17 interrelated tables

Northwind stores data for the “Northwind” company whose seven employees sell a variety of strangely named food products to some 90+ customers. The database holds orders placed with those customers. Each order has associated order line items called “OrderDetails”.

The Northwind schema betrays a history of dubious decisions, typical of real world databases. Primary keys are inconsistent (guids, integers, strings). The OrderDetail table has a two-part key {CustomerID, EmployeeID}. The employee’s picture is in one of Employee table columns, making the full employee entity an unnecessarily heavy choice in most UI scenarios. These peculiarities afford opportunities to demonstrate such distinctive features as exclusion of a heavy-weight image property with a projection query.

Notes

[1] A breeze application doesn’t have to depend upon .NET or any server-side technology. It doesn’t depend upon ASP MVC 4, IIS, Entity Framework, SQL Server, Visual Studio, NuGet, MVVM, or Knockout … although all of these technologies play a part in supporting the teaching tests and the Todo sample application. We chose them for convenience: they are easy to setup, they play well together, and they play well with breeze. But you’re not stuck with any of them.

 [2] The Northwind database referenced by this test suite is IdeaBlade’s slightly altered version of the well-known Northwind sample database from Microsoft.