This week, Matt and I were converting pagination in an app to Ajax pagination. In the process, we broke the build.
The failing feature looked something like this:
When I follow "Next page"
And I comment on "Ford" with "Fjord is a better name for a car."
Then I should be on the second page
And I should see the "Fjord is a better name for a car." comment
The implementation of “I should be on the second page” expected that this query string existed: page=2. When we switched to use Ajax, we could no longer check the query string in the same way.
We came up with the following implementation, and used Akephalos to make sure the Javascript was integrated into the test:
When I follow "Next page"
And I comment on "Ford" with "Fjord is a better name for a car."
Then the comment on "Ford" should have been made via Ajax
And I should see the "Fjord is a better name for a car." comment
It uses this code from features/support/ajax_recorder.rb:
class AjaxRecorder
def self.clear
@@records = []
end
def self.save(env)
@@records << env
end
def self.has_path?(path)
@@records.any? { |record| record['REQUEST_URI'] == path }
end
end
class AjaxRecorderApp
def initialize(app)
@app = app
end
def call(env)
if env['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest'
AjaxRecorder.save(env)
end
@app.call(env)
end
end
Capybara.app = AjaxRecorderApp.new(Capybara.app)
Before do
AjaxRecorder.clear
end
If it’s not clear, we wrote a Rack app that records Ajax requests into the @@records class variable on AjaxRecorder, and inserted it as middleware into our Cucumber/Capybara/Akephalos stack.
We were then able to use AjaxRecorder.has_path? via RSpec in features/step_definitions/ajax_steps.rb:
Then /^the comment on "(.*)" should have been made via Ajax$/ do |value|
response = fetch_moderated_response(value)
path = clients_moderated_response_moderated_comments_path(response)
AjaxRecorder.should have_path(path)
end
One reason this might be insane is that it appears to be testing implementation instead of behavior. Users don’t care about “Ajax”, they care that the site loads the new comment quickly, on the correct page.
There are at least two advantages to this test, however:
There are certain factors of a web application that are important but a little difficult to capture in Cucumber scenarios. Factors like:
Maybe they’re not impossible to capture if we’re willing to use implementation details such as XMLHttpRequest as a proxy for those factors, then tie that implementation to our user experience intent using language in our Cucumber steps:
Then the comment on "Ford" should have been posted quickly, without reloading the page, and with brief visual feedback
“without reloading the page” would be implemented using our AjaxReloader, “posted quickly” could be implemented using a timer/benchmark, and “brief visual feedback” could check that we pulsed/highlighted the new comment.
What do you think? Is this insane?
A recipe for adding searching and filtering to your Rails app.
Provide faster feedback for users. Increase the chance that they’ll find what they want.
Side note: This feature is testing the non-Javascript path through the app. I’m not going to show any Javascript testing in this recipe. The thoughtbot team has been trying to settle on a Javascript integration strategy that we’re happy with. We’ve tried some things but aren’t in love with anything yet.
Scenario: Search by fieldnotes
Given a project exists with a name of "Big Dig"
And the following reports exist:
| name | fieldnotes | project |
| Traffic Control | Barricade | name: Big Dig |
| Gases, Vapors | Dust | name: Big Dig |
When I sign in as a safety manager of "Big Dig"
And I go to the "Traffic Control" report page
And I search for "Dust"
Then I should be on the reports page
And I should see "Gases, Vapors"
And I should not see "Traffic Control"
And the search field should contain "Dust"
The following #{factory_name.pluralize} exist: step definition comes for free with Factory Girl. Note the extra cleverness FG has with the name: #{project_name} field in the table. Real time-saver.
I know I’m going to be writing multiple search scenarios so I created some step definitions for search:
When /^I search for "([^\"]*)"$/ do |query|
When %{I fill in "search-field" with "#{query}"}
And %{I press "Search"}
end
Then /^the search field should contain "([^\"]*)"$/ do |query|
field_with_id("search-field").value.should == query
end
I know I want search-field because the designer, Fred, has already sliced the HTML and CSS.
Another side note: field_with_id comes from Webrat::Locators but Joe is starting to advocate for a nicer abstraction called NamedElements that wouldn’t require writing your own step definitions.
The search box:
<% form_tag reports_path, :method => :get do %>
<%= text_field_tag "query", params[:query], :id => "search-field" %>
<%= submit_tag "Search", :id => "search-reports-button" %>
<% end %>
Only thing that might be of note is using params[:query] to get the ‘And the search field should contain “Dust”’ test to pass.
The filters:
<div id="filter-list" style="display: none;">
<form id="filters">
<!-- a bunch of checkboxes -->
</form>
</div>
The results:
<tbody class="striped" id="reports-tbody">
<%= render :partial => "report", :collection => @reports %>
</tbody>
The index action:
def index
@reports = Report.search(params)
if request.xhr?
render :partial => "/reports/report", :collection => @reports
end
end
There’s some authorization around scoping results to the current user’s project that I’ve removed for brevity.
There’s about a dozen different ways this data can be filtered. There’s specs for each kind that look something like this:
it "should find reports assigned to any of a set of safety inspectors" do
first = Factory(:safety_inspector)
second = Factory(:safety_inspector)
third = Factory(:safety_inspector)
find_me = Factory(:report, :safety_inspector => first)
me_too = Factory(:report, :safety_inspector => second)
not_me = Factory(:report, :safety_inspector => third)
reports = Report.search({ :safety_inspectors => "#{first.id},#{second.id}" })
reports.should include(find_me)
reports.should include(me_too)
reports.should_not include(not_me)
end
There’s one for sending a text query, and a giant one that tests combinations.
The method through which all searching and filtering passes:
def self.search(params)
full_text_search(params[:query].to_s).
location_in(params[:locations].to_s).
safety_inspector_in(params[:safety_inspectors].to_s).
safety_category_in(params[:safety_categories].to_s).
created_after(params[:from].to_s).
created_before(params[:to].to_s).
severity_in(params[:severities].to_s).
state_in(params[:states].to_s).
descend_by_severity_and_created_at.
distinct
end
Most items in this chain are custom class methods that wrap Searchlogic:
def self.location_in(locations)
return no_op if locations.blank?
location_id_equals_any(locations.to_array_of_ints)
end
named_scope :distinct, :select => "distinct reports.*"
named_scope :no_op, {}
The no_op is our way of maintaining chainability in the common cases where most searching and filtering criteria is blank. We don’t even want the SQL to be built for blank options. Maybe we should patch this upstream to Searchlogic?
The array of ints is a custom String extension:
class String
def to_array_of_ints
self.split(',').collect { |integer| integer.to_i }.to_a
end
end
The idea here is to do all filtering on highly indexed integers, which Postgres handles quickly. It’s also easy to pass in comma-separated ids from jQuery as we’ll see later.
“Full text search” is just SQL LIKEing while avoiding SQL injection:
def self.full_text_search(query)
return no_op if query.blank?
text_search(query)
end
named_scope :text_search, lambda {|query|
{
:joins => "INNER JOIN locations ON locations.id = reports.location_id
INNER JOIN users ON users.id IN (reports.safety_inspector_id, reports.supervisor_id, reports.subcontractor_id)",
:conditions => ["(reports.fieldnotes ILIKE :query) OR
(reports.name ILIKE :query) OR
(locations.name ILIKE :query) OR
(users.name ILIKE :query)", { :query => "%#{query}%" }]
}
}
Bind all the necessary events:
$(document).ready(function() {
$('#clear-filters-btn').click(function() {
$('#filters :checked').attr('checked', false);
$('#slider').slider('values', 0, $('#slider').slider('option', 'min'));
$('#slider').slider('values', 1, $('#slider').slider('option', 'max'));
searchReports();
});
$("#filter-list-btn").click(function(){
$(this).toggleClass("active");
$("#filter-list").slideToggle("500");
return false;
});
$('#search-field').keyup(searchReports);
$('#filters :checkbox').click(searchReports);
$('#filters :text').focus(searchReports);
});
Build the Ajax call with jQuery.param and call it:
function searchReportsURL(){
var params = {
'query' : escape($('#search-field').val()),
'locations' : checkedIdsForFilter('location'),
'supervisors' : checkedIdsForFilter('supervisor'),
'safety_categories' : checkedIdsForFilter('category'),
'severities' : checkedIdsForFilter('severity'),
'states' : checkedIdsForFilter('state'),
'risk_profiles' : checkedIdsForFilter('risk-profile'),
'from' : $('.left-handle').text(),
'to' : $('.right-handle').text()
}
return '/reports?' + $.param(params) + '&' + (new Date()).getTime();
}
var searchReportsTimeout = null;
function searchReports() {
if (searchReportsTimeout) {
clearTimeout(searchReportsTimeout);
}
searchReportsTimeout = setTimeout(function() {
$.get(searchReportsURL(),
function(data) {
$('#reports-tbody').html(data);
$(document).trigger('stripeRows');
}
);
}, 500);
}
For brevity, I’ve omitted some helpers like checkedIdsForFilter that build a comma-separated list of ids for each criteria. You can figure that out based on your own markup and Javascript’s replace() method.
I kept the timeout, however, because I think it’s important for the user experience. Without it, the search will happen too fast on every keyup(), resulting in a herky-jerky experience. There’s a half-second pause now, but that’s preferred over “strobe-lighting” the user.
Appending the date to the end of the URL is a cache-buster for Internet Explorer.
Bon appétit!
I’m still in the 101 classes of jQuery culinary school, which is why I’m excited about thoughtbot teaming up with Bocoup to provide our first jQuery class in June.
If you’re not familiar with Bocoup, they’ve been setting Boston afire recently with their torrid pace of about one Javascript event a week at their loft, where this training will also be held.
Hope to see you there!
