[DOCUMENTATION] Are controller specs discouraged in favor of request specs?

[rlue]

I stumbled across a guide on everydayrails.com today that made the following claim:

Both the Rails and RSpec teams suggest replacing or removing your app’s controller tests (also known as the functional test layer), in favor of directly testing models (units), or with higher-level integration tests.

The RSpec 3.5 release notes (where the author presumably got this information) had this to say (emphasis mine):

In Rails 5 assigns and assert_template are "soft deprecated". Controller tests themselves are not, and adding :type => :controller to your specs is still 100% supported.

and

For new Rails apps: we don't recommend adding the rails-controller-testing gem to your application. The official recommendation of the Rails team and the RSpec core team is to write request specs instead. Request specs allow you to focus on a single controller action, but unlike controller tests involve the router, the middleware stack, and both rack requests and responses. This adds realism to the test that you are writing, and helps avoid many of the issues that are common in controller specs.

So it sounds like controller specs are discouraged, but not deprecated (in adherence to SEMVER)? If this is the case, perhaps it would be helpful to add a note to this effect in the README of this repo (specifically, the “Controller Specs” section)?

If the maintainers are okay with this idea, I'd be happy to submit a PR.

[fables-tales]

Yes. The best advice we can give for people working on rails apps is to write request specs instead of controller specs. I'd consider writing a new controller spec in 2017 to be a smell, even on an older rails app. Keeping controller specs around for legacy reasons is absolutely fine though. @rlue if you'd like to open a PR on the readme I think that's a reasonable thing to do.

[rlue]

Thanks, PR submitted! If you could entertain a tangent — I’m having trouble grokking the terminology of test vs. spec, and wasn’t sure how to label the relationship between “request specs” and “integration tests”.

Would it be accurate to say that a specification is a description of an application’s desired behavior (as opposed to the definition of an application’s actual behavior; i.e., the app code itself), and that specs define the parameters of the test?

That is, can I say that request specs are “for” integration tests?

[xaviershay]

honestly I kind of use the two interchangeably :/

[baash05]

Honestly.. I don't need to test the whole stack/rack/middleware most of the time. I would favour faster tests over completeness. I use factories and moc's for the same reason.

[JonRowe]

Request specs are only marginally slower than controller specs, you are testing a large part of the middleware stack in controller specs too (they have never been unit tests) (request specs are not end to end, those are facilitated by system test/specs these days). Regardless rspec-rails is a thin wrapper around Rails test helpers (bringing their patterns into rspec for use) so its up to them to recommend what they want.

[pirj]

I suggest moving this discussion to our mailing list, or even better to Rails discussions.
There's a lot of confusion between Controller and Request specs, and really the best advice is to use Request specs.