Organizing PHPUnit Tests in Namespaces [closed]

Question

I see two options for organizing PHPUnit unit tests into a namespace hierarchy. What are the advantages/disadvantages to these two approaches? Are there any obvious flaws I haven't considered that would make one the obvious better choice?

Consider a sample class like \SomeFramework\Utilities\AwesomeClass:

• Approach 1: Place each TestCase class into the same namespace as the covered class.

  \SomeFramework\Utilities\AwesomeClassTest
  

  • Advantages
    • Consistent with the traditional approach to writing PHPUnit tests.
  • Disadvantages
    • Less flexibility.
    • Seems to break the principle behind using namespaces - unrelated tests are grouped into the same namespace.
      
      

• Approach 2: Place each TestCase in a namespace named after the covered class.

  \SomeFramework\Utilities\AwesomeClass\Test
  

  • Advantages
    • Provides a very easy/obvious way to group multiple related TestCase classes together, say for different test suites.
  • Disadvantages
    • Could result in a deeper, more complex hierarchy.

Answer 1

My proposed solution and the reasoning behind it:

Folder layout:

. ├── src │   ├── bar │   │   └── BarAwesomeClass.php │   └── foo │       └── FooAwesomeClass.php └── tests     ├── helpers     │   └── ProjectBaseTestClassWithHelperMethods.php     ├── integration     │   ├── BarModuleTest.php     │   └── FooModuleTest.php     └── unit         ├── bar         │   └── BarAwesomeClassTest.php         └── foo             └── FooAwesomeClassTest.php 

The helpers/ folder contains classes that are not tests but are only used in a testing context. Usually that folder contains a BaseTestClass maybe containing project specific helper methods and a couple of easy to reuse stub classes so you don't need as many mocks.

The integration/ folder contains tests that span over more classes and test "bigger" parts of the system. You don't have as many of them but there is no 1:1 mapping to production classes.

The unit/ folder maps 1:1 to the src/. So for every production class there is one class that contains all the unit tests for that class.

Namespaces

Approach 1: Place each TestCase class into the same namespace as the covered class.

This folder approach should solve one of your disadvantages with Approach 1. You still get the flexibility to have more tests than a pure 1:1 mapping could give you but everything is ordered and in place.

Seems to break the principle behind using namespaces - unrelated tests are grouped into the same namespace.

If the tests feel "unrelated" maybe the production code has the same issue?

It's true that the tests don't depend on one another but they might use their "close" classes as mocks or use the real ones in case of DTOs or Value Objects. So i'd say that there is a connection.

Approach 2: Place each TestCase in a namespace named after the covered class.

There are a couple of projects that do that but usually they structure it a little differently:

It's not \SomeFramework\Utilities\AwesomeClass\Test, but \SomeFramework\Tests\Utilities\AwesomeClassTest and they still keep the 1:1 mapping, but with the extra test namespace added.

Extra test namespace

My personal take is that I don't like having separate test namespaces and I'll try to find a couple for arguments for and against that choice:

Tests should serve as documentation on how to use a class

When the real class is in another namespace, the tests show how to use that class outside of its own module.

When the real class is in the same namespace, the tests show how to use that class from inside that module.

The differences are quite minor (usually a couple of "use" statements or fully-qualified paths)

When we get the possibility to say $this->getMock(AwesomeClass::CLASS) in PHP 5.5 instead of $this->getMock('\SomeFramework\Utilities\AwesomeClass') every mock will require a use statement.

For me the usage within the module is more valuable for most classes

Polluting the "Production" Namespace

When you say new \SomeFramework\Utilities\A the auto completion might show you AwesomeClass and AwesomeClassTest and some people don't want that. For external use, or when shipping your source that isn't a problem of course since the tests don't get shipped but it might be something to consider.

Answer 2

There is a third option that I use and that fits nicely with composer autoloading: Insert a Test namespace after the first step in the hierarchy. In your case that namespace would be \SomeFramework\Tests\Utilities\ and your class would be \SomeFramework\Tests\Utilities\AwesomeClassTest.

You can then either put the tests together with the other classes in the \SomeFramework\Test directory, or put them in a separate directory. Your autoload information for composer.json could look like this:

{
    "autoload": {
        "psr-0": { 
            "SomeFramework\\": "src/",
        }
    },
    "autoload-dev": {
        "psr-0": { 
            "SomeFramework\\Tests\\": "tests/"
        }
    }
}

Advantages of the third approach are:

• Separation of tests and production code
• Similar folder hierarchies for tests and production classes
• Easy autoloading