Hacker News Reader

Comment by multani | Hacker News Reader

Python also has doctest https://docs.python.org/3/library/doctest.html since ... a long time now.

The documentation tools are not as advanced as Go's and as far as I know, there's no way to "run the examples" yourself.

It's a great way to write tests for some functions though, to me the sweet spot is for small, without side effects functions. It's totally possible for bigger functions but then all the initialization code and assertions can easily get in the way and make the documentation not super clear.

View on HN

Dude doc tests are the one thing I really really miss when I moved over from working on python backend to a typescript backend…

Actually unittest as a whole, testing in ts/JS feels like a mess, everything is just fanned out everywhere, there has been such a lack of structure in our codebase. I’m sure there are examples of well organized testing suites, but I’ve yet to find them.

Thing is, most testing frameworks/libraries in JS gives you a lot of freedom to structure the overall testing architecture however you want, without being much picky about it. That means teams writing the tests have to carefully consider their testing architecture, treating it like production code. But most people don't consider testing code "production" code, they treat it like something they should be able to write once and then kind of forget about it.

So zero regard for architecture will lead to "everything is just fanned out everywhere" and "lack of structure", no matter what language you're using, not just JS. What you're talking about tells us more about your team's engineering practices than how messy the JS testing ecosystem is.

I agree 100% with the statement that it tells us more about our engineering team practices, but the question I have is, how to get it better? Python provides rich built ins, which make it easy to compose a rich suite.

It appears that no one else has an issue with it in my group, but I’m the oddball, these guys come from a TS/JS background. They don’t appear to express concern with it.

Are there resources that you can recommend that I can use to get better?

I was blown away this year when I realized Django REST Framework was reading comments from classes to generate docs, for example the welcome message on this page [0] comes from a comment in the code.

[0] https://govscent.org/api/

I've come to really love Python, in all its somewhat slow glory.

Since 2001, it seems: https://github.com/python/cpython/blob/3.11/Lib/doctest.py#L...

I don't know why you'd need to run an example apart from when running tests. After all, the examples have been tested to output what the example says.

That can be useful because the doc website turns into some kind of sandbox where you can tweak directly the test function and see the result without having to write the code yourself.

Reply on news.ycombinator.com