docs(dotnet): add API testing (#13889)

2022-05-23 22:12:57 +03:00 · 2022-05-23 22:12:57 +03:00 · 7f640d8a49
--- a/docs/src/api/class-apirequest.md
+++ b/docs/src/api/class-apirequest.md
@ -1,5 +1,4 @@
 # class: APIRequest
-* langs: js, java, python

 Exposes API that can be used for the Web API testing. This class is used for creating
 [APIRequestContext] instance which in turn can be used for sending web requests. An instance
@ -7,7 +6,6 @@ of this class can be obtained via [`property: Playwright.request`]. For more inf
 see [APIRequestContext].

 ## async method: APIRequest.newContext
-* langs: js, java, python
 - returns: <[APIRequestContext]>

 Creates new instances of [APIRequestContext].
@ -57,7 +55,7 @@ file with saved storage, or the value returned by one of [`method: BrowserContex
 [`method: APIRequestContext.storageState`] methods.

 ### option: APIRequest.newContext.storageState
-* langs: java
+* langs: java, csharp
 - `storageState` <[string]>

 Populates context with given storage state. This option can be used to initialize context with logged-in information
--- a/docs/src/api/class-apirequestcontext.md
+++ b/docs/src/api/class-apirequestcontext.md
@ -1,5 +1,4 @@
 # class: APIRequestContext
-* langs: js, java, python

 This API is used for the Web API testing. You can use it to trigger API endpoints, configure micro-services, prepare
 environment or the service to your e2e test.
@ -120,6 +119,12 @@ with sync_playwright() as p:
    assert await response.body() == '{"status": "ok"}'
 ```

+## method: APIRequestContext.createFormData
+* langs: csharp
+- returns: <[FormData]>
+
+Creates a new [FormData] instance which is used for providing form and multipart data when making HTTP requests.
+
 ## async method: APIRequestContext.delete
 - returns: <[APIResponse]>

@ -128,12 +133,15 @@ The method will populate request cookies from the context and update
 context cookies from the response. The method will automatically follow redirects.

 ### param: APIRequestContext.delete.url = %%-fetch-param-url-%%
-### param: APIRequestContext.delete.params = %%-java-fetch-params-%%
+### param: APIRequestContext.delete.params = %%-java-csharp-fetch-params-%%
 ### option: APIRequestContext.delete.params = %%-js-python-fetch-option-params-%%
+### option: APIRequestContext.delete.params = %%-csharp-fetch-option-params-%%
 ### option: APIRequestContext.delete.headers = %%-js-python-fetch-option-headers-%%
 ### option: APIRequestContext.delete.data = %%-js-python-fetch-option-data-%%
 ### option: APIRequestContext.delete.form = %%-js-python-fetch-option-form-%%
-### option: APIRequestContext.delete.multipart = %%-js-pyhton-fetch-option-multipart-%%
+### option: APIRequestContext.delete.form = %%-csharp-fetch-option-form-%%
+### option: APIRequestContext.delete.multipart = %%-js-python-fetch-option-multipart-%%
+### option: APIRequestContext.delete.multipart = %%-csharp-fetch-option-multipart-%%
 ### option: APIRequestContext.delete.timeout = %%-js-python-fetch-option-timeout-%%
 ### option: APIRequestContext.delete.failOnStatusCode = %%-js-python-fetch-option-failonstatuscode-%%
 ### option: APIRequestContext.delete.ignoreHTTPSErrors = %%-js-python-fetch-option-ignorehttpserrors-%%
@ -154,11 +162,12 @@ context cookies from the response. The method will automatically follow redirect

 Target URL or Request to get all parameters from.

-### param: APIRequestContext.fetch.params = %%-java-fetch-params-%%
+### param: APIRequestContext.fetch.params = %%-java-csharp-fetch-params-%%
 ### option: APIRequestContext.fetch.params = %%-js-python-fetch-option-params-%%
+### option: APIRequestContext.fetch.params = %%-csharp-fetch-option-params-%%

 ### option: APIRequestContext.fetch.method
-* langs: js, python
+* langs: js, python, csharp
 - `method` <[string]>

 If set changes the fetch method (e.g. [PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) or
@ -167,7 +176,9 @@ If set changes the fetch method (e.g. [PUT](https://developer.mozilla.org/en-US/
 ### option: APIRequestContext.fetch.headers = %%-js-python-fetch-option-headers-%%
 ### option: APIRequestContext.fetch.data = %%-js-python-fetch-option-data-%%
 ### option: APIRequestContext.fetch.form = %%-js-python-fetch-option-form-%%
-### option: APIRequestContext.fetch.multipart = %%-js-pyhton-fetch-option-multipart-%%
+### option: APIRequestContext.fetch.form = %%-csharp-fetch-option-form-%%
+### option: APIRequestContext.fetch.multipart = %%-js-python-fetch-option-multipart-%%
+### option: APIRequestContext.fetch.multipart = %%-csharp-fetch-option-multipart-%%
 ### option: APIRequestContext.fetch.timeout = %%-js-python-fetch-option-timeout-%%
 ### option: APIRequestContext.fetch.failOnStatusCode = %%-js-python-fetch-option-failonstatuscode-%%
 ### option: APIRequestContext.fetch.ignoreHTTPSErrors = %%-js-python-fetch-option-ignorehttpserrors-%%
@ -180,8 +191,9 @@ The method will populate request cookies from the context and update
 context cookies from the response. The method will automatically follow redirects.

 ### param: APIRequestContext.get.url = %%-fetch-param-url-%%
-### param: APIRequestContext.get.params = %%-java-fetch-params-%%
+### param: APIRequestContext.get.params = %%-java-csharp-fetch-params-%%
 ### option: APIRequestContext.get.params = %%-js-python-fetch-option-params-%%
+### option: APIRequestContext.get.params = %%-csharp-fetch-option-params-%%
 ### option: APIRequestContext.get.headers = %%-js-python-fetch-option-headers-%%
 ### option: APIRequestContext.get.timeout = %%-js-python-fetch-option-timeout-%%
 ### option: APIRequestContext.get.failOnStatusCode = %%-js-python-fetch-option-failonstatuscode-%%
@ -195,8 +207,9 @@ The method will populate request cookies from the context and update
 context cookies from the response. The method will automatically follow redirects.

 ### param: APIRequestContext.head.url = %%-fetch-param-url-%%
-### param: APIRequestContext.head.params = %%-java-fetch-params-%%
+### param: APIRequestContext.head.params = %%-java-csharp-fetch-params-%%
 ### option: APIRequestContext.head.params = %%-js-python-fetch-option-params-%%
+### option: APIRequestContext.head.params = %%-csharp-fetch-option-params-%%
 ### option: APIRequestContext.head.headers = %%-js-python-fetch-option-headers-%%
 ### option: APIRequestContext.head.timeout = %%-js-python-fetch-option-timeout-%%
 ### option: APIRequestContext.head.failOnStatusCode = %%-js-python-fetch-option-failonstatuscode-%%
@ -210,12 +223,15 @@ The method will populate request cookies from the context and update
 context cookies from the response. The method will automatically follow redirects.

 ### param: APIRequestContext.patch.url = %%-fetch-param-url-%%
-### param: APIRequestContext.patch.params = %%-java-fetch-params-%%
+### param: APIRequestContext.patch.params = %%-java-csharp-fetch-params-%%
 ### option: APIRequestContext.patch.params = %%-js-python-fetch-option-params-%%
+### option: APIRequestContext.patch.params = %%-csharp-fetch-option-params-%%
 ### option: APIRequestContext.patch.headers = %%-js-python-fetch-option-headers-%%
 ### option: APIRequestContext.patch.data = %%-js-python-fetch-option-data-%%
 ### option: APIRequestContext.patch.form = %%-js-python-fetch-option-form-%%
-### option: APIRequestContext.patch.multipart = %%-js-pyhton-fetch-option-multipart-%%
+### option: APIRequestContext.patch.form = %%-csharp-fetch-option-form-%%
+### option: APIRequestContext.patch.multipart = %%-js-python-fetch-option-multipart-%%
+### option: APIRequestContext.patch.multipart = %%-csharp-fetch-option-multipart-%%
 ### option: APIRequestContext.patch.timeout = %%-js-python-fetch-option-timeout-%%
 ### option: APIRequestContext.patch.failOnStatusCode = %%-js-python-fetch-option-failonstatuscode-%%
 ### option: APIRequestContext.patch.ignoreHTTPSErrors = %%-js-python-fetch-option-ignorehttpserrors-%%
@ -228,12 +244,15 @@ The method will populate request cookies from the context and update
 context cookies from the response. The method will automatically follow redirects.

 ### param: APIRequestContext.post.url = %%-fetch-param-url-%%
-### param: APIRequestContext.post.params = %%-java-fetch-params-%%
+### param: APIRequestContext.post.params = %%-java-csharp-fetch-params-%%
 ### option: APIRequestContext.post.params = %%-js-python-fetch-option-params-%%
+### option: APIRequestContext.post.params = %%-csharp-fetch-option-params-%%
 ### option: APIRequestContext.post.headers = %%-js-python-fetch-option-headers-%%
 ### option: APIRequestContext.post.data = %%-js-python-fetch-option-data-%%
 ### option: APIRequestContext.post.form = %%-js-python-fetch-option-form-%%
-### option: APIRequestContext.post.multipart = %%-js-pyhton-fetch-option-multipart-%%
+### option: APIRequestContext.post.form = %%-csharp-fetch-option-form-%%
+### option: APIRequestContext.post.multipart = %%-js-python-fetch-option-multipart-%%
+### option: APIRequestContext.post.multipart = %%-csharp-fetch-option-multipart-%%
 ### option: APIRequestContext.post.timeout = %%-js-python-fetch-option-timeout-%%
 ### option: APIRequestContext.post.failOnStatusCode = %%-js-python-fetch-option-failonstatuscode-%%
 ### option: APIRequestContext.post.ignoreHTTPSErrors = %%-js-python-fetch-option-ignorehttpserrors-%%
@ -246,12 +265,15 @@ The method will populate request cookies from the context and update
 context cookies from the response. The method will automatically follow redirects.

 ### param: APIRequestContext.put.url = %%-fetch-param-url-%%
-### param: APIRequestContext.put.params = %%-java-fetch-params-%%
+### param: APIRequestContext.put.params = %%-java-csharp-fetch-params-%%
 ### option: APIRequestContext.put.params = %%-js-python-fetch-option-params-%%
+### option: APIRequestContext.put.params = %%-csharp-fetch-option-params-%%
 ### option: APIRequestContext.put.headers = %%-js-python-fetch-option-headers-%%
 ### option: APIRequestContext.put.data = %%-js-python-fetch-option-data-%%
 ### option: APIRequestContext.put.form = %%-js-python-fetch-option-form-%%
-### option: APIRequestContext.put.multipart = %%-js-pyhton-fetch-option-multipart-%%
+### option: APIRequestContext.put.form = %%-csharp-fetch-option-form-%%
+### option: APIRequestContext.put.multipart = %%-js-python-fetch-option-multipart-%%
+### option: APIRequestContext.put.multipart = %%-csharp-fetch-option-multipart-%%
 ### option: APIRequestContext.put.timeout = %%-js-python-fetch-option-timeout-%%
 ### option: APIRequestContext.put.failOnStatusCode = %%-js-python-fetch-option-failonstatuscode-%%
 ### option: APIRequestContext.put.ignoreHTTPSErrors = %%-js-python-fetch-option-ignorehttpserrors-%%
@ -276,7 +298,7 @@ context cookies from the response. The method will automatically follow redirect
 Returns storage state for this request context, contains current cookies and local storage snapshot if it was passed to the constructor.

 ## async method: APIRequestContext.storageState
-* langs: java
+* langs: java, csharp
 - returns: <[string]>

 ### option: APIRequestContext.storageState.path = %%-storagestate-option-path-%%
--- a/docs/src/api/class-apiresponse.md
+++ b/docs/src/api/class-apiresponse.md
@ -1,5 +1,4 @@
 # class: APIResponse
-* langs: js, java, python

 [APIResponse] class represents responses returned by [`method: APIRequestContext.get`] and similar methods.

--- a/docs/src/api/class-browsercontext.md
+++ b/docs/src/api/class-browsercontext.md
@ -842,7 +842,8 @@ Creates a new page in the browser context.
 Returns all open pages in the context.

 ## property: BrowserContext.request
-* langs: js, java, python
+* langs:
+  - alias-csharp: APIRequest
 - type: <[APIRequestContext]>

 API testing helper associated with this context. Requests made with this API will use context cookies.
--- a/docs/src/api/class-formdata.md
+++ b/docs/src/api/class-formdata.md
@ -1,5 +1,5 @@
 # class: FormData
-* langs: java
+* langs: java, csharp

 The [FormData] is used create form data that is sent via [APIRequestContext].

@ -14,6 +14,7 @@ page.request().post("http://localhost/submit", RequestOptions.create().setForm(f
 ```

 ## method: FormData.create
+* langs: java
 - returns: <[FormData]>

 Creates new instance of [FormData].
@ -35,3 +36,12 @@ Field name.
  - `buffer` <[Buffer]> File content

 Field value.
+
+### param: FormData.set.value
+* langs: csharp
+- `value` <[string]|[boolean]|[int]|[Object]>
+  - `name` <[string]> File name
+  - `mimeType` <[string]> File type
+  - `buffer` <[Buffer]> File content
+
+Field value.
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@ -2559,7 +2559,8 @@ last redirect.
 ### option: Page.reload.timeout = %%-navigation-timeout-%%

 ## property: Page.request
-* langs: js, java, python
+* langs:
+  - alias-csharp: APIRequest
 - type: <[APIRequestContext]>

 API testing helper associated with this page. This method returns the same instance as
--- a/docs/src/api/class-playwright.md
+++ b/docs/src/api/class-playwright.md
@ -215,7 +215,8 @@ except TimeoutError as e:
 This object can be used to launch or connect to Firefox, returning instances of [Browser].

 ## property: Playwright.request
-* langs: js, java, python
+* langs:
+  - alias-csharp: APIRequest
 - type: <[APIRequest]>

 Exposes API that can be used for the Web API testing.
--- a/docs/src/api/params.md
+++ b/docs/src/api/params.md
@ -310,26 +310,32 @@ Target URL.

 Query parameters to be sent with the URL.

-## java-fetch-params
+## csharp-fetch-option-params
+* langs: csharp
+- `params` <[Object]<[string], [Serializable]>>
+
+Query parameters to be sent with the URL.
+
+## java-csharp-fetch-params
 * langs: java
 - `options` ?<[RequestOptions]>

 Optional request parameters.

 ## js-python-fetch-option-headers
-* langs: js, python
+* langs: js, python, csharp
 - `headers` <[Object]<[string], [string]>>

 Allows to set HTTP headers.

 ## js-python-fetch-option-timeout
-* langs: js, python
+* langs: js, python, csharp
 - `timeout` <[float]>

 Request timeout in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.

 ## js-python-fetch-option-failonstatuscode
-* langs: js, python
+* langs: js, python, csharp
 - `failOnStatusCode` <[boolean]>

 Whether to throw on response codes other than 2xx and 3xx. By default response object is returned
@ -343,7 +349,17 @@ Provides an object that will be serialized as html form using `application/x-www
 this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded`
 unless explicitly provided.

-## js-pyhton-fetch-option-multipart
+## csharp-fetch-option-form
+* langs: csharp
+- `form` <[FormData]>
+
+Provides an object that will be serialized as html form using `application/x-www-form-urlencoded` encoding and sent as
+this request body. If this parameter is specified `content-type` header will be set to `application/x-www-form-urlencoded`
+unless explicitly provided.
+
+An instance of [FormData] can be created via [`method: APIRequestContext.createFormData`].
+
+## js-python-fetch-option-multipart
 * langs: js, python
 - `multipart` <[Object]<[string], [string]|[float]|[boolean]|[ReadStream]|[Object]>>
  - `name` <[string]> File name
@ -355,8 +371,19 @@ this request body. If this parameter is specified `content-type` header will be
 unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream)
 or as file-like object containing file name, mime-type and its content.

+## csharp-fetch-option-multipart
+* langs: csharp
+- `multipart` <[FormData]>
+
+Provides an object that will be serialized as html form using `multipart/form-data` encoding and sent as
+this request body. If this parameter is specified `content-type` header will be set to `multipart/form-data`
+unless explicitly provided. File values can be passed either as [`fs.ReadStream`](https://nodejs.org/api/fs.html#fs_class_fs_readstream)
+or as file-like object containing file name, mime-type and its content.
+
+An instance of [FormData] can be created via [`method: APIRequestContext.createFormData`].
+
 ## js-python-fetch-option-data
-* langs: js, python
+* langs: js, python, csharp
 - `data` <[string]|[Buffer]|[Serializable]>

 Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
@ -364,7 +391,7 @@ and `content-type` header will be set to `application/json` if not explicitly se
 set to `application/octet-stream` if not explicitly set.

 ## js-python-fetch-option-ignorehttpserrors
-* langs: js, python
+* langs: js, python, csharp
 - `ignoreHTTPSErrors` <[boolean]>

 Whether to ignore HTTPS errors when sending network requests. Defaults to `false`.
--- a/utils/doclint/generateDotnetApi.js
+++ b/utils/doclint/generateDotnetApi.js
@ -80,7 +80,6 @@ classNameMap.set('Error', 'Exception');
 classNameMap.set('TimeoutError', 'TimeoutException');
 classNameMap.set('EvaluationArgument', 'object');
 classNameMap.set('boolean', 'bool');
-classNameMap.set('Serializable', 'T');
 classNameMap.set('any', 'object');
 classNameMap.set('Buffer', 'byte[]');
 classNameMap.set('path', 'string');
@ -407,7 +406,7 @@ function generateNameDefault(member, name, t, parent) {
          attemptedName = `${parent.name}BoundingBoxResult`;
        if (attemptedName === 'BrowserContextCookie')
          attemptedName = 'BrowserContextCookiesResult';
-        if (attemptedName === 'File')
+        if (attemptedName === 'File' || (parent.name === 'FormData' && attemptedName === 'SetValue'))
          attemptedName = `FilePayload`;
        if (attemptedName === 'Size')
          attemptedName = 'RequestSizesResult';
@ -501,6 +500,7 @@ function renderMethod(member, parent, name, options, out) {
  if (member.args.size === 0
    && type !== 'void'
    && !name.startsWith('Get')
+    && name !== 'CreateFormData'
    && !name.startsWith('PostDataJSON')
    && !name.startsWith('As')) {
    if (!member.async) {
@ -562,8 +562,9 @@ function renderMethod(member, parent, name, options, out) {

    if (arg.name === 'options') {
      if (options.mode === 'options' || options.mode === 'base') {
-        const optionsType = member.clazz.name + name.replace('<T>', '') + 'Options';
-        optionTypes.set(optionsType, arg.type);
+        const optionsType = rewriteSuggestedOptionsName(member.clazz.name + name.replace('<T>', '') + 'Options');
+        if (!optionTypes.has(optionsType) || arg.type.properties.length > optionTypes.get(optionsType).properties.length)
+          optionTypes.set(optionsType, arg.type);
        args.push(`${optionsType}? options = default`);
        argTypeMap.set(`${optionsType}? options = default`, 'options');
        addParamsDoc('options', ['Call options']);
@ -835,6 +836,9 @@ function translateType(type, parent, generateNameCallback = t => t.name, optiona
    return `${type.name}<${types.join(', ')}>`;
  }

+  if (type.name === 'Serializable')
+    return isReturnType ? 'T' : 'object';
+
  // there's a chance this is a name we've already seen before, so check
  // this is also where we map known types, like boolean -> bool, etc.
  const name = classNameMap.get(type.name) || type.name;
@ -894,3 +898,22 @@ function toAsync(name, convert) {
    return name.replace('<', 'Async<');
  return name + 'Async';
 }
+
+/**
+ * @param {string} suggestedName 
+ * @returns {string}
+ */
+function rewriteSuggestedOptionsName(suggestedName) {
+  if ([
+    'APIRequestContextDeleteOptions',
+    'APIRequestContextFetchOptions',
+    'APIRequestContextGetOptions',
+    'APIRequestContextHeadOptions',
+    'APIRequestContextPatchOptions',
+    'APIRequestContextPostOptions',
+    'APIRequestContextPutOptions',
+  ].includes(suggestedName))
+    return 'APIRequestContextOptions';
+  return suggestedName;
+}
+