docs: add "how to run tests" to developer.md #7787
Conversation
| @@ -49,6 +49,13 @@ For more information about the [Remote container extension](https://code.visuals | |||
| New code should be covered by basic unittests. Depending on the complexity of the feature, Reviewers may request more in-depth unittests. | |||
| If necessary, the Freqtrade team can assist and give guidance with writing good tests (however please don't expect anyone to write the tests for you). | |||
|
|
|||
| #### How to run tests | |||
|
|
|||
| Use `py.test` in root folder to run all available testcases and confirm your local environment is setup correctly | |||
There was a problem hiding this comment.
py.test is old terminology - pytest would be correct - and in the meantime probably depecated.
I'm also not entirely sure if we need this here as well - this document does link to the contributing guidelines - which do have detailed instructions on how to run pytest with freqtrade.
There was a problem hiding this comment.
see py.test more as a standin for whatever is actually used. which I didn't know, because it's not documented anywhere in the docs, the first thing I was looking.
my experience today: I was trying to add a new feature, so I looked into the docs to see how tests are run for this project and I couldn't find it. so a simple, "hey this is how you get the ball rolling. having that hidden in another documents is not obvious. it would be better to just make a section. Tests: where are they, how to run them, what to expect and then link to the contributing guidelines for detailed instructions. But it should be stated somewhere, in the docs, how to tests this project from a clean fork
There was a problem hiding this comment.
That's great - as that's exactly how it is now if you read through the developer setup section carefully.
it explains the tools that will be installed and are used as part of development (pytest, mypy, flake8 and coveralls) - with the assumption of developers as audience -> audience knows how to use them, otherwise that's a research project on it's own.
it's then linking to the contributing guidelines for detailed instructions on HOW to use them.
|
I just think if we want people to read docs first basic information should
be in there so it's always the first document to consult instead to hunt
links.
I'm a developer, but I'm not well-versed with python canon and a quick ask
on the discord server gave me 3 different answers on how to run tests.
Putting a quick section in there wouldn't hurt and maybe have a lot of
upside. How many people might never have run tests because they simple
didn't know how to do it? And didn't know how easy it is?
I don't get why you fight me so hard on this. Either you won't people to
use the docs, then it should be first class.
…__
Typed on a mobile, please excuse any typing mistakes or short-spokeness.
On Tue, 22 Nov 2022, 19:22 Matthias, ***@***.***> wrote:
***@***.**** commented on this pull request.
------------------------------
In docs/developer.md
<#7787 (comment)>:
> @@ -49,6 +49,13 @@ For more information about the [Remote container extension](https://code.visuals
New code should be covered by basic unittests. Depending on the complexity of the feature, Reviewers may request more in-depth unittests.
If necessary, the Freqtrade team can assist and give guidance with writing good tests (however please don't expect anyone to write the tests for you).
+#### How to run tests
+
+Use `py.test` in root folder to run all available testcases and confirm your local environment is setup correctly
That's great - as that's exactly how it is now if you read through the developer
setup <https://www.freqtrade.io/en/stable/developer/#developer-setup>
section carefully.
it explains the tools that will be installed (assuming developers as
audience -> audience knows how to use them, otherwise that's a research
project on it's own).
it's then linking to the contributing guidelines for detailed instructions.
—
Reply to this email directly, view it on GitHub
<#7787 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AB6WSHSBCUCPMP4QGTPU2GDWJUFO7ANCNFSM6AAAAAASHVAPMA>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
|
I'm sorry you see this as "fighting hard". The (rendered) documentation is there mostly for Users. it's common convention for open source projects to have a you described your experience - and i told you that apparently, you didn't read the developer section of the documentation in full / follow it's references. I've mentioned that the command used is deprecated (which is a request for change). The "note" part is wrong in other regards (tests are expected to pass on both the stable and develop branch) - but I'm more than happy to ignore that, as you'll have seen, i didn't even mention that in the review above. The problem goes deeper than this though - which is something i'll say upfront - we will not cover as part of documentation. Running/writing tests is either something you're familiar with - alternatively you'll struggle with them anyway and WILL need to do some research/learning upfront - outside of the freqtrade context - as there's a few concepts that - if unfamiliar - make them quite difficult to use (most prevalent example is mocking). |
|
Ok, good you clarified. Sometimes it feels I spent a lot more time arguing than implementing an fix. I think we just have different perspective. I come from a beginners mind. A beginner doesn't have to be somebody that isn't a developer, it can also be somebody new to a language or framework
I for example have been programming python for more than a decade now and have been using test driven development for years but I have never done them together. You have been working on freqtrade far longer. So of course things that seem obvious to you are not to other people with a different experience. I'm arguing for these people, that's why I meant, keep beginners mind in mind. In my opinion it's also one of the most valuable resources if you want to attract contribution. recording the experiences of somebody, coming from all walks of life, who wants to try to engage with a task and see how they might do it and where their experiences starts to fail & gets roadblock. So my report is: I wanted to do TDD but I couldn't even find how tests should be run for this project by looking at the obvious place: the docs. Many others might have left at this point and we most likely wouldn't have heard of them. But since I learned about beginners mind I made a habit out of recording this experiences and trying to at least instigate change for the better. This is this PR. About the exact content, as I think I made clear by now, I don't know how test should be run for the first time. So please add or change everything of my PR as needed so people like me know how you expect others to run tests and verify everything is set up as expected before they start their tests or run I think it will lead to a better developer and beginners experience |
Summary
Adding some hinters to docs about how to run tests for first time