diff --git a/src/data/navigation.js b/src/data/navigation.js index 6452dcd..4db95d4 100644 --- a/src/data/navigation.js +++ b/src/data/navigation.js @@ -7,6 +7,7 @@ const navigation = [ { title: "Products", href: "/docs/api/products" }, { title: "Features", href: "/docs/api/features" }, { title: "User Stories", href: "/docs/api/user-stories" }, + { title: "User Story Version Executions", href: "/docs/api/user-story-version-executions" }, { title: "Test Environments", href: "/docs/api/test-environments" }, { title: "Binary Apps", href: "/docs/api/binary-apps" }, { title: "Exploratory Tests", href: "/docs/api/exploratory-tests" }, diff --git a/src/pages/docs/api/exploratory-tests.md b/src/pages/docs/api/exploratory-tests.md index b2f38c4..6e34a91 100644 --- a/src/pages/docs/api/exploratory-tests.md +++ b/src/pages/docs/api/exploratory-tests.md @@ -1,6 +1,6 @@ --- title: Exploratory Tests -description: Create and manage exploratory tests +description: Create, update, launch, duplicate, and manage exploratory tests --- Create and manage exploratory tests for your products. @@ -22,6 +22,12 @@ Retrieve a specific exploratory test by ID. - `exploratory_test_id` (number, required) - ID of the Exploratory test +**Query Parameters:** + +| Parameter | Type | Required | Description | +| ------------ | ----- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `includes[]` | array | No | Optional associations to expand. Supported value: `user_stories`. When included, `user_stories` in each feature returns objects with `id`, `path`, `title`, `feature_id` instead of plain strings. | + **Example Request:** {% code language="bash" showLineNumbers=true %} @@ -35,7 +41,7 @@ curl -X GET "https://api.test.io/customer/v2/exploratory_tests/123" \ **Response:** `200 OK` -Returns the exploratory test object with full details including test environment, features, requirements, and more. +Returns the exploratory test object with full details including test environment, features, requirements, and more. By default, `user_stories` in each feature is an array of path strings. Pass `includes[]=user_stories` to expand them into objects. ## List exploratory tests @@ -49,6 +55,12 @@ Returns a paginated list of exploratory tests for the specified product. - `page` (number, optional) - Page number of the result set - `per_page` (number, optional) - Number of items per page when pagination is applied. Used only if **page** is provided. Default: 25 +**Query Parameters:** + +| Parameter | Type | Required | Description | +| ------------ | ----- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `includes[]` | array | No | Optional associations to expand. Supported value: `user_stories`. See [Get exploratory test](#get-exploratory-test) for details. | + **Notes:** If `page` parameter is omitted, pagination is not applied and the last 150 tests are returned. @@ -211,6 +223,150 @@ All attributes must be provided inside the root object `exploratory_test`. Returns the created exploratory test object with full details. +> **Note on `user_stories` in response**: The `user_stories` field in the response is an array of path strings by default. To get expanded user story objects, use `includes[]=user_stories` on the GET endpoints (see [Get exploratory test](#get-exploratory-test)). + +## Update exploratory test + +Updates an existing exploratory test. You can modify test parameters, features, and the test environment. + +**Endpoint:** `PUT /exploratory_tests/{exploratory_test_id}` + +**Parameters:** + +- `exploratory_test_id` (number, required) - ID of the Exploratory test + +All attributes must be provided inside the root object `exploratory_test`. Only provided fields will be updated. + +### Attributes + +Same attributes as [Create exploratory test](#create-exploratory-test), with the following differences: + +- `test_environment` (object, **optional**) - Test environment related attributes. If omitted, the existing test environment is kept +- `features` (array, optional) - Features to be tested. If omitted, existing features are kept +- `test_template` is **not available** for updates + +**Example Request:** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X PUT "https://api.test.io/customer/v2/exploratory_tests/123" \ + -H "Authorization: Token YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "exploratory_test": { + "test_title": "Updated Checkout Flow Test", + "goal": "Re-validate the checkout process after fixes", + "features": [ + { + "id": 15 + }, + { + "title": "Payment Flow", + "description": "Verify payment methods work correctly.", + "howtofind": "Proceed to payment after adding items to cart.", + "user_stories": [ + "As a customer, I want to pay with a credit card.", + "As a customer, I want to apply a discount code." + ] + } + ] + } + }' +``` + +{% /code %} + +**Response:** `200 OK` + +Returns the updated exploratory test object with full details. + +## Launch exploratory test + +Launches a previously created exploratory test that has not been launched yet. This is useful when the test was created with `auto_launch: false`. + +**Endpoint:** `POST /exploratory_tests/{exploratory_test_id}/launch` + +**Parameters:** + +- `exploratory_test_id` (number, required) - ID of the Exploratory test + +**Example Request:** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X POST "https://api.test.io/customer/v2/exploratory_tests/123/launch" \ + -H "Authorization: Token YOUR_API_TOKEN" +``` + +{% /code %} + +**Response:** `200 OK` + +Returns the launched exploratory test object with full details. + +## Duplicate exploratory test + +Creates a copy of an existing exploratory test. The duplicated test will have the same configuration (features, test environment, requirements, etc.) but will be a new, independent test. + +**Endpoint:** `POST /exploratory_tests/{exploratory_test_id}/duplicate` + +**Parameters:** + +- `exploratory_test_id` (number, required) - ID of the Exploratory test to duplicate + +**Example Request:** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X POST "https://api.test.io/customer/v2/exploratory_tests/123/duplicate" \ + -H "Authorization: Token YOUR_API_TOKEN" +``` + +{% /code %} + +**Response:** `200 OK` + +Returns the newly created (duplicated) exploratory test object with full details. The duplicated test will have a new ID. + +## Create test template from exploratory test + +Creates a reusable test template based on an existing exploratory test's configuration. The template captures the test scenario settings (features, requirements, etc.) so they can be reused when creating future tests. + +**Endpoint:** `POST /exploratory_tests/{exploratory_test_id}/templates` + +**Parameters:** + +- `exploratory_test_id` (number, required) - ID of the Exploratory test to create a template from + +**Request Body:** + +- `test_template` (object, required) + - `title` (string, required) - Title for the new test template + +**Example Request:** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X POST "https://api.test.io/customer/v2/exploratory_tests/123/templates" \ + -H "Authorization: Token YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "test_template": { + "title": "Checkout Flow Template" + } + }' +``` + +{% /code %} + +**Response:** `201 Created` + +Returns the newly created test template object. See [Test Templates](/docs/api/test-templates) for more details on the response format. + ### Building Requirements Array The `requirements` array allows you to specify device targeting for your test. Each requirement object can include: diff --git a/src/pages/docs/api/features.md b/src/pages/docs/api/features.md index a1b6978..114880f 100644 --- a/src/pages/docs/api/features.md +++ b/src/pages/docs/api/features.md @@ -1,6 +1,6 @@ --- title: Features -description: List and create features +description: List, create, and copy features --- Manage features for your products. @@ -17,6 +17,14 @@ Retrieve all features for a specific product. - `product_id` (number, required) - ID of the Product +**Query Parameters:** + +| Parameter | Type | Required | Description | +| ------------ | ----- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `includes[]` | array | No | Optional associations to expand. Supported value: `user_stories`. When included, `user_stories` returns objects with `id`, `path`, `title`, `feature_id` instead of plain strings. | + +> For products **with sections**, use `GET /products/{product_id}/sections/{section_id}/features` to list features scoped to a specific section. See [List features by section](#list-features-by-section) below. + **Example Request:** {% code language="bash" showLineNumbers=true %} @@ -30,6 +38,8 @@ curl -X GET "https://api.test.io/customer/v2/products/1/features" \ **Response:** `200 OK` +By default, `user_stories` is an array of path strings: + {% code language="json" showLineNumbers=true %} ```json @@ -48,6 +58,100 @@ curl -X GET "https://api.test.io/customer/v2/products/1/features" \ {% /code %} +**Example Request (with expanded user stories):** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X GET "https://api.test.io/customer/v2/products/1/features?includes[]=user_stories" \ + -H "Authorization: Token YOUR_API_TOKEN" +``` + +{% /code %} + +**Response:** `200 OK` + +When `includes[]=user_stories` is passed, each user story is returned as an object: + +{% code language="json" showLineNumbers=true %} + +```json +{ + "features": [ + { + "id": 1, + "title": "Account Management", + "description": "Manage your account information", + "howtofind": "Top right of the screen", + "user_stories": [ + { + "id": 10, + "path": "User story 1", + "title": "User story 1", + "feature_id": 1 + }, + { + "id": 11, + "path": "User story 2", + "title": "User story 2", + "feature_id": 1 + } + ] + } + ] +} +``` + +{% /code %} + +## List features by section + +Retrieve all features for a specific section of a product. Use this endpoint for products that have sections enabled. + +**Endpoint:** `GET /products/{product_id}/sections/{section_id}/features` + +**Parameters:** + +- `product_id` (number, required) - ID of the Product +- `section_id` (number, required) - ID of the Section + +**Query Parameters:** + +| Parameter | Type | Required | Description | +| ------------ | ----- | -------- | ------------------------------------------------------------------------------------------------------------------ | +| `includes[]` | array | No | Optional associations to expand. Supported value: `user_stories`. See [List features](#list-features) for details. | + +**Example Request:** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X GET "https://api.test.io/customer/v2/products/1/sections/2/features" \ + -H "Authorization: Token YOUR_API_TOKEN" +``` + +{% /code %} + +**Response:** `200 OK` + +{% code language="json" showLineNumbers=true %} + +```json +{ + "features": [ + { + "id": 1, + "title": "Account Management", + "description": "Manage your account information", + "howtofind": "Top right of the screen", + "user_stories": ["User story 1"] + } + ] +} +``` + +{% /code %} + ## Create feature Create a new feature. @@ -106,3 +210,57 @@ curl -X POST "https://api.test.io/customer/v2/features" \ ``` {% /code %} + +## Copy features + +Copy all features (including their user stories) from one product to another. The features are duplicated into the destination product. + +**Endpoint:** `PUT /products/{product_id}/features/copy` + +**Parameters:** + +- `product_id` (number, required) - ID of the source Product to copy features from +- `destination_product_id` (number, required) - ID of the destination Product to copy features to + +**Query Parameters:** + +| Parameter | Type | Required | Description | +| ------------ | ----- | -------- | ------------------------------------------------------------------------------------------------------------------ | +| `includes[]` | array | No | Optional associations to expand. Supported value: `user_stories`. See [List features](#list-features) for details. | + +**Example Request:** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X PUT "https://api.test.io/customer/v2/products/1/features/copy" \ + -H "Authorization: Token YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "destination_product_id": 2 + }' +``` + +{% /code %} + +**Response:** `200 OK` + +Returns the list of features in the destination product after copying. + +{% code language="json" showLineNumbers=true %} + +```json +{ + "features": [ + { + "id": 30, + "title": "Account Management", + "description": "Manage your account information", + "howtofind": "Top right of the screen", + "user_stories": ["User story 1"] + } + ] +} +``` + +{% /code %} diff --git a/src/pages/docs/api/overview.md b/src/pages/docs/api/overview.md index 6fd1436..b433290 100644 --- a/src/pages/docs/api/overview.md +++ b/src/pages/docs/api/overview.md @@ -34,6 +34,7 @@ The API provides access to the following resources: - **[Binary Apps](/docs/api/binary-apps)** - Upload and manage binary application files - **[Connections](/docs/api/connections)** - Manage connections - **[User Stories](/docs/api/user-stories)** - Create and manage user stories +- **[User Story Version Executions](/docs/api/user-story-version-executions)** - List execution results for user stories - **[Features](/docs/api/features)** - List and create features - **[Bugs](/docs/api/bugs)** - Fetch, search, and manage bugs - **[Exploratory Tests](/docs/api/exploratory-tests)** - Create and manage exploratory tests diff --git a/src/pages/docs/api/user-story-version-executions.md b/src/pages/docs/api/user-story-version-executions.md new file mode 100644 index 0000000..2615a64 --- /dev/null +++ b/src/pages/docs/api/user-story-version-executions.md @@ -0,0 +1,177 @@ +--- +title: User Story Version Executions +description: List and understand user story execution results from test cycles +--- + +User story version executions represent individual test runs of a user story by testers in a test cycle. Each execution records the outcome (e.g. passed, failed, blocked), who executed it, when, and on which device or browser. + +> **Prerequisites**: You need a product with [User Stories](/docs/api/user-stories) and [Exploratory Tests](/docs/api/exploratory-tests). Executions are created when testers run user stories as part of a test cycle. + +## What are User Story Version Executions? + +When a tester executes a user story during an exploratory test, the system creates a **user story version execution**. Each execution includes: + +- **Status** – Whether the story passed, failed, was blocked, or is still pending +- **Comment** – The tester’s notes (required when status is passed, failed, or blocked) +- **Executed by** – The tester’s screen name +- **Device/browser** – Device reports describing the environment used +- **Test cycle** – The test cycle and test environment where the execution took place + +Use this API to list executions for your user stories, filter by user story or version, and inspect results for reporting or integrations (e.g. InteractSoftware). + +## List user story version executions + +Returns a paginated list of user story version executions for the current customer. Results can be filtered by user story IDs or user story version IDs and ordered by creation time. + +**Endpoint:** `GET /user_story_version_executions` + +**Query Parameters:** + +| Parameter | Type | Required | Description | +| -------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `page` | integer | No | Page number for pagination (default: 1) | +| `per_page` | integer | No | Number of records per page (default: 25) | +| `user_story_ids[]` | array | No | Filter by user story IDs. Only executions for these user stories are returned. Pass multiple values as `user_story_ids[]=1&user_story_ids[]=2` | +| `user_story_version_ids[]` | array | No | Filter by user story version IDs. Pass multiple values as `user_story_version_ids[]=10&user_story_version_ids[]=11` | +| `order` | string | No | Sort order by creation time: `asc` (oldest first) or `desc` (newest first). Default: `asc` | + +**Example Request (all executions, newest first):** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X GET "https://api.test.io/customer/v2/user_story_version_executions?order=desc&per_page=10" \ + -H "Authorization: Token YOUR_API_TOKEN" +``` + +{% /code %} + +**Example Request (filter by user stories):** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X GET "https://api.test.io/customer/v2/user_story_version_executions?user_story_ids[]=1&user_story_ids[]=2&order=desc&per_page=10" \ + -H "Authorization: Token YOUR_API_TOKEN" +``` + +{% /code %} + +**Example Request (filter by user story version IDs):** + +{% code language="bash" showLineNumbers=true %} + +```bash +curl -X GET "https://api.test.io/customer/v2/user_story_version_executions?user_story_version_ids[]=5&user_story_version_ids[]=6&page=1&per_page=25" \ + -H "Authorization: Token YOUR_API_TOKEN" +``` + +{% /code %} + +**Response:** `200 OK` + +**Response attributes (top level):** + +| Attribute | Type | Description | +| ------------------------------- | ------- | ----------------------------------------------------------------- | +| `meta.record_count` | integer | Total number of executions matching the query (before pagination) | +| `user_story_version_executions` | array | List of execution objects (see below) | + +**User story version execution object attributes:** + +| Attribute | Type | Description | +| ---------------- | -------------- | -------------------------------------------------------------------------------------- | +| `id` | integer | Unique execution ID | +| `status` | string | Execution status. One of: `pending`, `passed`, `failed`, `blocked`, `cancelled` | +| `comment` | string \| null | Tester’s comment for the execution (present when status is passed, failed, or blocked) | +| `executed_by` | string \| null | Screen name of the tester who executed the user story | +| `device_reports` | array | Device/browser information for the execution (see Device report object below) | +| `test_cycle` | object | Test cycle summary (see Test cycle object below) | +| `executed_at` | string | ISO 8601 timestamp when the execution was created | + +**Status values:** + +- `pending` – Execution not yet completed +- `passed` – Tester confirmed the user story works as expected +- `failed` – Tester found that the user story does not work as expected +- `blocked` – Tester could not complete the user story (e.g. environment issue) +- `cancelled` – Execution was cancelled + +**Device report object (each item in `device_reports`):** + +| Attribute | Type | Description | +| -------------------------- | ------- | ----------------------------------------------------------- | +| `id` | integer | Device report ID | +| `category` | object | Device category: `id`, `key`, `name` (e.g. desktop, mobile) | +| `vendor` | object | Vendor: `id`, `name` | +| `operating_system` | object | OS: `id`, `key`, `name` | +| `operating_system_version` | object | OS version: `id`, `name` | +| `device` | object | Device: `id`, `name` | +| `browsers` | array | List of browser objects, each with `id` and `name` | + +**Test cycle object:** + +| Attribute | Type | Description | +| ------------------ | ------- | ------------------------------- | +| `id` | integer | Test cycle ID | +| `title` | string | Test cycle title | +| `test_environment` | object | Test environment: `id`, `title` | + +**Example Response:** + +{% code language="json" showLineNumbers=true %} + +```json +{ + "meta": { + "record_count": 42 + }, + "user_story_version_executions": [ + { + "id": 101, + "status": "passed", + "comment": "Verified all steps on checkout flow.", + "executed_by": "tester.screenname", + "device_reports": [ + { + "id": 1, + "category": { "id": 1, "key": "desktop", "name": "Desktop" }, + "vendor": { "id": 1, "name": "Apple" }, + "operating_system": { "id": 1, "key": "macos", "name": "macOS" }, + "operating_system_version": { "id": 1, "name": "14.0" }, + "device": { "id": 1, "name": "MacBook Pro" }, + "browsers": [{ "id": 1, "name": "Chrome" }] + } + ], + "test_cycle": { + "id": 5, + "title": "Regression Test – February 2025", + "test_environment": { "id": 1, "title": "Staging" } + }, + "executed_at": "2025-02-05T10:30:00.000Z" + }, + { + "id": 102, + "status": "failed", + "comment": "Add to cart button does not respond on mobile.", + "executed_by": "another.tester", + "device_reports": [], + "test_cycle": { + "id": 5, + "title": "Regression Test – February 2025", + "test_environment": { "id": 2, "title": "Production" } + }, + "executed_at": "2025-02-05T11:15:00.000Z" + } + ] +} +``` + +{% /code %} + +## Usage tips + +- Use `user_story_ids[]` when you want all executions for specific user stories (e.g. for a feature or product view). +- Use `user_story_version_ids[]` when you need executions for specific user story versions (e.g. tied to a test cycle or version snapshot). +- Use `order=desc` and `per_page` to fetch the most recent executions first and control page size. +- `meta.record_count` reflects the total matching the filters; use it with `per_page` to compute total pages or show “X of Y” in the UI.