Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Skip tests tagged as document: false on docs generation #450

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

stwr667
Copy link

@stwr667 stwr667 commented Oct 28, 2019

When running the below command to re-generate API docs:
RAILS_ENV=test rake docs:generate
it will execute every single rspec test under 'spec/acceptance/**/*_spec.rb'. It even executes the tests that are explicitly marked as:
document: false
With this update, only the rspec tests that contribute to the generation of API documentation will be executed by default, which is much more efficient.

Aside: For our team, this reduced the amount of tests being executed during
docs generation down from 195 to 37.

Further notes
Relevant RSpec documentation: https://relishapp.com/rspec/rspec-core/docs/command-line/tag-option#exclude-examples-with-a-%60name:value%60-tag-and-@

@jakehow
Copy link
Member

jakehow commented Oct 28, 2019

@stwr667 not sure we want to change this behavior, since I am think the intention was to use the task to both confirm all specs pass and generate docs simultaneously. I think there are a couple paths to go here:

  1. add a flag to trigger skipping undocumented specs,
  2. add another rake task,
  3. let users continue to add their own rake tasks when they want customization and add this as an example to the docs.

@oestrich
Copy link
Contributor

I agree with @jakehow, I don't think we want the default to be skipping tests in acceptance as the goal was "if the tests pass you get docs".

I like any of the three ways mentioned for going forward.

When running the below command to re-generate API docs:
RAILS_ENV=test rake docs:generate
it will execute every single rspec test under 'spec/acceptance/**/*_spec.rb'.
It *even* executes the tests that are explicitly marked as:
document: false
With this new rake task, only the rspec tests that contribute to the generation of
API documentation will be executed:
RAILS_ENV=test rake docs:generate:skip_undocumenting

Aside: For our team, this reduced the amount of tests being executed during
docs generation down from 195 to 37.
@stwr667
Copy link
Author

stwr667 commented Oct 29, 2019

@jakehow, @oestrich, thanks for your feedback. I've gone with option 2.

@stwr667
Copy link
Author

stwr667 commented Oct 31, 2019

Hi @jakehow, @oestrich,
Is there anything else blocking this from going ahead?
We've been using this heavily on our generations, and it's been working well.
Regards,
Steve

@stwr667
Copy link
Author

stwr667 commented Nov 14, 2019

@jakehow, @oestrich, can I get some feedback on this one please? It'd be good to prevent it from getting in a stale state.

@stwr667
Copy link
Author

stwr667 commented Jan 23, 2020

Happy new year @jakehow, @oestrich. I made changes as requested. Is there anything else holding this up from being merged?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants