can.fixture

Use

can.fixture intercepts an AJAX request and simulates the response with a file or function. Use them to develop JavaScript independently of the backend services.

The following simulates a GET request to /recipes:

can.fixture("GET /recipes",function(){
  return [
    {id: 1, name: "omelette"},
    {id: 2, name: "hot dog"}
  ];
});

Requests made to GET /recipes with can.ajax, jQuery.ajax,or jQuery.get will receive the data returned by the fixture function above:

$.get("/recipes",function(data){
  assertEqual( data.length, 2 )
})

There are two common ways of using fixtures. The first is to map Ajax requests to another file. The following intercepts requests to /tasks.json and directs them to fixtures/tasks.json:

can.fixture("/tasks.json", "fixtures/tasks.json");

The other common option is to generate the Ajax response with a requestHandler function. The following intercepts updating tasks at /tasks/ID.json and responds with updated data:

can.fixture("GET /tasks/{id}",function(request,response){
  return {id: request.data.id, name: "fix tires."}
})

A requestHandler function's response argument can be used to specify even more details of the Ajax response:

can.fixture("GET /tasks/{id}",function(request,response){
  response(
    200,
    "success",
    {id: request.data.id, name: "fix tires."},
    {location: "/tasks/"+request.data.id})
})

Read more about requestHandler and its response argument on their own documentation pages.

Templated Urls

Often, you want a dynamic fixture to handle urls for multiple resources (for example a REST url scheme). can.fixture's templated urls allow you to match urls with a wildcard.

The following example simulates services that get and update 100 todos.

// create todos
var todos = {};
for(var i = 0; i < 100; i++) {
  todos[i] = {
    id: i,
    name: "Todo "+i
  }
}
can.fixture("GET /todos/{id}",
  function(request, response, headers){
    // return the JSON data
    // notice that id is pulled from the url and added to data
    response(todos[request.data.id]);
  })

can.fixture("PUT /todos/{id}",
  function(request, response, headers){
    // update the todo's data
    can.extend(todos[request.data.id], request.data );
    response({});
  })

Notice that data found in templated urls (ex: {id}) is added to the request's data object.

Simulating Errors

The following simulates an unauthorized request to /foo.

can.fixture("/foo",
  function(request, response) {
    response(401,"{type: 'unauthorized'}");
  });

This could be received by the following Ajax request:

can.ajax({
  url: '/foo',
  error : function(jqXhr, status, statusText){
    // status === 'error'
    // statusText === "{type: 'unauthorized'}"
  }
})

Turning off Fixtures

You can remove a fixture by passing null for the fixture option:

// add a fixture
can.fixture("GET todos.json","//fixtures/todos.json");

// remove the fixture
can.fixture("GET todos.json", null)

You can also set on to false:

can.fixture.on = false;

Bypassing Fixtures

While there are few cases where you would need to, it is possible to bypass a fixture completely, without turning off fixtures globally. This is done by passing fixture: false to your AJAX settings. This will prevent can.fixture from trapping your request, and actually send it to the server.

// add a fixture
can.fixture('POST /foo', '//fixtures/foo.json');

// Send AJAX call to server, even if fixtures are on
can.ajax({
    type: 'POST',
    url: '/foo',
    fixture: false
});

can.fixture.store

store makes a CRUD service layer that handles sorting, grouping, filtering and more. Use it with a can.Model like this:

var Todo = can.Model.extend({
  findAll : 'GET /todos',
  findOne : 'GET /todos/{id}',
  create  : 'POST /todos',
  update  : 'PUT /todos/{id}',
  destroy : 'DELETE /todos/{id}'
  }, {});

var store = can.fixture.store(100, function(i) {
  return {
    id : i,
    name : 'Todo ' + i
  }
});

can.fixture('GET /todos', store.findAll);
can.fixture('GET /todos/{id}', store.findOne);
can.fixture('POST /todos', store.create);
can.fixture('PUT /todos/{id}', store.update);
can.fixture('DELETE /todos/{id}', store.destroy);

Testing Performance

Dynamic fixtures are awesome for performance testing. Want to see what 10000 files does to your app's performance? Make a fixture that returns 10000 items.

What to see what the app feels like when a request takes 5 seconds to return? Set delay to 5000.

Since response is called asynchronously you can also set a custom fixture timeout like this:

can.fixture( "/foobar.json", function(request, response){
  setTimeout(function() {
    response({ foo: "bar" });
  }, 1000);
})

Organizing fixtures

The best way of organizing fixtures is to have a 'fixtures.js' file that steals can/util/fixture and defines all your fixtures. For example, if you have a 'todo' application, you might have todo/fixtures/fixtures.js look like:

steal({
        path: '//can/util/fixture.js',
        ignore: true
      })
      .then(function(){

  can.fixture({
      type: 'get',
      url: '/services/todos.json'
    },
    '//todo/fixtures/todos.json');

  can.fixture({
      type: 'post',
      url: '/services/todos.json'
    },
    function(request, response, settings){
        response({
            id: Math.random(),
            name: settings.data.name
        })
    });

})

Notice: We used steal's ignore option to prevent loading the fixture plugin in production.

Finally, we steal todo/fixtures/fixtures.js in the app file (todo/todo.js) like:

steal({path: '//todo/fixtures/fixtures.js',ignore: true});

//start of your app's steals
steal( ... )

We typically keep it a one liner so it's easy to comment out.

Switching Between Sets of Fixtures

If you are using fixtures for testing, you often want to use different sets of fixtures. You can add something like the following to your fixtures.js file:

if( /fixtureSet1/.test( window.location.search) ){
  can.fixture("/foo","//foo/fixtures/foo1.json');
} else if(/fixtureSet2/.test( window.location.search)){
  can.fixture("/foo","//foo/fixtures/foo2.json');
} else {
  // default fixtures (maybe no fixtures)
}