@dichovsky/testrail-api-client 1.0.0 → 2.1.0

package/src/modules/projects.ts

@@ -0,0 +1,67 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { Project, AddProjectPayload, UpdateProjectPayload } from '../types.js';
+import { ProjectSchema } from '../schemas.js';
+import { z } from 'zod';
+
+export class ProjectModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    /**
+     * Get a project by ID.
+     * @throws {TestRailValidationError} When projectId is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async getProject(projectId: number): Promise<Project> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse(ProjectSchema, await this.client.request<unknown>('GET', `get_project/${projectId}`));
+    }
+
+    /**
+     * Get all projects.
+     * @throws {TestRailValidationError} When limit or offset is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async getProjects(limit?: number, offset?: number): Promise<Project[]> {
+        this.client.validatePaginationParams(limit, offset);
+        const endpoint = this.client.buildEndpoint('get_projects', { limit, offset });
+        const raw = await this.client.request<unknown>('GET', endpoint);
+        return (
+            this.client.parse<{ projects?: Project[] }>(z.object({ projects: z.array(ProjectSchema).optional() }), raw)
+                .projects ?? []
+        );
+    }
+
+    /**
+     * Add a new project.
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async addProject(payload: AddProjectPayload): Promise<Project> {
+        return this.client.parse<Project>(
+            ProjectSchema,
+            await this.client.request<unknown>('POST', 'add_project', payload),
+        );
+    }
+
+    /**
+     * Update an existing project.
+     * @throws {TestRailValidationError} When projectId is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async updateProject(projectId: number, payload: UpdateProjectPayload): Promise<Project> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<Project>(
+            ProjectSchema,
+            await this.client.request<unknown>('POST', `update_project/${projectId}`, payload),
+        );
+    }
+
+    /**
+     * Delete a project.
+     * @throws {TestRailValidationError} When projectId is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async deleteProject(projectId: number): Promise<void> {
+        this.client.validateId(projectId, 'projectId');
+        await this.client.request<void>('POST', `delete_project/${projectId}`);
+    }
+}

package/src/modules/reports.ts

@@ -0,0 +1,23 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { Report, ReportResult } from '../types.js';
+import { ReportSchema, ReportResultSchema } from '../schemas.js';
+
+export class ReportModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    async getReports(projectId: number): Promise<Report[]> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<Report[]>(
+            ReportSchema.array(),
+            await this.client.request<unknown>('GET', `get_reports/${projectId}`),
+        );
+    }
+
+    async runReport(reportTemplateId: number): Promise<ReportResult> {
+        this.client.validateId(reportTemplateId, 'reportTemplateId');
+        return this.client.parse<ReportResult>(
+            ReportResultSchema,
+            await this.client.request<unknown>('GET', `run_report/${reportTemplateId}`),
+        );
+    }
+}

package/src/modules/results.ts

@@ -0,0 +1,90 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { Result, GetResultsOptions } from '../types.js';
+import type { AddResultPayload, AddResultsForCasesPayload } from '../schemas.js';
+import { ResultSchema } from '../schemas.js';
+import { serializeIdList } from '../utils.js';
+import { z } from 'zod';
+
+export class ResultModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    async getResults(testId: number, options?: GetResultsOptions): Promise<Result[]> {
+        this.client.validateId(testId, 'testId');
+        this.client.validatePaginationParams(options?.limit, options?.offset);
+        const endpoint = this.client.buildEndpoint(`get_results/${testId}`, {
+            created_after: options?.created_after,
+            created_before: options?.created_before,
+            created_by: serializeIdList(options?.created_by),
+            status_id: serializeIdList(options?.status_id),
+            limit: options?.limit,
+            offset: options?.offset,
+        });
+        const raw = await this.client.request<unknown>('GET', endpoint);
+        return (
+            this.client.parse<{ results?: Result[] }>(z.object({ results: z.array(ResultSchema).optional() }), raw)
+                .results ?? []
+        );
+    }
+
+    async getResultsForCase(runId: number, caseId: number, options?: GetResultsOptions): Promise<Result[]> {
+        this.client.validateId(runId, 'runId');
+        this.client.validateId(caseId, 'caseId');
+        this.client.validatePaginationParams(options?.limit, options?.offset);
+        const endpoint = this.client.buildEndpoint(`get_results_for_case/${runId}/${caseId}`, {
+            created_after: options?.created_after,
+            created_before: options?.created_before,
+            created_by: serializeIdList(options?.created_by),
+            status_id: serializeIdList(options?.status_id),
+            limit: options?.limit,
+            offset: options?.offset,
+        });
+        const raw = await this.client.request<unknown>('GET', endpoint);
+        return (
+            this.client.parse<{ results?: Result[] }>(z.object({ results: z.array(ResultSchema).optional() }), raw)
+                .results ?? []
+        );
+    }
+
+    async getResultsForRun(runId: number, options?: GetResultsOptions): Promise<Result[]> {
+        this.client.validateId(runId, 'runId');
+        this.client.validatePaginationParams(options?.limit, options?.offset);
+        const endpoint = this.client.buildEndpoint(`get_results_for_run/${runId}`, {
+            created_after: options?.created_after,
+            created_before: options?.created_before,
+            created_by: serializeIdList(options?.created_by),
+            status_id: serializeIdList(options?.status_id),
+            limit: options?.limit,
+            offset: options?.offset,
+        });
+        const raw = await this.client.request<unknown>('GET', endpoint);
+        return (
+            this.client.parse<{ results?: Result[] }>(z.object({ results: z.array(ResultSchema).optional() }), raw)
+                .results ?? []
+        );
+    }
+
+    async addResult(testId: number, payload: AddResultPayload): Promise<Result> {
+        this.client.validateId(testId, 'testId');
+        return this.client.parse<Result>(
+            ResultSchema,
+            await this.client.request<unknown>('POST', `add_result/${testId}`, payload),
+        );
+    }
+
+    async addResultForCase(runId: number, caseId: number, payload: AddResultPayload): Promise<Result> {
+        this.client.validateId(runId, 'runId');
+        this.client.validateId(caseId, 'caseId');
+        return this.client.parse<Result>(
+            ResultSchema,
+            await this.client.request<unknown>('POST', `add_result_for_case/${runId}/${caseId}`, payload),
+        );
+    }
+
+    async addResultsForCases(runId: number, payload: AddResultsForCasesPayload): Promise<Result[]> {
+        this.client.validateId(runId, 'runId');
+        return this.client.parse<Result[]>(
+            z.array(ResultSchema),
+            await this.client.request<unknown>('POST', `add_results_for_cases/${runId}`, payload),
+        );
+    }
+}

package/src/modules/runs.ts

@@ -0,0 +1,70 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { Run, GetRunsOptions } from '../types.js';
+import type { AddRunPayload, UpdateRunPayload } from '../schemas.js';
+import { RunSchema } from '../schemas.js';
+import { z } from 'zod';
+
+export class RunModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    async getRun(runId: number): Promise<Run> {
+        this.client.validateId(runId, 'runId');
+        return this.client.parse<Run>(RunSchema, await this.client.request<unknown>('GET', `get_run/${runId}`));
+    }
+
+    async getRuns(projectId: number, options?: GetRunsOptions): Promise<Run[]> {
+        this.client.validateId(projectId, 'projectId');
+        const { createdAfter, createdBefore, createdBy, isCompleted, milestoneId, refsFilter, suiteId, limit, offset } =
+            options ?? {};
+        this.client.validatePaginationParams(limit, offset);
+        if (milestoneId !== undefined) {
+            this.client.validateId(milestoneId, 'milestoneId');
+        }
+        if (suiteId !== undefined) {
+            this.client.validateId(suiteId, 'suiteId');
+        }
+        if (createdBy !== undefined) {
+            createdBy.forEach((userId) => this.client.validateId(userId, 'createdBy'));
+        }
+        const createdByFilter = createdBy && createdBy.length > 0 ? createdBy.join(',') : undefined;
+        const endpoint = this.client.buildEndpoint(`get_runs/${projectId}`, {
+            created_after: createdAfter,
+            created_before: createdBefore,
+            created_by: createdByFilter,
+            is_completed: isCompleted !== undefined ? (isCompleted ? 1 : 0) : undefined,
+            milestone_id: milestoneId,
+            refs_filter: refsFilter,
+            suite_id: suiteId,
+            limit,
+            offset,
+        });
+        const raw = await this.client.request<unknown>('GET', endpoint);
+        return this.client.parse<{ runs?: Run[] }>(z.object({ runs: z.array(RunSchema).optional() }), raw).runs ?? [];
+    }
+
+    async addRun(projectId: number, payload: AddRunPayload): Promise<Run> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<Run>(
+            RunSchema,
+            await this.client.request<unknown>('POST', `add_run/${projectId}`, payload),
+        );
+    }
+
+    async updateRun(runId: number, payload: UpdateRunPayload): Promise<Run> {
+        this.client.validateId(runId, 'runId');
+        return this.client.parse<Run>(
+            RunSchema,
+            await this.client.request<unknown>('POST', `update_run/${runId}`, payload),
+        );
+    }
+
+    async closeRun(runId: number): Promise<Run> {
+        this.client.validateId(runId, 'runId');
+        return this.client.parse<Run>(RunSchema, await this.client.request<unknown>('POST', `close_run/${runId}`));
+    }
+
+    async deleteRun(runId: number): Promise<void> {
+        this.client.validateId(runId, 'runId');
+        await this.client.request<void>('POST', `delete_run/${runId}`);
+    }
+}

package/src/modules/sections.ts

@@ -0,0 +1,55 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { Section, AddSectionPayload, UpdateSectionPayload } from '../types.js';
+import { SectionSchema } from '../schemas.js';
+import { z } from 'zod';
+
+export class SectionModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    async getSection(sectionId: number): Promise<Section> {
+        this.client.validateId(sectionId, 'sectionId');
+        return this.client.parse<Section>(
+            SectionSchema,
+            await this.client.request<unknown>('GET', `get_section/${sectionId}`),
+        );
+    }
+
+    async getSections(
+        projectId: number,
+        options?: { suiteId?: number; limit?: number; offset?: number },
+    ): Promise<Section[]> {
+        this.client.validateId(projectId, 'projectId');
+        const { suiteId, limit, offset } = options ?? {};
+        if (suiteId !== undefined) {
+            this.client.validateId(suiteId, 'suiteId');
+        }
+        this.client.validatePaginationParams(limit, offset);
+        const endpoint = this.client.buildEndpoint(`get_sections/${projectId}`, { suite_id: suiteId, limit, offset });
+        const raw = await this.client.request<unknown>('GET', endpoint);
+        return (
+            this.client.parse<{ sections?: Section[] }>(z.object({ sections: z.array(SectionSchema).optional() }), raw)
+                .sections ?? []
+        );
+    }
+
+    async addSection(projectId: number, payload: AddSectionPayload): Promise<Section> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<Section>(
+            SectionSchema,
+            await this.client.request<unknown>('POST', `add_section/${projectId}`, payload),
+        );
+    }
+
+    async updateSection(sectionId: number, payload: UpdateSectionPayload): Promise<Section> {
+        this.client.validateId(sectionId, 'sectionId');
+        return this.client.parse<Section>(
+            SectionSchema,
+            await this.client.request<unknown>('POST', `update_section/${sectionId}`, payload),
+        );
+    }
+
+    async deleteSection(sectionId: number): Promise<void> {
+        this.client.validateId(sectionId, 'sectionId');
+        await this.client.request<void>('POST', `delete_section/${sectionId}`);
+    }
+}

package/src/modules/sharedSteps.ts

@@ -0,0 +1,44 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { SharedStep, AddSharedStepPayload, UpdateSharedStepPayload } from '../types.js';
+import { SharedStepSchema } from '../schemas.js';
+
+export class SharedStepModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    async getSharedStep(sharedStepId: number): Promise<SharedStep> {
+        this.client.validateId(sharedStepId, 'sharedStepId');
+        return this.client.parse<SharedStep>(
+            SharedStepSchema,
+            await this.client.request<unknown>('GET', `get_shared_step/${sharedStepId}`),
+        );
+    }
+
+    async getSharedSteps(projectId: number): Promise<SharedStep[]> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<SharedStep[]>(
+            SharedStepSchema.array(),
+            await this.client.request<unknown>('GET', `get_shared_steps/${projectId}`),
+        );
+    }
+
+    async addSharedStep(projectId: number, payload: AddSharedStepPayload): Promise<SharedStep> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<SharedStep>(
+            SharedStepSchema,
+            await this.client.request<unknown>('POST', `add_shared_step/${projectId}`, payload),
+        );
+    }
+
+    async updateSharedStep(sharedStepId: number, payload: UpdateSharedStepPayload): Promise<SharedStep> {
+        this.client.validateId(sharedStepId, 'sharedStepId');
+        return this.client.parse<SharedStep>(
+            SharedStepSchema,
+            await this.client.request<unknown>('POST', `update_shared_step/${sharedStepId}`, payload),
+        );
+    }
+
+    async deleteSharedStep(sharedStepId: number): Promise<void> {
+        this.client.validateId(sharedStepId, 'sharedStepId');
+        await this.client.request<void>('POST', `delete_shared_step/${sharedStepId}`);
+    }
+}

package/src/modules/suites.ts

@@ -0,0 +1,67 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { Suite, AddSuitePayload, UpdateSuitePayload } from '../types.js';
+import { SuiteSchema } from '../schemas.js';
+import { z } from 'zod';
+
+export class SuiteModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    /**
+     * Get a suite by ID.
+     * @throws {TestRailValidationError} When suiteId is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async getSuite(suiteId: number): Promise<Suite> {
+        this.client.validateId(suiteId, 'suiteId');
+        return this.client.parse<Suite>(SuiteSchema, await this.client.request<unknown>('GET', `get_suite/${suiteId}`));
+    }
+
+    /**
+     * Get all suites for a project.
+     * @throws {TestRailValidationError} When projectId is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async getSuites(projectId: number): Promise<Suite[]> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<Suite[]>(
+            z.array(SuiteSchema),
+            await this.client.request<unknown>('GET', `get_suites/${projectId}`),
+        );
+    }
+
+    /**
+     * Add a suite to a project.
+     * @throws {TestRailValidationError} When projectId is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async addSuite(projectId: number, payload: AddSuitePayload): Promise<Suite> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<Suite>(
+            SuiteSchema,
+            await this.client.request<unknown>('POST', `add_suite/${projectId}`, payload),
+        );
+    }
+
+    /**
+     * Update a suite.
+     * @throws {TestRailValidationError} When suiteId is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async updateSuite(suiteId: number, payload: UpdateSuitePayload): Promise<Suite> {
+        this.client.validateId(suiteId, 'suiteId');
+        return this.client.parse<Suite>(
+            SuiteSchema,
+            await this.client.request<unknown>('POST', `update_suite/${suiteId}`, payload),
+        );
+    }
+
+    /**
+     * Delete a suite.
+     * @throws {TestRailValidationError} When suiteId is invalid
+     * @throws {TestRailApiError} When the API request fails
+     */
+    async deleteSuite(suiteId: number): Promise<void> {
+        this.client.validateId(suiteId, 'suiteId');
+        await this.client.request<void>('POST', `delete_suite/${suiteId}`);
+    }
+}

package/src/modules/tests.ts

@@ -0,0 +1,28 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { Test, GetTestsOptions } from '../types.js';
+import { TestSchema } from '../schemas.js';
+import { serializeIdList } from '../utils.js';
+import { z } from 'zod';
+
+export class TestModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    async getTest(testId: number): Promise<Test> {
+        this.client.validateId(testId, 'testId');
+        return this.client.parse<Test>(TestSchema, await this.client.request<unknown>('GET', `get_test/${testId}`));
+    }
+
+    async getTests(runId: number, options?: GetTestsOptions): Promise<Test[]> {
+        this.client.validateId(runId, 'runId');
+        this.client.validatePaginationParams(options?.limit, options?.offset);
+        const endpoint = this.client.buildEndpoint(`get_tests/${runId}`, {
+            status_id: serializeIdList(options?.status_id),
+            limit: options?.limit,
+            offset: options?.offset,
+        });
+        const raw = await this.client.request<unknown>('GET', endpoint);
+        return (
+            this.client.parse<{ tests?: Test[] }>(z.object({ tests: z.array(TestSchema).optional() }), raw).tests ?? []
+        );
+    }
+}

package/src/modules/users.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { TestRailValidationError } from '../errors.js';
+import { UserSchema, GroupSchema } from '../schemas.js';
+import { TestRailClientCore } from '../client-core.js';
+import type { AddGroupPayload, AddUserPayload, Group, UpdateGroupPayload, UpdateUserPayload, User } from '../types.js';
+
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export class UsersModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    async getUser(userId: number): Promise<User> {
+        this.client.validateId(userId, 'userId');
+        return this.client.parse<User>(UserSchema, await this.client.request<unknown>('GET', `get_user/${userId}`));
+    }
+
+    async getUserByEmail(email: string): Promise<User> {
+        if (!EMAIL_REGEX.test(email)) {
+            throw new TestRailValidationError('Invalid email format');
+        }
+
+        const endpoint = this.client.buildEndpoint('get_user_by_email', { email });
+        return this.client.parse<User>(UserSchema, await this.client.request<unknown>('GET', endpoint));
+    }
+
+    async getUsers(limit?: number, offset?: number, projectId?: number): Promise<User[]> {
+        this.client.validatePaginationParams(limit, offset);
+        if (projectId !== undefined) {
+            this.client.validateId(projectId, 'projectId');
+        }
+
+        const endpoint = this.client.buildEndpoint(projectId !== undefined ? `get_users/${projectId}` : 'get_users', {
+            limit,
+            offset,
+        });
+        const raw = await this.client.request<unknown>('GET', endpoint);
+
+        return (
+            this.client.parse<{ users?: User[] }>(z.object({ users: z.array(UserSchema).optional() }), raw).users ?? []
+        );
+    }
+
+    async getCurrentUser(): Promise<User> {
+        return this.client.parse<User>(UserSchema, await this.client.request<unknown>('GET', 'get_current_user'));
+    }
+
+    async addUser(payload: AddUserPayload): Promise<User> {
+        return this.client.parse<User>(UserSchema, await this.client.request<unknown>('POST', 'add_user', payload));
+    }
+
+    async updateUser(userId: number, payload: UpdateUserPayload): Promise<User> {
+        this.client.validateId(userId, 'userId');
+        return this.client.parse<User>(
+            UserSchema,
+            await this.client.request<unknown>('POST', `update_user/${userId}`, payload),
+        );
+    }
+
+    async getGroup(groupId: number): Promise<Group> {
+        this.client.validateId(groupId, 'groupId');
+        return this.client.parse<Group>(GroupSchema, await this.client.request<unknown>('GET', `get_group/${groupId}`));
+    }
+
+    async getGroups(): Promise<Group[]> {
+        return this.client.parse<Group[]>(
+            z.array(GroupSchema),
+            await this.client.request<unknown>('GET', 'get_groups'),
+        );
+    }
+
+    async addGroup(payload: AddGroupPayload): Promise<Group> {
+        return this.client.parse<Group>(GroupSchema, await this.client.request<unknown>('POST', 'add_group', payload));
+    }
+
+    async updateGroup(groupId: number, payload: UpdateGroupPayload): Promise<Group> {
+        this.client.validateId(groupId, 'groupId');
+        return this.client.parse<Group>(
+            GroupSchema,
+            await this.client.request<unknown>('POST', `update_group/${groupId}`, payload),
+        );
+    }
+
+    async deleteGroup(groupId: number): Promise<void> {
+        this.client.validateId(groupId, 'groupId');
+        await this.client.request<void>('POST', `delete_group/${groupId}`);
+    }
+}

package/src/modules/variables.ts

@@ -0,0 +1,36 @@
+import { TestRailClientCore } from '../client-core.js';
+import type { Variable, AddVariablePayload, UpdateVariablePayload } from '../types.js';
+import { VariableSchema } from '../schemas.js';
+
+export class VariableModule {
+    constructor(private readonly client: TestRailClientCore) {}
+
+    async getVariables(projectId: number): Promise<Variable[]> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<Variable[]>(
+            VariableSchema.array(),
+            await this.client.request<unknown>('GET', `get_variables/${projectId}`),
+        );
+    }
+
+    async addVariable(projectId: number, payload: AddVariablePayload): Promise<Variable> {
+        this.client.validateId(projectId, 'projectId');
+        return this.client.parse<Variable>(
+            VariableSchema,
+            await this.client.request<unknown>('POST', `add_variable/${projectId}`, payload),
+        );
+    }
+
+    async updateVariable(variableId: number, payload: UpdateVariablePayload): Promise<Variable> {
+        this.client.validateId(variableId, 'variableId');
+        return this.client.parse<Variable>(
+            VariableSchema,
+            await this.client.request<unknown>('POST', `update_variable/${variableId}`, payload),
+        );
+    }
+
+    async deleteVariable(variableId: number): Promise<void> {
+        this.client.validateId(variableId, 'variableId');
+        await this.client.request<void>('POST', `delete_variable/${variableId}`);
+    }
+}