pytest-md and pytest-md-report: Markdown reports for pytest
09:43 Share

The standard pytest output is actually pretty good. It's come a long way since I started using pytest. There's nice percentages. Even by default, you can see the test files that ran and all the test cases themselves show up as dots for passing. And then a percent of the test suite complete shows up on the right. It's pretty nice, actually.

And there's ways you can customize it. There's all sorts of ways you can customize it. And we're going to take a look at some plugins that customize it for you. And we're going to start with looking at a couple of PyTest plugins that will generate markdown reports, which is cool.

Welcome to Test & Code. This episode is brought to you by HelloPyTest, the new fastest way to learn PyTest, and by the Python Test community. Find out more at courses.pythontest.com. Taking a look at the top PyTest plugin list, there are a couple plugins listed. At number six, I'm looking at the February list. At number 76 is PyTest-MD, PyTest-MD. That's a plugin for generating markdown reports for PyTest results.

And then down at number 102 is PyTest MD report. That is a PyTest plugin to generate test outcome reports with Markdown table format. So one does Markdown and one does a Markdown table. This is cool. That's what we're going to look at today. Let's start with the first one. PyTest-MD. That is a...

plugin generated by Rafael Pierzina, and it doesn't look like it's gotten a lot of work lately. If I look at PyPI, it shows that it supports up to Python 3.7. Well,

3.8 is still deprecated. So I tried this out. So I'm trying this on Python 3.13.2 and using PyTest 8.3.4 is what I was trying these out on. And it still works fine, even though it hasn't been updated. It's doing some pretty standard stuff that's been supported with PyTest for a long time. And also Raphael is one of the PyTest

Core maintainers, well, he has in the past. It's still kind of fun. So what does PyTestMD do? If you install it, it will pip install it. And then if you pass it in dash dash MD and then give it a file name like report.md, it does the normal stuff, but then it generates a report file.

and this, like, it's just a, it's a markdown format, and it lists kind of a summary of how many tests passed and failed and skipped and everything. Now, you can get a verbose, more verbose output with, if you pass in dash V, and that will give you more detail on each test passing or failing. Actually, if you do dash V, it will list

It'll list every test, even the passing ones, and tell you the times that they ran. It's kind of fun, actually. And it's even incorporated with Emoji. So he has another plugin called PyTest Emoji. And if you have that on also and pass in dash dash emoji and dash V to your report, actually, it doesn't matter if you have the V or not. It'll put little emojis like a happy face for passing. And for error, it's a little angry face. It's cool.

X-Passed is a surprise. Nice. X-Failed is a snooze or like sad. I don't know. Anyway, there's emojis. That's kind of fun. Like I said, it hasn't had a lot of love since 2019. I think it was 2019. Let's take a look at the history. Yeah, last touched in July of 2019. And Raphael did some trainings and some stuff.

presentations around that time. So I don't know if this was associated with something like that. But anyway, you can still take a look at it. It's kind of fun to look at the code. And I it's still it might be useful for you to generate some marketing report. So that's nice. Next up, let's take a look at

PyTestMD report. That is, it's had a little more activity. So that, if I look at the release history, it was started back in 2020 and the most recent release was January of 2025. So that just, just last month. So nice. What does this do? It is

It's generating a report. Oh, it's kind of neat. So the Raphael's pytestmd, it only reports to a file. It doesn't change the standard output. Now, mdreport does change the standard output. So if you have it installed and you pass in dash dash md dash report,

At the end, it will list a table, a markdown table, with, let's see, file path, past, failed, error, skipped, x failed, x passed, and then a subtotal for each of the files. So it's got all these columns for the different types of things.

And the number of tests that are in each column, like the number of passes in a file. And so each file is a row. And that's nice. And they're color-coded. So the failing files are red. The passing, the files that all of the tests are passing are green. And then you've got yellow for skipped, X failed, and X passed. And then the total as the color, like basically if there's any failures, it's red, et cetera, et cetera.

If you, you can have a verbose report, but this is kind of cool. It doesn't, it isn't tied to the dash V. It's got its own verbose flag that you pass in. And instead of per file, then it will list, it still tells you what file it's in, but it adds another column, which is the function. So you get one row for every test function. So that's, it's a bigger table, but it's pretty cool. It's actually a beautiful looking table. Nice.

There's a whole bunch of really cool flags for it too. If you, it'll be like by default, if something's zero, so like if a test file has zero X fails in it,

it'll show up as a zero, but it'll be kind of a light gray zero. So it's, it's pretty, you know, innocuous, but if you don't want any, if you're not, especially if you're not using color, you might not want any zeros in there at all so that it's easier to read. And you can, you can say like set the MD report zeros to empty and that'll like clear those out. Uh, you can also change the color so you can have control over color, uh,

Maybe if you don't want color at all, you can say report color never. And there's a lot of configurations for it. You can set up the configurations in Toml, private project at Toml. Probably your any file too, I imagine. Yeah, I'm sure you can. Yep, it supports any and Toml and setup.cfg. But that's just because it's using

using the same setting system that PyTest is. So that's pretty cool. So what about if you wanted a file? So by default, it's just printing it out, but you can pass it in a file and it'll go to a file instead. And if you want to see it on both the file and the standard output, there's a T flag for that too. So you can have that as well. And what if that markdown file is not quite the same format as you want? So like maybe you want GFM

or the GitHub. Are those different? Anyway, there's a couple different flavors of Markdown that it supports, which is nice. The other thing is maybe you've got a system where you really aren't using XFails, so you don't really need the XFail and XPass column. So if that's the case, you can tell it to just exclude those columns. That's nice. Anyway, really kind of a really fun plugin. I

I think both, neither of them are a lot of code though. They're not super huge. And that's kind of one of the neat things about PyTest plugins. So this is kind of a fun thing to look at. If one of these is closer to what you need, you can take a look at how they're coding this and take a look. And since these are open source, you have access to it, of course. So check those out.

I highly recommend checking out probably both of them, but especially PyTest MD report because I like those color-coded tables. I also really like that the verboseness is separated. Actually, if you pass in dash V, it will do the verbose also, but I think you can turn... Anyway, it's possible to not have your verbose PyTest and still have a per-function report table, so that's cool. Anyway, I think let's...

This is fun talking about different ways you can report. So next episode, I'll probably do a different plugin that also does a different kind of report.

Thank you for listening and thank you to everyone who has supported the show through purchases of the courses, both Hello PyTest, the new fastest way to learn PyTest, and the complete PyTest course, if you'd like to really become an expert at PyTest. Both are available at courses.pythontest.com and there you can also join the Python test community. That's all for now. Now go out and test something.