How to run all DocTests within a Package?

Mojo
1

When I run magic run mojo test, it didn’t catch all the doctests I have within. Seems like it’s ignoring folders with a __init__.mojo file in it.

2

Hi @Samuel,

Thanks for sharing this question! Test files that you want to run using mojo test can be organized within a directory hierarchy, but the test files must not be part of a Mojo package (i.e. the test directories should not contain __init__.mojo files) – see the testing doc.

You can use either def or fn to define a test function. Because a test function always raises an error to indicate failure, any test function defined using fn must include the raises declaration.

Generally, you should use the assertion utilities from the Mojo standard library testing module to implement your tests. You can include multiple related assertions in the same test function. However, if an assertion raises an error during execution then the test function returns immediately, skipping any subsequent assertions.

You must define your Mojo unit tests in Mojo source files named with a test prefix or suffix. You can organize your test files within a directory hierarchy, but the test files must not be part of a Mojo package (that is, the test directories should not contain __init__.mojo files).

3

Thanks Caroline for the clarification. The issue comes when the files I’m using are not really test files, those are structs and functions that I really want to share as part of a mojo package.

Because of that, I tried to add documentation tests within each struct and function definition. But those documentation tests are not captured by the test command.
As you pointed out, now I understand what’s the reason. But then, why someone will write documentation tests, if the only way to really run those tests is defining the struct out of a package?

In previous versions (like mojo 25.1.0.dev2025013105) it was not really a problem, we were able to test the documentation within packages, but now it’s not possible.

If it’s just the way it should be, no problem, I will move all documentation test to files. Thanks!

4

Thanks for sharing that additional info!

Just to clarify, assuming your file structure is something like the following:

<root>
- folder_a/
  - __init__.mojo
  - foo.mojo
- folder_b/
  - bar.mojo

When you’re running magic run mojo test, are you doing so from within folder_a, or you at the root level?

5

I’m on root level. But even when I cd into folder_a and I try to run mojo test, it’s not working. It only captures the test when I specify the file, like: mojo test folder_a/foo.mojo.

6

Hi @Samuel,

Apologies for the delayed response! This behavior is a result of the fact that we’re in the process of deprecating the Mojo REPL. Docstring tests were previously executed via the REPL. Going forward, we recommend instead setting up a dedicated testing environment and a test action with Magic and using magic run test. We’d also recommend checking out the Mojo standard library test files and MAX examples for examples of how we recommend structuring tests.

1 Like