pest: Plans for `describe` blocks?

This is pretty important, as without it we have no idea what “it” is referring to in tests.

Currently, it('can log in') gets translated directly as “it can log in” which is ambiguous. It would be preferable to be able to describe the subject:

describe(User::class, function () {
  it('can log in if verified')->assertAuthenticated();
});

=> “User can log in if verified”

Or even allow nested descriptions, using context as an alias for describe, like in RSpec.

describe('User', function () {
  context('is verified', function () {
    it('can log in')->assertAuthenticated();
  });

  context('is not verified', function () {
    it('can not log in')->assertGuest();
  });
});

=> “User is verified can log in”, “User is not verified can not log in”

it’s in the 2.9 anouncement, this feature is included in the core Pest

@nunomaduro I think describe blocks are very important in order to make your tests efficient, readable, and expressive. The “Testing Best Practices” repo explains it a few times:

• Include 3 parts in each test name
• Categorize tests under at least 2 levels [of describe]

It would be very meaningful to have describe in Pest. Please consider it. 🙏

Sorry - if considering this once again, we are going to put this on hold.

I’d love for Pest to use describe-it syntax, which includes describe and context. Right now we just have it syntax, and I’m overloading a lot of context into test names. Its also making it hard to share setups.

it('returns valid response when there are records', function () {
    Specie::factory()
        ->count(5)
        ->create();

    // assertion
});

it('returns valid response when there are no records', function () {
    $this->assertEquals(0, Specie::count());

    // assertion
});

If this was using other describe-it tools in other languages I’d be doing this:

describe(FooController::class, function () {

  context('when there are records', function () {
    before(function () {
      Specie::factory()
        ->count(5)
        ->create();
    });
    
    it('returns valid response', function () {
      // assertion 1
    });
    it('can do backflips', function () {
      // assertion 2
    });
    it('jump sharks', function () {
      // assertion 3
    });
  });

  context('when there are no records', function () {
    before(function () {
      $this->assertEquals(0, Specie::count());
    });
  
    it('returns valid response', function () {
        // assertion 1
    });
  });
});

This is a load more lines but the output and debugging improvements that come with it are worth a whole lot more than the sore fingers.

Or you can smush loads of assertions into one, either way context is really handy when you want to nest contexts.

Please can we consider describe and context?

See how they work in RSpec. https://www.betterspecs.org/#contexts

One more vote for describe(), and possibly context() as an alias.

I segment test files using comments, but they are not included in reports. And when a class has more than a couple of methods, I sometimes have to artificially change test descriptions to avoid collisions. A way to group tests inside the same Pest file would be a great addition!

This feature would provide a lot of value. In a single test suite, I might test multiple functions, and with multiple scenarios. But all the console descriptions are “it does ____”. It would be really nice to be able to group things by function or scenario with describe() blocks. This would (1) provide a better development experience, and (2) provide a better debugging experience while reading terminal output.

I wrote a plugin awhile ago that accomplishes this

https://github.com/ozziexsh/pest-plugin-nest

the caveat is that you need to use the plugin’s exported test and it functions to get output to work properly but so far it has been great

you also cannot nest hook functions like beforeEach inside describe blocks as phpunit expects there to only be one per file

I think this is a main feature for a framework like Pest. Is there any plan for this @nunomaduro?

It’s a good idea, but no plans for now.

@nunomaduro, what would it take to get this on the roadmap?

Just a note to people here. You could create a plugin for doing this instead of describe being part of the core of pest, it could be a plugin for people to install if they want it.

This would be the selling feature for me to ditch phpUnit for.

In fact I was under the impression Pest already has the elegant RSpec context syntax. Why do people switch then??

Describe and contexts are needed IMO

It’s a good idea, but no plans for now.

@nunomaduro Any expectation to see this feature in Pest v2? 😊

@jordanbrauer I think it’s totally fine for you to try and work out a PR for this and figure out what it’s supposed to do.

One note about adding this is that it will be a breaking change for the IntelliJ Plugin, so changes has to be made before the IntelliJ plugin can work with it.

@jordanbrauer seeing as @nunomaduro was the one to reopen, I am guessing he is (or will be) working on this personally.