Add the UnitTest trait as a marker for classes and objects that should be automatically discovered and constructed/executed as unit tests for hardware written in Chisel.

Also add a new chisel3.UnitTests main which discovers all unit tests in the classpath and generates the FIRRTL output for them. The discovery mechanism is roughly the same as implemented in ScalaTest, which scans the classpath for JAR files and directories and then tries to guess class names based on the encountered file structure. This feels pretty brittle, but has been working reliably for ScalaTest for a long time, so chances are this will work for Chisel too.

The utility offers a few options to list all available unit tests, or filter them according to inclusion or exclusion regular expressions. This allows unit tests of only the current package or a subset of the current project to be discovered and built. This is particularly useful if a Chisel project depends on libraries such as rocket-chip or by necessesity Chisel itself, whose unit tests are likely not of interest to that project.

Classes and objects can be marked as unit tests as follows:

package magic

class TestA extends UnitTest {
  Definition(new MyAdder(1))
  Definition(new MyAdder(42))
  // ...
}

object TestB extends UnitTest {
  for (i <- 1 to 4)
    Definition(new MyMultiplier(i))
  // ...
}

The chisel3.UnitTests utility can then be execute, for example through mill or a standalone binary:

# List all unit tests:
> mill chisel[].runMain chisel3.UnitTests -l
magic.TestA
magic.TestB
some.other.package.TestX

# Produce FIRRTL output for all unit tests:
> mill chisel[].runMain chisel3.UnitTests -o tests.fir

# Filter tests according to a regex:
> mill chisel[].runMain chisel3.UnitTests -l -f '^magic\.' -x TestA
magic.TestB

As a convenience, Chisel modules can directly be marked as unit test as long as they do not have any constructor arguments. Doing so will automatically create a new Definition of the module without instantiating it. This can be useful for modules marked as public that serve as test harness, or by using a FormalTest marker to execute the module as a formal test.

class MyTestHarness extends RawModule with UnitTest with Public {
  // ...
}

class MyFormalTest extends RawModule with UnitTest {
  // ...
  FormalTest(this)
}

This is a first building block towards adding hardware unit tests to Chisel in a similar style as AnyFlatSpec and friends in ScalaTest, #[test] in Rust, lit tests in LLVM, or gtest in C++.

At a later stage, we may want to automate the execution of unit tests as formal or simulation checks, similar to how we have helper methods to run a Chisel generator all the way through to Verilog.

Contributor Checklist

• Did you add Scaladoc to every public function/method?
• Did you add at least one test demonstrating the PR?
• Did you delete any extraneous printlns/debugging code?
• Did you specify the type of improvement?
• Did you add appropriate documentation in docs/src?
• Did you request a desired merge strategy?
• Did you add text to be included in the Release Notes for this change?

Type of Improvement

• Feature (or new API)

Desired Merge Strategy

• Squash: The PR will be squashed and merged (choose this if you have no preference).

Release Notes

Reviewer Checklist (only modified by reviewer)

• Did you add the appropriate labels? (Select the most appropriate one based on the "Type of Improvement")
• Did you mark the proper milestone (Bug fix: 3.6.x, 5.x, or 6.x depending on impact, API modification or big change: 7.0)?
• Did you review?
• Did you check whether all relevant Contributor checkboxes have been checked?
• Did you do one of the following when ready to merge:
  • Squash: You/ the contributor Enable auto-merge (squash), clean up the commit message, and label with Please Merge.
  • Merge: Ensure that contributor has cleaned up their commit history, then merge with Create a merge commit.