Quiz Submission Questions - Index/Show

This patch makes it possible to list the "question records" for a QS
which clients can use to tell what questions are answered, flagged,
etc.

closes CNVS-10025

TEST PLAN
---- ----

Fire up some computer, launch a Canvas instance, create a quiz with a
question or two, take it as a student, answer it, then get ready for
API business:

> Index action - Listing all question records

[GET] api/v1/quiz_submissions/:quiz_submission_id/questions

  - Perform the request
  - Verify you get N entries, one for each question you answered or
    marked
  - Set an "include" parameter with "quiz_question" (ie,
    "?include=user")
    - Verify that the returned set now contains 3 entries:
      1. "quiz_submission_questions" what you saw earlier
      2. "quiz_questions" with Quiz Questions that you answered
      3. "meta" that you can safely ignore

> Show action - Fetching a single question record

[GET] /api/v1/quiz_submissions/:quiz_submission_id/questions/:id

  - Perform the request
  - Verify you get 1 entry
  - Try the "include" parameter as you did in the Index case

As a sidenote, the output of these endpoints should be the same as the
stuff you get when you answer a question (see CNVS-9844), they
basically should tell you what answer you provided if you did, and if
you marked the question or not.

Change-Id: If39b84d8fda77870c3990822ade06bd28b276c3d
Reviewed-on: https://gerrit.instructure.com/27598
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Derek DeVries <ddevries@instructure.com>
QA-Review: Myller de Araujo <myller@instructure.com>
Product-Review: Ahmad Amireh <ahmad@instructure.com>

Author: amireh

app/controllers/quiz_submission_questions_controller.rb

@@ -19,18 +19,91 @@
 # @API Quiz Submission Questions
 # @beta
 #
-
+# API for answering and flagging questions in a quiz-taking session.
+#
+# @model QuizSubmissionQuestion
+#     {
+#       "id": "QuizSubmissionQuestion",
+#       "required": ["id"],
+#       "properties": {
+#         "id": {
+#           "description": "The ID of the QuizQuestion this answer is for.",
+#           "example": 1,
+#           "type": "integer",
+#           "format": "int64"
+#         },
+#         "flagged": {
+#           "description": "Whether this question is flagged.",
+#           "example": true,
+#           "type": "boolean"
+#         },
+#         "answer": {
+#           "description": "The provided answer (if any) for this question. The format of this parameter depends on the type of the question, see the Appendix for more information."
+#         }
+#       }
+#     }
+#
 class QuizSubmissionQuestionsController < ApplicationController
   include Api::V1::QuizSubmissionQuestion
   include Api::V1::Helpers::QuizzesApiHelper
   include Api::V1::Helpers::QuizSubmissionsApiHelper
 
-  before_filter :require_user,
-    :require_quiz_submission,
-    :export_scopes,
-    :prepare_service,
-    :validate_ldb_status!,
-    :require_question
+  before_filter :require_user, :require_quiz_submission, :export_scopes
+  before_filter :require_question, except: [ :index ]
+  before_filter :prepare_service, except: [ :index, :show ]
+  before_filter :validate_ldb_status!, except: [ :index, :show ]
+
+  # @API Get all quiz submission questions.
+  # @beta
+  #
+  # Get a list of all the question records for this quiz submission.
+  #
+  # @argument include[] [String, "quiz_question"]
+  #   Associations to include with the quiz submission question.
+  #
+  # <b>200 OK</b> response code is returned if the request was successful.
+  #
+  # @example_response
+  #  {
+  #    "quiz_submission_questions": [QuizSubmissionQuestion]
+  #  }
+  def index
+    if authorized_action(@quiz_submission, @current_user, :read)
+      render json: quiz_submission_questions_json(@quiz.quiz_questions,
+        @quiz_submission.submission_data,
+        {
+          user: @current_user,
+          session: session,
+          includes: extract_includes
+        })
+    end
+  end
+
+  # @API Get a single quiz submission question.
+  # @beta
+  #
+  # Get a single question record.
+  #
+  # @argument include[] [String, "quiz_question"]
+  #   Associations to include with the quiz submission question.
+  #
+  # <b>200 OK</b> response code is returned if the request was successful.
+  #
+  # @example_response
+  #  {
+  #    "quiz_submission_questions": [QuizSubmissionQuestion]
+  #  }
+  def show
+    if authorized_action(@quiz_submission, @current_user, :read)
+      render json: quiz_submission_questions_json(@question,
+        @quiz_submission.submission_data,
+        {
+          user: @current_user,
+          session: session,
+          includes: extract_includes
+        })
+    end
+  end
 
   # @API Answering a question.
   # @beta
@@ -191,6 +264,10 @@ def flag_current_question(flagged_unflagged)
       false)
   end
 
+  def extract_includes(key = :include, hash = params)
+    Array(hash[key])
+  end
+
   # @!appendix Question Answer Formats
   #
   #  {include:file:doc/examples/quiz_question_answers.md}

config/routes.rb

@@ -1353,6 +1353,8 @@ def ef_routes(context)
     end
 
     scope(:controller => :quiz_submission_questions) do
+      get '/quiz_submissions/:quiz_submission_id/questions', :action => :index, :path_name => 'quiz_submission_questions'
+      get '/quiz_submissions/:quiz_submission_id/questions/:id', :action => :show, :path_name => 'quiz_submission_question'
       put '/quiz_submissions/:quiz_submission_id/questions/:id', :action => :answer, :path_name => 'quiz_submission_question_answer'
       put '/quiz_submissions/:quiz_submission_id/questions/:id/flag', :action => :flag, :path_name => 'quiz_submission_question_flag'
       put '/quiz_submissions/:quiz_submission_id/questions/:id/unflag', :action => :unflag, :path_name => 'quiz_submission_question_unflag'

lib/api/v1/quiz_submission_question.rb

@@ -17,13 +17,38 @@
 #
 
 module Api::V1::QuizSubmissionQuestion
+  include Api::V1::QuizQuestion
 
-  def quiz_submission_questions_json(quiz_questions, submission_data)
-    {
-      quiz_submission_questions: quiz_questions.map do |qq|
-        quiz_submission_question_json(qq, submission_data)
-      end
-    }
+  Includables = %w[ quiz_question ]
+
+  # @param [Array<QuizQuestion>] quiz_questions
+  # @param [Hash] submission_data
+  # @param [Hash] meta
+  # @param [Array<String>] meta[:includes]
+  # @param [User] meta[:user]
+  # @param [Hash] meta[:session]
+  def quiz_submission_questions_json(quiz_questions, submission_data, meta = {})
+    quiz_questions = [ quiz_questions ] unless quiz_questions.kind_of?(Array)
+    includes = (meta[:includes] || []) & Includables
+
+    data = {}
+    data[:quiz_submission_questions] = quiz_questions.map do |qq|
+      quiz_submission_question_json(qq, submission_data)
+    end
+
+    if includes.include? 'quiz_question'
+      data[:quiz_questions] = questions_json(quiz_questions,
+        meta[:user],
+        meta[:session])
+    end
+
+    unless includes.empty?
+      data[:meta] = {
+        primaryCollection: 'quiz_submission_questions'
+      }
+    end
+
+    data
   end
 
   # A renderable version of a QuizQuestion's "answer" record in a submission's

spec/apis/api_spec_helper.rb

@@ -239,11 +239,13 @@ def assert_jsonapi_compliance(json, primary_set, associations = [])
     required_keys << 'meta'
   end
 
+  # test key values instead of nr. of keys so we get meaningful failures
+  json.keys.sort.should == required_keys.sort
+
   required_keys.each do |key|
     json.should be_has_key(key)
     json[key].is_a?(Array).should be_true unless key == 'meta'
   end
-  json.size.should == required_keys.size
 
   if associations.any?
     json['meta']['primaryCollection'].should == primary_set

spec/apis/v1/quiz_submission_questions_api_spec.rb

@@ -37,6 +37,39 @@ def create_question(type, factory_options = {}, quiz=@quiz)
       qq
     end
 
+    def ask_and_answer_stuff
+      @qq1 = create_question 'multiple_choice'
+      @qq2 = create_question 'true_false'
+
+      @quiz_submission.submission_data = {
+        "question_#{@qq1.id}" => "1658",
+        "question_#{@qq2.id}" => "8950"
+      }
+    end
+
+    def api_index(data = {}, options = {})
+      helper = method(options[:raw] ? :raw_api_call : :api_call)
+      helper.call(:get,
+        "/api/v1/quiz_submissions/#{@quiz_submission.id}/questions",
+        { :controller => 'quiz_submission_questions',
+          :action => 'index',
+          :format => 'json',
+          :quiz_submission_id => @quiz_submission.id.to_s
+        }, data)
+    end
+
+    def api_show(data = {}, options = {})
+      helper = method(options[:raw] ? :raw_api_call : :api_call)
+      helper.call(:get,
+        "/api/v1/quiz_submissions/#{@quiz_submission.id}/questions/#{@question[:id]}",
+        { :controller => 'quiz_submission_questions',
+          :action => 'show',
+          :format => 'json',
+          :quiz_submission_id => @quiz_submission.id.to_s,
+          :id => @question[:id].to_s
+        }, data)
+    end
+
     def api_update(data = {}, options = {})
       data = {
         validation_token: @quiz_submission.validation_token,
@@ -97,6 +130,95 @@ def api_unflag(data = {}, options = {})
     @quiz_submission = @quiz.generate_submission(@student)
   end
 
+  describe 'GET /quiz_submissions/:quiz_submission_id/questions [index]' do
+    it 'should return an empty list' do
+      json = api_index
+      json.has_key?('quiz_submission_questions').should be_true
+      json['quiz_submission_questions'].size.should == 0
+    end
+
+    it 'should list all items' do
+      ask_and_answer_stuff
+
+      json = api_index
+      json['quiz_submission_questions'].size.should == 2
+    end
+
+    it 'should restrict access to itself' do
+      student_in_course
+      json = api_index({}, { raw: true })
+      response.status.to_i.should == 401
+    end
+  end
+
+  describe 'GET /quiz_submissions/:quiz_submission_id/questions/:id [show]' do
+    before :each do
+      ask_and_answer_stuff
+      @question = @qq1
+    end
+
+    it 'should grant access to its student' do
+      json = api_show
+      json.has_key?('quiz_submission_questions').should be_true
+      json['quiz_submission_questions'].length.should == 1
+    end
+
+    it 'should deny access by other students' do
+      student_in_course
+      api_show({}, { raw: true })
+      response.status.to_i.should == 401
+    end
+
+    context 'Output' do
+      it 'should include the quiz question id' do
+        json = api_show
+        json.has_key?('quiz_submission_questions').should be_true
+        json['quiz_submission_questions'][0]['id'].should ==
+          @question.id
+      end
+
+      it 'should include the flagged status' do
+        json = api_show
+        json.has_key?('quiz_submission_questions').should be_true
+        json['quiz_submission_questions'][0].has_key?('flagged').should be_true
+        json['quiz_submission_questions'][0]['flagged'].should be_false
+      end
+    end
+
+    context 'Links' do
+      it 'should include its linked quiz_question' do
+        json = api_show({
+          :include => %w[ quiz_question ]
+        })
+
+        json.has_key?('quiz_submission_questions').should be_true
+        json['quiz_submission_questions'].size.should == 1
+
+        json.has_key?('quiz_questions').should be_true
+        json['quiz_questions'].size.should == 1
+        json['quiz_questions'][0]['id'].should ==
+          json['quiz_submission_questions'][0]['id']
+      end
+    end
+
+    context 'JSON-API compliance' do
+      it 'should conform to the JSON-API spec when returning the object' do
+        json = api_show
+        assert_jsonapi_compliance(json, 'quiz_submission_questions')
+      end
+
+      it 'should conform to the JSON-API spec when returning linked objects' do
+        includables = Api::V1::QuizSubmissionQuestion::Includables
+
+        json = api_show({
+          :include => includables
+        })
+
+        assert_jsonapi_compliance(json, 'quiz_submission_questions', includables)
+      end
+    end
+  end
+
   describe 'PUT /quiz_submissions/:quiz_submission_id/questions/:id [update]' do
     context 'answering questions' do
       it 'should answer a MultipleChoice question' do