github-actions[bot]
commented
2 years ago 🤖 🤖
Hi! 👋🏽 👋 Welcome to the Exercism Python Repo!
Thank you for opening an issue! 🐍 🌈 ✨
- If you are requesting support, we will be along shortly to help. (generally within 72 hours, often more quickly).
- Found a problem with tests, exercises or something else?? 🎉
◦ We'll take a look as soon as we can & identify what work is needed to fix it. (generally within 72 hours).
◦ If you'd also like to make a PR to fix the issue, please have a quick look at the Pull Requests doc.
We 💙 PRs that follow our Exercism & Track contributing guidelines!
- Here because of an obvious (and small set of) spelling, grammar, or punctuation issues with one exercise,
concept, or Python document?? 🌟Please feel free to submit a PR, linking to this issue.🎉
‼️ Please Do Not ‼️ ❗ Run checks on the whole repo & submit a bunch of PRs. This creates longer review cycles & exhausts reviewers energy & time. It may also conflict with ongoing changes from other contributors. ❗ Insert only blank lines, make a closing bracket drop to the next line, change a word to a synonym without obvious reason, or add trailing space that's not an[ EOL][EOL] for the very end of text files. ❗ Introduce arbitrary changes "just to change things" . _...These sorts of things are **not** considered helpful, and will likely be closed by reviewers._ |
- For anything complicated or ambiguous, let's discuss things -- we will likely welcome a PR from you.
- Here to suggest a feature or new exercise?? Hooray! Please keep in mind Chesterton's Fence.
Thoughtful suggestions will likely result faster & more enthusiastic responses from maintainers.
💛 💙 While you are here... If you decide to help out with other open issues, you have our gratitude 🙌 🙌🏽.
Anything tagged with [help wanted] and without [Claimed] is up for grabs.
Comment on the issue and we will reserve it for you. 🌈 ✨
bobahop
BethanyG
This issue describes how to implement the
Test Driven Development (TDD)Python Track docs.Getting started
Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read up on the following documents:
Goal
This document is intended to explain basic
Test Driven Development (TDD)practices/philosophies and how exercism adapts those practices. It should orient students to a "TDD Mindset" for iterating on and solving exercism problems on the Python track.Learning objectives
Test Driven Development (TDD)is, and how it can inform and improve the process of coding.TDDprincipals in the design of its concept and practice exercises.Out of scope
This is a fairly high-level and broad document, emphasizing a programming approach or philosophy. The intent here is to explain why exercises are structured the way they are on the Python track (minimal stubs, viewable tests, access to mentoring and community solutions, encouragement for iterating on solutions) and provide resources for students to explore and adapt the TDD technique more fully, rather than set up a programming problem or tutorial. No topic is really "out of scope", as long as it applies to TDD, refactoring, iterating on solutions, reading test files, and writing tests.
Concepts
Proposed Concepts to Cover
- `Test Driven Development (TDD)` - `TDD as design` - `unit tests` & `testing` - `test failure` as a coding guide - `refactoring` as a coding discipline - `test writing`Prerequisites
Since this is a broad track-focused document, there really are no prerequisites.
Resources to refer to
Articles on Test Driven Development
- [Agile Alliance: TDD](https://www.agilealliance.org/glossary/tdd) - [The TDD Manifesto](https://tddmanifesto.com/) - [Martin Fowler: Test Driven Development](https://martinfowler.com/bliki/TestDrivenDevelopment.html) - [Test Driven: Test Driven Development](https://testdriven.io/test-driven-development/) - [Xeno Stack: Test Driven Development](https://www.xenonstack.com/blog/test-driven-development) - [Semaphore Blog: Test Driven Development](https://semaphoreci.com/blog/test-driven-development) - [Guru99: Test Driven Development](https://www.guru99.com/test-driven-development.html) - [Inspired Testing: What Why and How of TDD](https://www.inspiredtesting.com/news-insights/insights/466-what-why-how-test-driven-development) - [Browser Stack: What is TDD](https://www.browserstack.com/guide/what-is-test-driven-development) - [Brian Okken: Lean TDD (_or TDD without the insanity_)](https://pythontest.com/lean-tdd/)Replies on TDD Made to Students in the Python Repo
_Below are some replies made to students in the Python repo when they've had issues with having to read the test files. Feel free to copy, paraphrase or otherwise use them to explain the Python Track's TDD approach:_ > [Twelve Days Issue](https://github.com/exercism/python/issues/3031) However, the directions were never intended to specify the detail that is in the attached test file. > We we practice a form of Test Driven Development (*TDD for short*) on exercism, where we provide the main tests for you (_rather than have you write the tests yourself_). > [TDD](https://www.agilealliance.org/glossary/tdd/) practice has you write tests *before* code, to allow test failure to guide the implementation. So we expect students to look at the [test files](https://github.com/exercism/python/blob/main/exercises/practice/twelve-days/twelve_days_test.py) to figure out what the expected inputs and outputs of their functions should be. >[Second Twelve Days Issue](https://github.com/exercism/python/issues/2983) For [Practice exercises](https://exercism.org/docs/building/product/practice-exercises), we give very minimal stubs. The 'ethos' behind this is that practice exercises are implemented as a form of [test driven development](https://www.agilealliance.org/glossary/tdd/#q), where we've written out the core tests for you ahead of time. You **_should_** be looking at the tests to get a feel for what is expected, and you should let test failure guide what you write in code. > Practice exercises (in contrast to the "learning" or [Concept exercises](https://exercism.org/docs/building/product/concept-exercises)) are meant to encourage practice with multiple techniques in the language and/or algorithms or design decisions. Implementation is much less directed, problem descriptions are less detailed (_and are mostly shared across tracks_) and the test files tend to look for outcomes, and shy away from dictating data structures (_where that's possible_). Often students will discuss with mentors different approaches, and may even add their own additional test cases locally as they work through the problem. > [Gigasecond Issue](https://github.com/exercism/python/issues/3018) We practice a form of Test Driven Development (_TDD for short_) on exercism, where we provide the main tests for you. [TDD](https://www.agilealliance.org/glossary/tdd/) has you write tests _before_ code, to allow test failure to guide the implementation. So we expect students to look at the [test files](https://github.com/exercism/python/blob/main/exercises/practice/gigasecond/gigasecond_test.py) to figure out what the expected inputs and outputs of their functions should be. > [Kindergarten Garden Issue](https://github.com/exercism/python/issues/2856) > 1. By design, the practice exercises (_the exercises that are not in the syllabus tree as the "main" exercises in the boxes_) are implemented as a form of TDD - [Test-Driven development](https://www.agilealliance.org/glossary/tdd/#q=~(infinite~false~filters~(postType~(~'page~'post~'aa_book~'aa_event_session~'aa_experience_report~'aa_glossary~'aa_research_paper~'aa_video)~tags~(~'tdd))~searchTerm~'~sort~false~sortDirection~'asc~page~1)). But in exercism's case, we've written out the basic tests for you ahead of time. **`TL;DR`** - the expectation is that you engage with and look at the tests in addition to the instructions/specification. That doesn't mean we can't do better on the instructions. But it **does** mean that we will probably never get to the point of specifying everything in detail -- because we expect you to explore the test file. > 2. Practice exercises are intended to be as open-ended as possible, and to encourage discussion with a mentor. That means we take pains to **not** dictate implementation. Now for OOP exercises in OOP-supporting languages, some exercises do indeed "dictate" a `class` and/or `method` names. But apart from importing expected `class` and or `method` names, we try not to overly constrict a student to a particular interface. We strive to have the tests look for _results_ -- I don't care how you implemented `Garden` -- I care that when I call `garden.plants("Alice")`, I get back a list that has `["Violets", "Clover", "Radishes", "Clover"]`. Even the parameters listed in the stub are optional -- you could call them anything you like. And for `students`, many [community solutions](https://exercism.org/tracks/python/exercises/kindergarten-garden/solutions?passed_head_tests=true) use a default argument of `None`, rather than use it as positional-only. Again, this is meant to encourage a conversation with a mentor about different possible approaches or techniques. > 3. Stub code for practice exercises is kept to a minimum. While we have been discussing if more detail is warranted, we have been wary of over-specifying or constricting implementation. For now, we are going with bare minimum sans docstrings or typehinting. We might revisit that later this year. > [Lack of Clarity in Python Testing issue](https://github.com/exercism/python/issues/1827)Broadly speaking we’re using Test Driven Development principles — although we’ve written the tests for you — and so part of the Fun is reading the errors that crop up when the tests fail. > The pass statement is there to keep the empty “slug” file from throwing a SyntaxError before the tests can even run. Though there are many exercises, IIRC all have been implemented so you’ve got enough of a “slug” that the tests will run to completion but all tests will fail. This is actually a big improvement over the situation with many other language tracks, where no slug is provided at all. > From the Pangram slug you need only run the tests to encounter the first failure, which will be that False is not returned when “five boxing wizards [...]” is passed into your function. You could respond by putting return False at the bottom of your function, and you’ll pass that test but fail on “Five quacking Zephyrs[...]", and so on. > Via this iterative method you quickly learn the outline of what your implementation needs to do at a minimum. This is a helpful set of skills to acquire and I’m not sure that making the documentation more clear about the implementation (as opposed to about the problem) is really helping you with that. > It’s my hope that everyone starts to read the test suite and understand the constraints they’re trying to meet before they start implementing a solution, as that’s exactly what you’d do when using TDD principles in a work environment.Files to Be Created
Track Document
Since this is a track document, it can be formatted in markdown any way the author desires. However, it should still conform to the Exercism Markdown Specification, and follow all the rules in the Exercism Formatting and Style Guide. Any links should be reference links, and any included images should be placed in the
docs/imagesfolder.Document Entry in
docs/config.jsonSee other entries in the
configdoc. Note that each document displayed on the website needs:configlet, or this generator.docs/<DOCUMENTNAME>.md)Implementation Notes
Help
If you have any questions while implementing this issue, please post the questions as comments in this issue, or contact one of the maintainers on our Slack channel.