Writing CST Feedback - epi-workbench/EWBTemplates GitHub Wiki
This page is a reference for writing Code Submission Test (CST) feedback messages for Epi-Workbench coding exercises. It is not intended to comprehensively document the testthat package or all aspects of writing CSTs. Instead, this guide is intended for course authors who are already familiar with writing CSTs and want quick, practical guidance on how to write clear, helpful, and consistent feedback messages that appear when a test fails.
The focus here is on writing clear, helpful, and consistent feedback messages, particularly when a CST (Code Submission Test) fails. These messages appear automatically unless overwritten by a custom info message or a call to testthat::fail().
Page Contents
- When to Use Custom Feedback Messages
- Writing Good Feedback Messages
- Adjusting Feedback By Exercise Type
- CST Feedback vs. Hints
- Examples of Feedback Messages
When to Use Custom Feedback Messages
The default CST feedback messages are identical to those returned by testthat. However, default messages are often too technical or vague for beginners. Therefore, course authors should write a custom failure message for every CST.
As of this writing, testthat does not offer a straightforward or consistent mechanism for defining custom success messages. Therefore, success messages are generally left to the default behavior.
Writing Good Feedback Messages
[!IMPORTANT] EWB Culminating Exercises
- The feedback guidance in this section is for coding exercises and labs only.
- In culminating exercises, CST feedback should be intentionally minimal to create an appropriate step up in difficulty from the lab. See Adjusting Feedback By Exercise Type for details.
Good feedback messages:
- Are short (ideally 1–2 lines)
- Point out where the issue is, not necessarily how to fix it
- Guide rather than give away the answer
- Use consistent tone and phrasing across exercises so that learners know what to expect
- Often take the form of a question instead of a statement
- Avoid showing exact code unless it's a mechanical error (e.g., a typo)
Examples
❌ “This is wrong.”
✅ “Did you create an object named alc_1? It looks like the code above creates an object named alc_2.”
❌ “Set skip = 1?”
✅ “Did you remember to set skip = to the correct value?”
❌ “Use read_csv() instead.”
✅ “Did you use the correct function to read comma-separated values?”
Adjusting Feedback By Exercise Type
Feedback tone and depth should match the exercise type and the learner’s stage in the course.
| Exercise Type | Feedback Style |
|---|---|
| Basic coding exercise | Friendly and guiding. More direct feedback is acceptable, especially when introducing new concepts — including showing the correct answer if appropriate. |
| Lab exercise | Still guiding, but less prescriptive. Feedback should encourage synthesis and reinforce prior concepts without giving away full solutions. |
| Culminating exercise | In culminating exercises, CST feedback should be intentionally minimal to create an appropriate step up in difficulty from the lab. Instead of providing targeted, guiding messages, culminating exercise CSTs use a single generic feedback line: It looks like your code isn’t quite right. Try again or open a hint if you get stuck. This approach shifts more responsibility to the learner, reinforces independent debugging skills, and mirrors real-world analytic workflows where detailed, line-by-line feedback is rarely available. Learners can still access more explicit guidance through the hint system — at a knowledge points (KP) cost — preserving support without reducing the challenge of the culminating assessment. |
Think of it as a spectrum: direct and supportive early on, gradually shifting to subtle and reflective as learners build confidence and independence.
CST Feedback vs. Hints
| CST Feedback | Hints | |
|---|---|---|
| When shown | Automatically on incorrect submission | Manually when learner requests help |
| Tone | Subtle, light, non-directive | More detailed, layered, and explanatory |
| Form | Guiding questions or location-specific nudges | Bulleted tips with optional section titles |
| Content | Where the issue is, not how to fix it | Conceptual scaffolding, partial or complete solutions allowed |
Think of CST feedback as a polite tap on the shoulder and hints as a clue after raising your hand.
Examples of Feedback Messages
[!NOTE]
2025-07-23: This section is still under development.