Plans for describe blocks?

[mikeerickson]

Curious, what are your thoughts about implementing the standard describe blocks?

Ala?

https://jestjs.io/docs/en/api#describename-fn

Example

describe('my block', function() {
  test('is delicious', function() {
    assertTrue(true);
  });
});

[nunomaduro]

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

[hackel]

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"

[mikeerickson]

Would tend to agree with you 👍

[MatanYadaev]

@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. 🙏

[jordanbrauer]

Would be a nice to have for sure. Given that this issue was re-opened recently, I am curious what everyone has in mind for how describe works; what is it doing under the hood with how Pest works now? If no one else takes this soon or hasn't already started it, I might be interested in starting work on it.

[mikeerickson]

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

[olivernybroe]

@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.

[nunomaduro]

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

[MatanYadaev]

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

[AndyWendt]

Describe and contexts are needed IMO

[paulshryock]

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.

[fran-f]

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!

[philsturgeon]

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

[raveren]

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??

[paulshryock]

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

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

[joskfg]

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

[olivernybroe]

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.

[paulshryock]

I've forked the Pest plugin template and started a pest-plugin-describe repo here: https://github.com/paulshryock/pest-plugin-describe

I haven't done any design or implementation yet, but the repo exists and I'll tinker with it when I have some free time. If anyone else is interested in contributing, PR's are welcome. Or feel free to open Issues or Discussions on that repo to get some discussion going.

[ozziexsh]

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

[paulshryock]

I wrote a plugin awhile ago that accomplishes this

Amazing! I will definitely check that out.

[raveren]

@nunomaduro can we reopen this just to close it and pop some champagne!

Thank you thank you thank you!!! I'll start planning our migration to Pest now :))

[paulshryock]

Still would love to see this functionality in Pest core without needing a plugin, as time allows. Being able to use functions like beforeEach, beforeAll, afterEach, and afterAll inside of describe/context would be important too.

[raveren]

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