9
}));
10
11
const { ApiEndpointsTable } = await import("../../components/api-endpoints-table");
12
+const { ApiPageTitle } = await import("../../components/api-page-title");
13
+const { DEPRECATED_API_LEGACY_TITLE } = await import("../../components/legacy-badge");
14
+const { getDeprecatedApiSidebarName } = await import("../../lib/deprecated-api-sidebar");
15
+const { getApiDisplayTitle, isApiPageDeprecated } = await import("../../lib/api-deprecation");
16
17
const DOCS_DIR = join(import.meta.dir, "../..");
18
const GENERATOR_PATH = join(DOCS_DIR, "scripts/generate-api-index.ts");
119
});
120
121
describe("deprecated API endpoints", () => {
122
+ test("removes only a trailing deprecation marker from deprecated display titles", () => {
123
+ expect(getApiDisplayTitle("Deprecated task endpoint (DEPRECATED)", true)).toBe(
124
+ "Deprecated task endpoint",
125
+ );
126
+ expect(getApiDisplayTitle("Deprecated task endpoint (deprecated)", true)).toBe(
127
+ "Deprecated task endpoint",
128
+ );
129
+ expect(getApiDisplayTitle("Active task endpoint (DEPRECATED)", false)).toBe(
130
+ "Active task endpoint (DEPRECATED)",
131
+ );
132
+ expect(getApiDisplayTitle("Deprecated endpoint details", true)).toBe(
133
+ "Deprecated endpoint details",
134
+ );
135
+ });
136
+
137
+ test("renders Legacy on a deprecated API endpoint detail title", () => {
138
+ const operation = {
139
+ method: "get",
140
+ path: "/v3.1/tasks/deprecated",
141
+ };
142
+ const pageData = {
143
+ getSchema: () => ({
144
+ dereferenced: {
145
+ paths: {
146
+ [operation.path]: {
147
+ [operation.method]: { deprecated: true },
148
+ },
149
+ },
150
+ },
151
+ }),
152
+ };
153
+
154
+ const deprecated = isApiPageDeprecated(pageData, [operation]);
155
+ const html = renderToStaticMarkup(
156
+ <ApiPageTitle
157
+ title="Deprecated task endpoint (DEPRECATED)"
158
+ version="3.1"
159
+ deprecated={deprecated}
160
+ />,
161
+ );
162
+
163
+ expect(deprecated).toBe(true);
164
+ expect(html).toContain("<span>Deprecated task endpoint</span>");
165
+ expect(html).not.toContain("Deprecated task endpoint (DEPRECATED)");
166
+ expect(html).toContain(
167
+ 'class="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-2xl font-semibold"',
168
+ );
169
+ expect(html).toContain('class="inline-flex shrink-0 items-center gap-2"');
170
+ expect(html.match(/>Legacy<\/span>/g)).toHaveLength(1);
171
+ expect(html).toContain(
172
+ 'title="Deprecated API endpoint; kept for existing integrations and may be removed in a future release"',
173
+ );
174
+ });
175
+
176
+ test("omits Legacy from an active API endpoint detail title", () => {
177
+ const operation = {
178
+ method: "post",
179
+ path: "/v3.1/tasks/active",
180
+ };
181
+ const pageData = {
182
+ getSchema: () => ({
183
+ dereferenced: {
184
+ paths: {
185
+ [operation.path]: {
186
+ [operation.method]: {},
187
+ },
188
+ },
189
+ },
190
+ }),
191
+ };
192
+
193
+ const deprecated = isApiPageDeprecated(pageData, [operation]);
194
+ const html = renderToStaticMarkup(
195
+ <ApiPageTitle
196
+ title="Active task endpoint"
197
+ version="3.1"
198
+ deprecated={deprecated}
199
+ />,
200
+ );
201
+
202
+ expect(deprecated).toBe(false);
203
+ expect(html).not.toContain(">Legacy</span>");
204
+ });
205
+
206
+ test("replaces the sidebar title marker with a compact Legacy badge", () => {
207
+ const operation = {
208
+ method: "get",
209
+ path: "/v3.1/tasks/deprecated",
210
+ };
211
+ const pageData = {
212
+ getSchema: () => ({
213
+ dereferenced: {
214
+ paths: {
215
+ [operation.path]: {
216
+ [operation.method]: { deprecated: true },
217
+ },
218
+ },
219
+ },
220
+ }),
221
+ };
222
+
223
+ const html = renderToStaticMarkup(
224
+ <>
225
+ {getDeprecatedApiSidebarName("Deprecated task endpoint (DEPRECATED)", pageData, [
226
+ operation,
227
+ ])}
228
+ </>,
229
+ );
230
+
231
+ expect(html).toContain("Deprecated task endpoint");
232
+ expect(html).not.toContain("(DEPRECATED)");
233
+ expect(html.match(/>Legacy<\/span>/g)).toHaveLength(1);
234
+ expect(html).toContain("text-[10px]");
235
+ expect(html).toContain(DEPRECATED_API_LEGACY_TITLE);
236
+ });
237
+
238
+ test("keeps an unflagged sidebar title unchanged", () => {
239
+ const operation = {
240
+ method: "post",
241
+ path: "/v3.1/tasks/active",
242
+ };
243
+ const pageData = {
244
+ getSchema: () => ({
245
+ dereferenced: {
246
+ paths: {
247
+ [operation.path]: {
248
+ [operation.method]: {},
249
+ },
250
+ },
251
+ },
252
+ }),
253
+ };
254
+
255
+ const html = renderToStaticMarkup(
256
+ <>
257
+ {getDeprecatedApiSidebarName("Active task endpoint (DEPRECATED)", pageData, [operation])}
258
+ </>,
259
+ );
260
+
261
+ expect(html).toBe("Active task endpoint (DEPRECATED)");
262
+ expect(html).not.toContain(">Legacy</span>");
263
+ });
264
+
265
test("serializes legacy only for deprecated v3.1 and v3 operations", async () => {
266
const fixtureDir = await generateFixture();
267
const v31Content = await readFile(
294
method: "GET",
295
pathV31: "/v3.1/tasks/deprecated",
296
pathV3: "/v3/tasks/deprecated",
150
- summary: "Deprecated task endpoint",
297
+ summary: "Deprecated task endpoint (DEPRECATED)",
298
href: "/reference/api-reference/tasks/getDeprecatedTask",
299
legacy: true,
300
},
309
/>,
310
);
311
312
+ expect(html).toContain(
313
+ '<a href="/reference/api-reference/tasks/getDeprecatedTask">Deprecated task endpoint</a>',
314
+ );
315
+ expect(html).not.toContain("Deprecated task endpoint (DEPRECATED)");
316
expect(
317
html.match(
318
/title="Deprecated API endpoint; kept for existing integrations and may be removed in a future release"/g,