From 7f640d8a494f3717394367dc4280044522c7e687 Mon Sep 17 00:00:00 2001 From: Max Schmitt Date: Mon, 23 May 2022 22:12:57 +0300 Subject: [PATCH] docs(dotnet): add API testing (#13889) --- docs/src/api/class-apirequest.md | 4 +- docs/src/api/class-apirequestcontext.md | 52 ++++++++++++++++++------- docs/src/api/class-apiresponse.md | 1 - docs/src/api/class-browsercontext.md | 3 +- docs/src/api/class-formdata.md | 12 +++++- docs/src/api/class-page.md | 3 +- docs/src/api/class-playwright.md | 3 +- docs/src/api/params.md | 41 +++++++++++++++---- utils/doclint/generateDotnetApi.js | 31 +++++++++++++-- 9 files changed, 116 insertions(+), 34 deletions(-) diff --git a/docs/src/api/class-apirequest.md b/docs/src/api/class-apirequest.md index c48588c59d..317e1f8e71 100644 --- 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 diff --git a/docs/src/api/class-apirequestcontext.md b/docs/src/api/class-apirequestcontext.md index de05aedf22..e63492d662 100644 --- 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-%% diff --git a/docs/src/api/class-apiresponse.md b/docs/src/api/class-apiresponse.md index 2252a7b253..93f7600cc6 100644 --- 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. diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md index 7d30bb6a69..7a778d2f68 100644 --- 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. diff --git a/docs/src/api/class-formdata.md b/docs/src/api/class-formdata.md index 76fe7640db..b5590eadd9 100644 --- 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. diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index c64fda9290..77e3568806 100644 --- 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 diff --git a/docs/src/api/class-playwright.md b/docs/src/api/class-playwright.md index 055c6efe85..dfb4db3293 100644 --- 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. diff --git a/docs/src/api/params.md b/docs/src/api/params.md index 3b3bf57fcc..bcd7962959 100644 --- 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`. diff --git a/utils/doclint/generateDotnetApi.js b/utils/doclint/generateDotnetApi.js index eedf19ad50..9a71ecee54 100644 --- 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('', '') + 'Options'; - optionTypes.set(optionsType, arg.type); + const optionsType = rewriteSuggestedOptionsName(member.clazz.name + name.replace('', '') + '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; +} +