User Stories

Manage user stories for your products and features.

Prerequisites: You need a product and a feature. See Products and Features. User stories can also be included directly when creating features.

What are User Stories?

User Stories describe expected behavior from a user’s perspective. In testing, your task is to confirm whether each User Story works as expected.

Examples of User Stories:

A user can add a product to the cart
A user can remove items from the cart
When a valid promo code is applied, the correct discount is applied
A user can log in with valid credentials

Executing a User Story typically takes under 5 minutes. You can find them on the test overview page above the Feature description. Not every test will include User Stories.

Important: A User Story is not executed standalone. It is always executed in the scope of a test, specifically an exploratory test. You can include User Stories via Features and then run them by creating an Exploratory Test.

Get user story

Retrieve a specific user story by ID.

Endpoint: GET /user_stories/{user_story_id}

Parameters:

user_story_id (number, required) - ID of the User story

Example Request:

1curl -X GET "https://api.test.io/customer/v2/user_stories/1" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 200 OK

1{
2  "id": 1,
3  "path": "As a shopper, I can add a product to my cart",
4  "title": "Add product to cart"
5}

List user stories

Returns user stories of all features under the specified product.

Endpoint: GET /products/{product_id}/user_stories{?section_id}

Parameters:

product_id (number, required) - ID of the Product
section_id (number, optional) - ID of the Section. Must be provided for product with sections

Notes:

For products without sections, the response includes user stories from all features of the product
For products with sections, the section_id query parameter must be provided. In this case, the response includes user stories from all features that associated with the specified section of the product

Example Request:

1curl -X GET "https://api.test.io/customer/v2/products/1/user_stories?section_id=2" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 200 OK

1{
2  "user_stories": [
3    {
4      "id": 1,
5      "path": "As a shopper, I can add a product to my cart",
6      "title": "Add product to cart"
7    },
8    {
9      "id": 2,
10      "path": "As a shopper, I can remove a product from my cart",
11      "title": "Remove product from cart"
12    }
13  ]
14}

Create user story

Creates a new user story under the feature of the specified product.

Endpoint: POST /products/{product_id}/user_stories{?section_id}

Parameters:

product_id (number, required) - ID of the Product
section_id (number, optional) - ID of the Section. Must be provided for product with sections

Notes:

For products without sections, the user story can be created under any feature of the product
For products with sections, the section_id query parameter must be provided. In this case, the user story can only be created under a feature associated with the specified section of the product

All attributes must be provided inside the root object user_story.

Request Body:

feature_id (number, required) - ID of the feature under which the user story will be created
path (string, required) - Description of the user story in the form "As a <user>, I can <action>"

Example Request:

1curl -X POST "https://api.test.io/customer/v2/products/1/user_stories?section_id=2" \
2  -H "Authorization: Token YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "user_story": {
6      "feature_id": 1,
7      "path": "As a shopper, I can add a product to my cart"
8    }
9  }'

Response: 201 Created

1{
2  "id": 1,
3  "path": "As a shopper, I can add a product to my cart",
4  "title": "Add product to cart"
5}

Update user story

Updates the specified user story within the product.

Endpoint: PUT /products/{product_id}/user_stories/{user_story_id}{?section_id}

Parameters:

product_id (number, required) - ID of the Product
user_story_id (number, required) - ID of the User story
section_id (number, optional) - ID of the Section. Must be provided for product with sections

Notes:

For products without sections, the user story must be associated with a feature of the specified product
For products with sections, the section_id query parameter must be provided. In this case, the user story must be associated with a feature that is part of a section of the specified product

All attributes must be provided inside the root object user_story.

Request Body:

path (string, required) - Description of the user story

Example Request:

1curl -X PUT "https://api.test.io/customer/v2/products/1/user_stories/2?section_id=2" \
2  -H "Authorization: Token YOUR_API_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "user_story": {
6      "path": "As a shopper, I can remove a product from my cart"
7    }
8  }'

Response: 200 OK

1{
2  "id": 2,
3  "path": "As a shopper, I can remove a product from my cart",
4  "title": "Remove product from cart"
5}

Delete user story

Deletes the specified user story from the product.

Endpoint: DELETE /products/{product_id}/user_stories/{user_story_id}{?section_id}

Parameters:

product_id (number, required) - ID of the Product
user_story_id (number, required) - ID of the User story
section_id (number, optional) - ID of the Section. Must be provided for product with sections

Notes:

For products without sections, the user story must be associated with a feature of the specified product
For products with sections, the section_id query parameter must be provided. In this case, the user story must be associated with a feature that is part of a section of the specified product

Example Request:

1curl -X DELETE "https://api.test.io/customer/v2/products/1/user_stories/2?section_id=2" \
2  -H "Authorization: Token YOUR_API_TOKEN"

Response: 200 OK

1{
2  "id": 2,
3  "path": "As a shopper, I can add a product to my cart",
4  "title": "Add product to cart"
5}