Documentation Needed for clientArgs

[shellscape]

I've seen a few issues and pull requests regarding clientArgs in both karma's repo and grunt-karma's repo with zero documentation for it. Is there documentation out there and it's just hiding, or is the documentation lacking information on this feature?

[vojtajina]

What do you mean by clientArgs? The arguments that are passed into the browser?

Karma does pass the config.clientto the browser, however by default Karma does not use any of those properties. It might (there's a PR for useIframe, we should add captureConsole, etc.).

The only option I can think of is Mocha, which does mention it in the README, https://github.com/karma-runner/karma-mocha.

So I'm closing this, please send a pull request if you think there's something missing.

[shellscape]

Please see the following (on some of which you're a participant)

#671
9e7309d
#672
#530

This needs to be DOCUMENTED on the Karma documentation either on the 0.8 or 0.10 site. "client" appears one time on this page http://karma-runner.github.io/0.10/config/configuration-file.html and does not cover anything remotely close to clientArgs or the 'client' property you just mentoned.

I'm miffed that you closed this issue BEFORE I had a chance to respond. That's just poor etiquette, and is a smack in the digital face of someone taking an interest in the project.

[vojtajina]

@shellscape I didn't mean to offend you by closing the issue.

Can you be more concrete? What should be in the documentation? Source of all the documentation is on github (https://github.com/karma-runner/karma/tree/master/docs), so you can send a pull request to improve it. That would super awesome and other people would benefit from it.

The links you mentioned don't give me any better info - the clientArgs is just anything you pass will be forwarded to the client(browser).

@gfxmonk might be able to improve the docs, as he wanted this feature so badly. I don't think other people are using it at this point, because there are no adapter using it, it might be more useful in the future. At this point I only know about mocha using it.

I'm happy to help with concrete questions/problems.
If you submit a PR to improve the docs, that would be great.

[timbertson]

I did document the args that my original PR introduced (in the CLI args to karma run), but I'm happy to provide docs for the config setting too. How about:

## clientArgs
**Type:** Array

**Default:** `undefined`

**CLI:** All arguments after `--` (**Note:** this is the case for `karma run` only)

**Description:** When `karma run` is passed additional arguments on the command-line, they
are passed through to the test adapter as ``karma.config.args` (an array of strings).
The `clientArgs` option allows you to set this value for actions other than `run`.

@vojtajina can you confirm that clientArgs has no effect for karma run - only karma serve? It looks that way to me from the code, but my memory is sketchy.

Also, perhaps the default should be [] - from the code, it looks like the default is [] when executing karma run but undefined at other times?

[vojtajina]

The config option is client.args. Yep, the client.args is not read from
the config file by karma run, only by karma start

My point is, why do we need to document this? It's not used. Passing
anything in there won't do anything...
You need some code in the client that will consume these config options...

On Sat, Nov 30, 2013 at 4:53 PM, Tim Cuthbertson
notifications@github.comwrote:

I did document the args that my original PR introduced (in the CLI args to karma
run), but I'm happy to provide docs for the config setting too. How about:

clientArgs

Type: Array

Default: undefined

CLI: All arguments after -- (Note: this is the case for karma run only)

Description: When karma run is passed additional arguments on the command-line, they
are passed through to the test adapter as ``karma.config.args(an array of strings). TheclientArgs` option allows you to set this value for actions other than `run`.

@vojtajina https://github.com/vojtajina can you confirm that clientArgshas no effect for karma
run - only karma serve? It looks that way to me from the code, but my
memory is sketchy.

Also, perhaps the default should be [] - from the code, it looks like the
default is [] when executing karma run but undefined at other times?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/833#issuecomment-29564748
.

[timbertson]

Fair point. The docs are not super useful yet, but they're not useless either:

• users may need these docs as soon as any adapter uses it
• you don't know what other (custom) adapters are out there (case in point: mine certainly uses it - https://npmjs.org/package/karma-sjs-adapter)
• adapter authors might be using these docs too (unless there are other developer-specific docs?)

Also, if users think it sounds like a good idea, they might contribute support to it for their preferred adapter when they realize it doesn't support clientArgs yet. We could add a note in the docs that its behaviour depends on whether the adapter actually makes use of it, to avoid confusion.

I don't think there's any reason that common adapters (mocha etc) shouldn't make use of it, they just don't yet - partly because few people know of the feature's existence.

[shellscape]

@gfxmonk has hit the nail on the head with regard to the why and the how. We're currently customizing an adapter for internal use because the current adapters which ship don't support it, and when trying to figure out how things work we noticed that the documentation was nonexistent for the capability.

+1 vote for documenting this, and for @gfxmonk 's PR for updating the docs.

[vojtajina]

Yes. mocha uses it and so it is in Mocha's readme. You can add readme to
karma-sjs-adapter (at this point I even don't know what it is). I'm pretty
sure there are other plugins that use this and will be more in the future.
That's why I think these adapters should document their options.

That said, I'm not against mentioning that option in the Karma docs. Again

• it's all on github, anybody can send a PR.

On Sun, Dec 1, 2013 at 6:20 PM, Andrew Powell notifications@github.comwrote:

@gfxmonk https://github.com/gfxmonk has hit the nail on the head with
regard to the why and the how. We're currently customizing an adapter for
internal use because the current adapters which ship don't support it, and
when trying to figure out how things work we noticed that the documentation
was nonexistent for the capability.

+1 vote for documenting this, and for @gfxmonkhttps://github.com/gfxmonk's PR for updating the docs.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/833#issuecomment-29590697
.