As far as I can see, there’s nothing TDD-specific under Using Exercism | Exercism's Docs
If we had a document describing test-driven development, and how Exercism uses it, we could have a single place to point for questions/complaints about “the introduction does not contain all the requirements”.
Thoughts?
The Python track has one here. It’s not great (ugh - in re-reading it, it needs some serious love), but it might be a jumping off point for a more general one?
I’m ok with that.
Personally i’m thinking of adding a note in the hello world exercise for the Clojure track and maybe an additional small article in the Clojure track docs.
Great plan! If someone is up for a PR I’ll be happy to review
Where should it reside? I’m thinking under Using Exercism | Exercism's Docs
But should it be in the Solving Exercises submenu?
Solving Exercises submenu sounds good. But maybe also a section with link within the FAQ doc?
What Bethany said!
The location doesn’t really matter given that it would probably need to be linked from various pages. Solving Exercises submenu is perfectly fine.
Before I create a PR, let me get your thoughts on this draft:
Test-Driven Development (sometimes called Test-First Development or Test-Driven Design) is the practice of writing the unit tests first, before you write a single line of implementation code.
While this may seem like putting the cart before the horse, there are several good reasons why you might want to do this:
Design.
It forces you to think first about the design of the interface to the code, instead of jumping straight to the implementation.
Having a well-designed interface is often more important than having an efficient implementation.
Discipline.
Writing tests is often seen as a chore; writing the tests first guarantees that at the end of the day you will have written a suite of unit tests (rather than leaving them until the end and possibly never getting around to it).
Less Work.
If you apply a tight cycle of write one test, then write the code to implement that test, then write the next test, your code ends up growing organically.
This often (though not always) leads to less wasted effort; you end up writing all the code you need, and none of the code you don’t need.
A suite of unit tests have already been written for you.
You will write a solution that contains just enough code to make all the tests pass, and no more.
Many tracks use “skipped” tests.
At first, only the first test is “active”, and all the rest are deactivated somehow (it depends on the track).
When you run the test suite, only the first test runs.
We do this to encourage you to follow this workflow:
Exactly how tests are “unskipped” depends on the track.
For some tracks, it might be commenting or removing an annotation.
For some tracks, it might be changing an attribute from true to false.
Take the time to read the track documentation: it will explain these details.
When you’re working in the code editor on Exercism’s website, you can read the tests but you are not able to edit them.
All the tests will be executed each time you run them, regardless of any “skip” mechanisms.
Don’t be discouraged by a large number of failing tests.
Focus on making them pass one-by-one.
Each exercise you work on will have some instructions describing in general terms what you need to do.
However, these instructions cannot account for any language-specific implementation details because the instructoins are common to all of Exercism’s language tracks.
You have solved an exercise when all the tests pass.
In other words, you are required to write a program that satisfies the tests.
The tests represent the complete requirements for the exercise.
When you start working on an exercise, you will read the instructions carefully (of course).
That will give you the broad overview of how you go about solving it.
But you will have to read the tests to understand exactly what the tests require.
For example:
This looks solid!
More often than not, you can get away with reading the test output and not the test.
Depends on the track, there may not be “actual vs expected” output.
Anyway, I don’t want to reduce the emphasis on the value of the tests.
I like this. 
I do have some proposed rephrasing and re-arranging, but its less critique, and more suggestions.
You can take or leave most of it.
Proposed changes of bullets 1 & 2:
1. Design.
It forces you to think first about the design of the interface to the code, instead of jumping straight to the implementation.
Having a well-designed (and testable!) interface is often more important than having an efficient implementation.
2. Discipline.
Writing tests is often seen as a chore or an afterthought; writing the tests _first_ guarantees that at the end of the day you will have written enough unit tests to cover most or all of your codes functionality (rather than possibly never getting around to it).
Proposed changes of How does Exercism apply TDD?
We've done the work of writing a unit test suite for you.
Your goal is to write a solution that contains just enough code to make all those unit tests pass, and no more.
Should you choose to work with a mentor (and we encourage you to do that once you get the tests passing), they can help you refactor and refine your initial implementation, or even propose new unit tests.
Proposed changes to The tests are the requirements!:
## The tests *are* the requirements!
Each exercise you work on will have some instructions describing in general terms what you need to do.
By design, these instructions do not account for programming-language-specific implementation details because they are shared by all of Exercism’s language tracks.
Sometimes, a language track will append more specific details for you, but it is not a requirement that they do so.
When you start working on an exercise, give the instructions a careful read.
They will give you a broad overview of how you go about implementing a solution.
But you will have to read the _tests_ to understand the full and exact requirements:
- Must the output be in a particular kind of data structure?
- Must the output be sorted in some order?
- How are you expected to handle exceptions? And so on.
You have solved an exercise when all the provided tests run and pass.
In other words, you are required to write a program that **satisfies the given tests**, not an interpretation of the instructions.
**The tests represent the complete requirements for the exercise.**
Proposed changes of the Working in the online editor and Working locally sections (also propose flipping the order):
## Working in the online editor
When you’re working in the code editor on Exercism’s website, you can read the tests but you are not able to edit them.
All tests will be executed each time you run them, regardless of any “skip” mechanisms noted in the test file.
Test results will default to expanding the first failed test message (although what is displayed varies by track).
Don’t be discouraged by a large number of failing tests.
Focus on making them pass one-by-one.
## What about working locally?
Many tracks use “skipped” tests in their test files.
Initially, only the first test is “active” and the remaining are deactivated (how this happens varies by track).
When you run the test suite in your environment, only the first test runs.
We do this to encourage you to follow this workflow:
1. Before adding any new code, run the test suite: you should see a failing test.
2. Add *just enough* code to pass the test.
3. Run the test suite. If the test still fails, repeat the last step.
4. Review your code and refactor as desired, making sure the tests still pass.
5. Once you have passed all the tests, congratulations you’re done!
6. Otherwise, “unskip” the next test and goto 1.
Exactly how tests are “unskipped” (or selected) depends on the track.
For some tracks, it might be commenting or removing an annotation.
For some tracks, it might be changing an attribute from true to false.
Take the time to read the track documentation: it will explain these details.
Propose moving The tests are the requirements to right after How does Exercism apply TDD?, since I think that message is more important than the details of working locally and in the editor. I also think that the working locally / working in editor should be at the same level as all the other headers – just toward the end of the doc, right above the Further reading section.
I would also pay attention and consider “evaluation” as opposed to “output” when it is not output. The language tracks often (but not always) test evaluation rather than output.
Or “results” instead of “output”
I suggest moving this bit to lower down with a level two heading of “Why do people use TDD?”.
Instead I’d focus on why Exercism pushes you towards TDD first as that’ll be why most people are reading this.
So maybe move " The tests are the requirements!" up to the top, maybe renamed to “On Exercism, the tests are the requirements”
I like the the idea of the last clause, but the execution is a bit awkward.
Perhaps:
In other words, your solution is not just an interpretation the instructions that “looks right”, your solution is a program that satisfies the given tests.
@BethanyG @iHiD Thanks for the concrete suggestions. The doc is looking much better. I’ll submit a PR later today.
I’d suggest adding a generic pointer to track specific testing instructions to this document.
It’s really easy to miss the track specific documentation on testing when searching the website UI for places to get help. The top menu of the track contains “About …”, but theres nothing leading to the track docs on that page. The Three-Dot-Menu on the right hides the track documentation very well.
It’s even hard to describe the place, because the Three-Dot-User-Menu is so close to it. So the only “findable” menu entry offering “help” is “Contribute → Docs”. Which leads people looking for help on testing their code to this proposed document about TDD.