[docs] add documentation for API usage of userVariables

[htho]

What is your Scenario?

I was looking for a way to inject userVariables (introduced in v1.16.0) when I start TestCafe via the js API. The only documented way to use them is via a configuration file. I did not find any documentation about JS API usage, but this comment by @Artem-Babich in #2431:

Hi, you can use userVariables to pass additional data to the tests. You can define them in the configuration file as well as in your runner code:

createTestCafe({userVariables: { url: 'test' }})

import { userVariables } from 'testcafe';

fixture `Test user variables`

test('Type text', async t => {
    await t.expect(userVariables.url).eql('test')
});

This is exactly what I was looking for. It works, although it is a little awkward because all other configuration goes to the runner (and therefore RunOptions).

What are you suggesting?

For API / TestCafe API / Global / createTestCafe() # options

1. Add the paramter to the table of parameters
2. Link to userVariables at "Related configuration file properties"

For API / Configuration File # User Variables

1. Add:

CLI: N/A API: createTestCafe

For /ts-defs-src/runner-api/configuration.d.ts

1. Add userVariables: UserVariables

What alternatives have you considered?

I can add a file like testcafe.global.tc.ts:

declare module "testcafe" {
    global {
        interface TestCafeConfigurationOptions {
            userVariables: UserVariables
        }
    }
}

Additional context

No response

[Aleksey28]

Hi @htho,

Thank you for informing us about this issue. We'll investigate it and update this thread once we have news.