[docs] Clarify only-testing/skip-testing format #27585
Conversation
scan/lib/scan/options.rb
Outdated
| @@ -125,15 +125,15 @@ def self.available_options | |||
| # tests to run | |||
| FastlaneCore::ConfigItem.new(key: :only_testing, | |||
| env_name: "SCAN_ONLY_TESTING", | |||
| description: "Array of strings matching Test Bundle/Test Suite/Test Cases to run", | |||
| description: "Array of test identifiers to run, using the `xcodebuild` test identifier format: `Test Target`, `Test Target/Test Suite`, or `Test Target/Test Suite/Test Case`", | |||
There was a problem hiding this comment.
Thanks for making the changes!
Just wanted to share another idea how we could improve this:
Array of test identifiers to run. Expected format is TestTarget[/TestClass[/TestMethod]]
This kind of bracket notation is pretty common in CLI tools and technical docs, though it’s not a universal standard. It just visually indicates that some segments can be omitted, as long as the order and hierarchy are respected.
There was a problem hiding this comment.
Oh good idea! That's more compact than my version and seems pretty clear, at least to my eyes. How would you feel about:
| description: "Array of test identifiers to run, using the `xcodebuild` test identifier format: `Test Target`, `Test Target/Test Suite`, or `Test Target/Test Suite/Test Case`", | |
| description: "Array of `xcodebuild` test identifiers to run. Expected format: Test Target[/Test Suite[/Test Case]]", |
I don't feel strongly about that version or the one you suggested — happy to make either change, or for someone else to edit + merge the change. Thanks for reviewing!
There was a problem hiding this comment.
Thanks for the suggestion! I’d consider simplifying the message a bit by omitting xcodebuild, since it’s already implied by the context. Maybe we could merge our ideas into something like:
Array of test identifiers to run. Expected format: TestTarget[/TestSuite[/TestCase]]
What do you think?
There was a problem hiding this comment.
That works for me! Anecdotally, it wasn't obvious to me from the context that this format came from xcodebuild, but I have no idea how common or unusual that is for other users 😂 I'll update to that latest version and we should be good to go. Thanks for workshopping this with me!
Checklist
bundle exec rspecfrom the root directory to see all new and existing tests passbundle exec rubocop -ato ensure the code style is validci/circlecibuilds in the "All checks have passed" section of my PR (connect CircleCI to GitHub if not)Motivation and Context
I hadn't used these
scanoptions before, nor was I familiar with theirxcodebuildequivalents. When I read the docs, I interpreted the slashes as meaning "or", rather than specifying a string format. That is, I thought I could provide just--only-testing:"someTestFunctionName"or--only-testing:"TestSuiteName/testFunctionName".Eventually https://stackoverflow.com/a/40558173 set me aright. I figured others might be similarly confused.
Description
I've tried to keep things concise here while also explaining the format a bit more clearly. Definitely open to edits and feedback!