Updates to test execution documentation

[czrpb]

Hi!

Here is my documentation style. Looking forward to many critiques so I can improve! 😄

Closes #906

[github-actions]

Thank you for contributing to exercism/elixir 💜 🎉. This is an automated PR comment 🤖 for the maintainers of this repository that helps with the PR review process. You can safely ignore it and wait for a maintainer to review your changes.

Based on the files changed in this PR, it would be good to pay attention to the following details when reviewing the PR:

• General steps

  • 🏆 Does this PR need to receive a label with a reputation modifier (x:size/{tiny,small,medium,large,massive})? (A medium reputation amount is awarded by default, see docs)

• Any exercise changed

  • 👤 Does the author of the PR need to be added as an author or contributor in <exercise>/.meta/config.json (see docs)?
  • 🔬 Do the analyzer and the analyzer comments exist for this exercise? Do they need to be changed?
  • 📜 Does the design file (<exercise>/.meta/design.md) need to be updated to document new implementation decisions?

---

Automated comment created by PR Commenter 🤖.

[angelikatyborska]

The additions are great! Good job. It reads very well, the wording fits the style of other documents.

Here are some potential improvements that we could make:

I would just want a small change to the information order. In case somebody is impatient, I want them to see at the very top: here's how you run all tests (mix test) and here's how you unskip tests, which are the two basic things you need to know to solve the exercise. Everything else that's "nice to know" but not essential should come afterwards.

This would roughly mean that I would like the beginning of the document to stay as it was, and then after the ## Pending tests section we can start explaining how a test block looks like, which testing framework we're using and what other extra options are there.

As a rule, we try to write all code snippets in a way that they are actual correct code snippets without syntax errors. They don't have to compile, they just need to be semantically correct so the the syntax highlighting will manage to color them correctly. So, to mark a line that doesn't do anything, we would write # ... instead of ... (*), or to mark a string whose content doesn't matter, we would write "..." instead of ....

Another general thing that could be improved is how links are written. We should make use of markdown's link syntax and provide nice link text instead of relying on the platform turning raw URLs into links, so for example, instead of:

Elixir's test execution tool: https://hexdocs.pm/mix/Mix.Tasks.Test.html

Write:

[Elixir's test execution tool](https://hexdocs.pm/mix/Mix.Tasks.Test.html)

(*) PS:... is technically a valid expression in Elixir because three dots are allowed as a variable name, but a lot of highlighting tools don't know that 😁

[czrpb]

all suggestions/recommendations made!

thx!!

[angelikatyborska]

I'm assuming this is ready for review even though the PR is a draft because I can't see anything missing and I will make it not-a-draft :)

[angelikatyborska]

I reviewed how the file exercises/shared/.docs/tests.md is used in practice and I realized it has to be relatively short. Its only usage is to be included in the HELP.md file that students download with each exercise. HELP.md starts with the content of exercises/shared/.docs/tests.md, but then it also includes instructions on how to submit the solution and where to look for help. If exercises/shared/.docs/tests.md would be very long, the students would have a hard time finding instructions on how to submit the solution, which would be pretty bad...

I took all your additions and put them in docs/TESTS.md instead. That file can be as long and detailed as we want. It's rendered here: https://exercism.org/docs/tracks/elixir/tests

[angelikatyborska]

Thank you a lot for your contribution 💜 I'll merge it now. I had to do some other minor changes, I decided to do them myself not to bother you anymore. If I made a mistake there, let me know.

[czrpb]

of course and i hope i was not more effort than value! 😉

and thank you!