You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/docs/contributing/add-new-language.md
+2-1Lines changed: 2 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -144,7 +144,8 @@ This parameter **must** be the last parameter of a method, and allow a user to o
144
144
145
145
### Requesters
146
146
147
-
> TODO: informations
147
+
The requester needs to be configurable and capable to be overwriten to use a user defined requester.
148
+
The default requester must be the classic HTTP requester, and it's possible to provide other alternatives like an [Echo Requester](https://github.com/algolia/api-clients-automation/blob/main/clients/algoliasearch-client-javascript/packages/client-common/src/createEchoRequester.ts) that just send the request back.
Copy file name to clipboardExpand all lines: website/docs/contributing/testing/common-test-suite.md
+77-37Lines changed: 77 additions & 37 deletions
Original file line number
Diff line number
Diff line change
@@ -4,8 +4,8 @@ title: Common Test Suite
4
4
5
5
# Common Test Suite
6
6
7
-
The CTS aims at ensuring minimal working operation for the API clients, by comparing the request formed by sample parameters.
8
-
It is automatically generated for all languages, from a JSON entry point.
7
+
The CTS gather multiple types of tests that make sure our API clients generate the correct requests and throws the correct error, it does not aim at testing the engine.
8
+
It is automatically generated for all languages from JSON files and ensure properties are valid by checking specs.
9
9
10
10
:::info
11
11
@@ -17,7 +17,13 @@ Common Test Suite requires all clients to be built.
17
17
18
18
## How to add test
19
19
20
-
The test generation script requires a JSON file name from the `operationId` (e.g. `search.json`), located in the `CTS/<client>/requests/` folder (e.g. `CTS/search/requests/`).
20
+
There are differents type of tests in the CTS:
21
+
22
+
### Requests tests
23
+
24
+
Those tests aims at ensuring minimal working operation for the API clients, by comparing the request formed by sample parameters.
25
+
26
+
The test generation script requires a JSON file name from the `operationId` (e.g. `search.json`), located in the `tests/CTS/methods/requests/<client>/` folder (e.g. `tests/CTS/methods/requests/search/`).
21
27
22
28
> See the [browse test file for the search client](https://github.com/algolia/api-clients-automation/blob/main/tests/CTS/methods/requests/search/browse.json)
23
29
@@ -66,27 +72,40 @@ The test generation script requires a JSON file name from the `operationId` (e.g
66
72
And that's it! If the name of the file matches an `operationId` in the spec, a test will be generated and will be calling the method name `operationId`.
67
73
68
74
The list of `queryParameters` must match exactly the actual value, the CTS has to check the number of query parameters and the value of each.
75
+
**It's important to ensure the number of parameters because the API clients must not set default values, they should be handled by the engine.**
76
+
77
+
### Clients tests
78
+
79
+
The clients tests are located in the folder `tests/CTS/client/<client>`, they aim at testing the constructors and common error thrown by the API, and can be use to build more complex multi-step tests.
80
+
81
+
> TODO
69
82
70
83
## How to add a new language
71
84
72
-
Create a template in [`tests/CTS/methods/requests/templates/<languageName>/requests.mustache`](https://github.com/algolia/api-clients-automation/tree/main/tests/CTS/methods/requests/templates) that parses an array of tests into the test framework of choice.
85
+
### Requests tests
73
86
74
-
> See [implementation of the JavaScript tests](https://github.com/algolia/api-clients-automation/blob/main/tests/CTS/methods/requests/templates/javascript/requests.mustache)
87
+
Create a template in `templates/<languageName>/tests/requests.mustache` that parses an array of tests into the test framework of choice.
88
+
89
+
> See [implementation of the JavaScript tests](https://github.com/algolia/api-clients-automation/blob/main/templates/javascript/tests/requests/requests.mustache)
75
90
76
91
When writing your template, here is a list of variables accessible from `mustache`:
77
92
78
93
```json
79
94
{
80
-
"import": "the name of the package or library to import",
81
95
"client": "the name of the API Client object to instanciate and import",
96
+
"clientPrefix": "the name of the client without Client at the end",
97
+
"hasRegionalHost": "true if the hosts accepts region",
98
+
"defaultRegion": "the region to provide by default to the constructor",
82
99
"blocks": [
83
100
{
84
101
// The list of test to implement
85
102
"operationID": "the name of the endpoint and the cts file to test",
86
103
"tests": [
87
104
{
88
-
"testName": "the descriptive name test (default to `method`)",
89
105
"method": "the method to call on the API Client",
106
+
"testName": "the descriptive name test (default to `method`)",
107
+
"testIndex": "the index of the test to avoid duplicate function name",
108
+
"hasParameters": "true if the method has parameters, useful for `GET` requests",
90
109
"parameters": {
91
110
// Object of all parameters with their name, to be used for languages that require the parameter name
92
111
"parameterName": "value"
@@ -109,49 +128,45 @@ When writing your template, here is a list of variables accessible from `mustach
109
128
"objectName": "SearchParams",
110
129
// oneOfModel empty if there is no oneOf
111
130
"oneOfModel": {
131
+
// the compound type
112
132
"parentClassName": "SearchParams",
113
-
"type": "SearchParamsObject"
133
+
"type": "SearchParamsObject",
134
+
"x-one-of-explicit-name": "true if the name needs to be explicit (types are compatible)"
114
135
},
115
136
// properties used to have unique name and link to parent
116
137
"parent": "theParentObject",
117
138
"suffix": 7,
118
139
"parentSuffix": 6,
140
+
"useAnonymousKey": "true if we are in an array at the first level",
119
141
// boolean indicating if it is the last parameter
120
142
"-last": false
121
143
}
122
144
],
123
-
"requestOptionsWithDataType": [
124
-
{
125
-
"key": "key",
126
-
"value": "value",
127
-
// booleans indicating the data type
128
-
"isArray": false,
129
-
"isObject": true,
130
-
"isFreeFormObject": false,
131
-
"isString": false,
132
-
"isInteger": false,
133
-
"isLong": false,
134
-
"isDouble": false,
135
-
"isEnum": false,
136
-
"isBoolean": false,
137
-
"objectName": "SearchParams",
138
-
// oneOfModel empty if there is no oneOf
139
-
"oneOfModel": {
140
-
"parentClassName": "SearchParams",
141
-
"type": "SearchParamsObject"
142
-
},
143
-
// properties used to have unique name and link to parent
144
-
"parent": "theParentObject",
145
-
"suffix": 7,
146
-
"parentSuffix": 6,
147
-
// boolean indicating if it is the last parameter
148
-
"-last": false
145
+
"parametersWithDataTypeMap": {
146
+
"parameterName": {
147
+
// Same as the parametersWithDataType, where the "key" is really a key
149
148
}
150
-
],
151
-
// boolean indicating if the method has parameters, useful for `GET` requests
152
-
"hasParameters": true,
149
+
},
153
150
// boolean indicating if the method has requestOptions, useful to shape your template only if provided
154
151
"hasRequestOptions": true,
152
+
"requestOptions": {
153
+
"queryParameters": {
154
+
// the raw JSON object
155
+
"parameters": {},
156
+
// list of parameters with enhance types
157
+
"parametersWithDataType": [],
158
+
// map of enhance parameters
159
+
"parametersWithDataTypeMap": {}
160
+
},
161
+
"headers": {
162
+
// the raw JSON object
163
+
"parameters": {},
164
+
// list of parameters with enhance types
165
+
"parametersWithDataType": [],
166
+
// map of enhance parameters
167
+
"parametersWithDataTypeMap": {}
168
+
},
169
+
},
155
170
"request": {
156
171
"path": "the expected path of the request",
157
172
"method": "the expected method: GET, POST, PUT, DELETE or PATCH",
@@ -174,6 +189,31 @@ When writing your template, here is a list of variables accessible from `mustach
174
189
}
175
190
```
176
191
192
+
As well as lambdas to transform strings:
193
+
-`escapeQuotes` - Escapes double quotes characters, replaces `"` with `\"`.
194
+
-`escapeSlash` - Escapes backward slash characters, replaces `\` with `\\`.
195
+
-`lowercase` - Converts all of the characters in this fragment to lower case using the rules of the ROOT locale.
196
+
-`uppercase` - Converts all of the characters in this fragment to upper case using the rules of the ROOT locale.
197
+
-`titlecase` - Converts text in a fragment to title case. For example once upon a time to Once Upon A Time.
198
+
-`camelcase` - Converts text in a fragment to camelCase. For example Input-text to inputText.
199
+
-`indented` - Prepends 4 spaces indention from second line of a fragment on. First line will be indented by Mustache.
200
+
-`indented_8` - Prepends 8 spaces indention from second line of a fragment on. First line will be indented by Mustache.
201
+
-`indented_12` - Prepends 12 spaces indention from second line of a fragment on. First line will be indented by Mustache.
202
+
-`indented_16` - Prepends 16 spaces indention from second line of a fragment on. First line will be indented by Mustache.
203
+
204
+
If specific values are needed for a specific languages, or custom generated files, they can be added using a custom CTS manager:
-`import`: the name of the client package to import from
212
+
213
+
### Clients tests
214
+
215
+
> TODO
216
+
177
217
## Add common tests to every clients
178
218
179
219
You might want to test how every clients behaves, without having to duplicate the same tests. We provide 4 methods on every clients, common to all languages.
0 commit comments