Teacher Tool Testing Documentation

[thsparks]

We should do some documentation around the teacher tool, public facing and just to track features for testing.

Overview

The teacher tool is a mechanism for constructing a checklist of requirements and running that list automatically against projects in quick succession. This allows teachers to build a checklist, then easily evaluate any number of projects based on that checklist. Projects must be evaluated one at a time, but with auto-run enabled, you can update the loaded project by providing a new share link, at which point the rules will automatically be re-run on the new project.

You can access the beta version of the teacher tool here: https://microbit.makecode.com/beta--eval

Side note: these notes use rubric/checklist interchangeably. Going forward, "checklist" is the correct term. Tool UI strings still need updating to account for this.

Testable Features

Creating, Editing, and Running a Checklist

1. User can create a new rubric using the "New Rubric" card (or from the "..." action menu)

   • If there is already an "in progress" checklist, a warning will appear asking if you are okay with overwriting it.

   • Screenshots

     

2. User can give the checklist a name

   • Screenshots

     

3. User can add criteria from the catalog using the "Add Criteria" button.

   • Some criteria (like [block] used [count] times) can be added multiple times, others (like Read a GPIO pin can only be added once)

   • Screenshots

     

4. User can remove criteria using the trash button

   • Screenshots

     

5. User can fill in parameters

   • Numeric parameters have a small input and only allow number inputs

   • String parameters can have medium and long sized inputs

   • Block parameters should open a block-picker modal

   • Empty parameters appear in an error state until they have values

   • Screenshots

     

6. User can load a project into the project view by pasting in a share link or share id

   • The project should load in read-only mode

   • The project title should appear at the top of the project view

   • Screenshots

     

7. With a project loaded, user can run the checklist and see results by clicking the "Run" button

   • Button is disabled without loaded project

   • Screenshots

     

Editing Results

1. User can add feedback/notes using the "Add Notes" button

   • The feedback box should resize to fit its content

   • Feedback is persisted if the user re-runs the rules using the "Run" button

   • Screenshots

     

2. User can edit an outcome using the provided dropdown
   • Screenshots

     

Result Clearing and Auto-Run

1. If auto-run is disabled, a result's outcome (i.e. "Looks good", "Needs work", etc...) should be set to "Not started" automatically when any of any of the following conditions are met:

   • It is newly added (should default to the "Not Started" state)
   • A parameter in a rule is changed (only the affected rule should enter the "Not Started" state)
   • The loaded project changes (all rules should be set to "Not started")

2. Auto-run can be toggled on/off using the button in the menu.

   • Screenshots

     

3. If auto-run is enabled, any rules that enter the "Not started" state from the above conditions should immediately and automatically get re-run and have their results updated.

Loading/Importing/Exporting Checklists

1. User can open pre-built rubrics from the home page

   • Will ask for overwrite confirmation if the user already has an in-progress checklist.

   • Screenshots

     

2. User can export a checklist from the vertical "..." menu near the "auto-run" button. This will download a json file.
   • Screenshots

     

3. User can import a rubric from a file using the same "..." menu, or from the card on the welcome page.

   • Rubric file can be selected via "Browse" or dropped directly into the popup

   • Will ask for overwrite confirmation if the user already has an in-progress checklist.

   • Screenshots

     

Other

• If user refreshes the page (or closes/re-opens the browser), their checklist should be preserved.
• User can click the print button to create a version of the results with the outcome and feedback visible, but other UI elements hidden (currently broken).
  • Screenshots

    

• The checklist-view/project-view splitter can be resized. It can also be reset to 50/50 split with double-click.
  • Screenshots

    

[abchatra]

@v-katherine teacher tool documentation here. If you have questions feel free to post in this issue.

[thsparks]

Quick note that the "Catalog" mentioned in Step 3 of "Creating, Editing, and Running a Checklist" is referencing a version of the tool that hasn't been deployed to beta just yet. Should get that pushed within a day or two.

[abchatra]

Related : https://github.com/microsoft/pxt-microbit/issues/5622