Can we use rspec context description stack for describe responses?

[AlexeyMatskevich]

Example

context "when user send not match password do
    it "return some error" do
      post "/login", {password: "password"}

      expect(reponse.body).to eq(" ... some error ...")
    end
  end

It generate description: return some error in openapi.yaml
It would be more convenient to add a description from the entire description stack context.

context "when user ... foo" do
  ...
  context "but not ... bar" do
  ...
     it "return some error" do
  ...

For example, this would generate description: when user ... foo but not ... bar it return some error
Then we will have all the power of the rspec as a BDD in the API description.

Although it is possible use description into the response is not entirely correct, I lack a technical understanding in this matter.

[k0kubun]

Although it is possible use description into the response is not entirely correct, I lack a technical understanding in this matter.

I took a look at how to support this feature. Let me ask a few things.

• Don't you use a describe block? Please include it if you use it in your real example.
  • context cannot be distinguished from describe. Do you expect to include describe's descriptions as well?
• it cannot be distinguished from specify. Therefore we can't reasonably generate "it" in your proposed description.
  • Therefore the description would be when your ... foo but not ... bar return some error. Are you okay with it?

[AlexeyMatskevich]

1. Yep, I use it to separate tests by methods or by queries for request tests and use context for refinement of behavior context. I try to follow the rules from http://www.betterspecs.org/

describe Table, type: :request do
  describe "/index" do
    context "when ..." do
      it "return ..." do
      context "but ..." do
        it "return ..."
...
    context "when another..." do
      it "return another ..." do
...
end

2. Here we are talking about the fact that rspec implies the use of BDD descriptions through describe and context and if we merging which together it, it should ultimately be a complete English sentence describing the behavior in each case. so it would be better to leave it. Can we just simple add it string in the presence of context?

[k0kubun]

1. Yep, I use it to separate tests by methods or by queries for request tests and use context for refinement of behavior context. I try to follow the rules from

Because context and describe are the same things, description will need to be:

• Table /index when ... return ...
• Table /index when ... but ... return ...
• Table /index when another ... return another ...

Let me ask this again: are you okay with that? We simply can't remove Table /index part in a reasonable manner.

Can we just simple add it string in the presence of context?

I think it's feasible to just generate it regardless of whether a user used it or specify (because of the assumption, I think the behavior should not be a default). Though, as context cannot be distinguished from describe, it will need to be generated in a presence of describe too.

[AlexeyMatskevich]

1. Yes it is really problematic. Maybe cut top level describe with regex, but this seems like an unreliable solution. I think that for this we need to develop some kind of agreement on the description if we want to process it automatically. For example, use only /path in the upper describe, then we can somehow cut it based on regexp.
   Table /index when another ... return another ... -> (regexp) -> when another ... return another ...
2. I agree

[k0kubun]

Yes it is really problematic. Maybe cut top level describe with regex, but this seems like an unreliable solution. I think that for this we need to develop some kind of agreement on the description if we want to process it automatically. For example, use only /path in the upper describe, then we can somehow cut it based on regexp.
Table /index when another ... return another ... -> (regexp) -> when another ... return another ...

If it requires some agreement on the description, probably it's too specific to your project. So I added some flexibility on the solution for you 2f36d0d.

You take a RSpec example, and you traverse a context tree as you like, and yield a description from it:

RSpec::OpenAPI.description_builder = -> (example) do
  contexts = example.example_group.parent_groups.map(&:description).select do |description|
    description.match?(/\Awhen /)
  end
  [*contexts, 'it', example.description].join(' ')
end

I hope you'll find a best way to build a description using the config as you like. Please try v0.3.1.

[AlexeyMatskevich]

I would not say that I have a specific use of rspec in the project, I try to follow generally accepted techniques, but you are right that in the end everything becomes specific.
Thanks for the work you've done.