Lathe Studio - User Guide

Welcome to Lathe Studio, a modern test management platform for Jira-centric engineering teams.

---

Table of Contents#

1. Getting Started
2. Projects
3. Releases & Builds
4. Test Cases
5. Test Runs
6. Test Execution
7. Coverage Tags
8. Jira Integration
9. Reporting
10. User Management
11. Roles & Permissions
12. User Groups

---

Getting Started#

Creating Your First Project

1. Click "New Project" on the projects page
2. Enter a project name and optional description
3. Click Create

You'll be taken to the project dashboard where you can start creating test cases, releases, and test runs.

Navigation Overview

• Sidebar: Access Dashboard, Releases, Builds, Test Runs, Test Library, and Reporting
• Projects: Navigate to /projects to switch between or create projects
• Settings: Access project settings, user settings, and organization settings

---

Projects#

Project Dashboard

The project dashboard gives you a high-level view of your testing activity:

• Weekly Calendar: Visual view of test runs and releases
• Test Runs Summary: Recent runs with pass/fail counts
• Quick Actions: Create a new release for the selected project

Project Settings

Access project settings via Project Settings in the sidebar:

General Tab

• Project Name: Update the project name
• Description: Add or edit project description
• Project Code: 2–8 uppercase letters (e.g., MOB) used as a prefix for test case and run identifiers (e.g., TC-MOB-0001, RUN-MOB-0042)
• Jira Project Key: Link to your Jira project

Users Tab

Manage project members and their access:

• Add Members: Invite organization members to the project
• Roles: Assign a system role (Viewer, Tester, Admin, Owner) or a custom organization role
• Remove Members: Remove users from the project

Every organization starts with four system roles. These cover the most common access patterns and are available on all plans:

Enterprise plans can create custom roles with any combination of non-restricted permissions. See Roles & Permissions for details.

Coverage Tags Tab

Create and manage coverage tags for categorizing test cases and builds.

Jira Tab

Configure Jira field mappings for this project (see Jira Integration).

Bitbucket Tab

Configure Bitbucket Pipelines integration:

• Webhook URL for receiving CI build events
• Repository URL for auto-matching incoming builds
• API key selection

Sprint Tab

Configure sprint settings for the project.

---

Releases & Builds#

Releases

Releases represent major versions or milestones in your project.

Creating a Release

1. Navigate to Releases (global or project-specific)
2. Click "New Release"
3. Enter:
   • Name: Release name (e.g., "v2.0")
   • Description: Optional release notes
   • Target Date: When the release is planned
4. Click Create

Release Statuses:

• Planned: Upcoming release
• Active: Currently in development
• Released: Shipped to production

Builds

Builds represent specific iterations or versions within a release.

Creating a Build

1. Navigate to a release and click "New Build", or go to Builds and click "New Build"
2. Enter:
   • Name: Build name (e.g., "Build 2.0.1") — required
   • Release: Select parent release — required
   • Description: Optional build notes
   • Start/End Dates: Build timeline (optional)
   • Coverage Tags: Optional tags for categorization
3. Click Create

Note: Builds created via CI/CD integrations (Bitbucket, GitHub, GitLab) automatically include branch, commit SHA, and source metadata.

Build Detail Page

The build detail page shows:

• Readiness Widget: Verified, Pending, Blocked, and New test counts
• Coverage Tab: Test case execution status with filtering
• Test Runs: All runs associated with this build
• Coverage Tags: Tags assigned to this build

Build Queue (CI/CD Integration)

The Build Queue shows builds awaiting assignment:

• Builds created via API/webhook appear here
• Click Assign to Release to associate with a release
• View build details and metadata

---

Test Cases#

Test Library

The Test Library is your central repository for all test cases.

Sections

Organize test cases into sections:

1. Create Section: Click "New Section" in the Test Library
2. Nested Sections: Create hierarchical organization
3. Section Tags: Assign coverage tags that inherit to all test cases in the section

Creating Test Cases

1. Navigate to a section or click "New Test Case"

2. Fill in the details:

   • Title: Clear, descriptive test case name
   • Priority: P0 (Critical) to P3 (Low)
   • Test Type: Functional, Regression, Smoke, E2E, API, etc.
   • Execution Mode: Manual, Automated, or Hybrid
   • Description: Context and background
   • Preconditions: Setup required before testing

3. Test Steps: Add steps with actions and expected results

   • Use the rich text toolbar for formatting
   • Bold, italic, code, and links supported
   • Drag to reorder steps

4. Coverage Tags: Assign tags for categorization

5. Click Save

Test Case Display Codes

Each test case gets a human-readable code like TC-MOB-0042 based on the project code. These codes appear in test case lists, run detail views, and Jira issue titles when bugs are pushed.

Test Case Status

• Draft: Work in progress
• Review: Ready for review
• Approved: Ready for execution
• Obsolete: Deprecated test case

Editing Test Cases

• Edit any field including steps, priority, and tags
• modified_by and modified_at are tracked on save

---

Test Runs#

Creating Test Runs

Test runs group test cases for execution.

Basic Creation

1. Click "New Test Run"

2. Configure:

   • Name: Run identifier (e.g., "Sprint 23 Smoke Test")
   • Environment: Dev, Staging, Production, or Custom
   • Release: Optional parent release
   • Build: Optional specific build

3. Select Test Cases:

   • Browse by section
   • Filter by coverage tags
   • Select individual cases or entire sections

4. Click Create

Advanced Options

• Duplicate Run: Copy an existing run with all its test cases pre-selected
• Pre-selection: When creating from a release or build detail page, that release/build is automatically pre-selected in the form

Test Run Display Codes

Each run gets a code like RUN-MOB-0089 based on the project code, shown in run lists and the run detail header.

Test Run Lifecycle

Statuses:

1. Planned: Created but not started
2. In Progress: Currently being executed
3. Submitted: Tester finished, awaiting build completion
4. Completed: Finalized

Submitting Runs

When submitting a run with unexecuted tests:

• Create New Run (Untested Only): Move remaining tests to a new run
• Create New Run (All): Duplicate entire run
• Just Submit: Submit as-is

---

Test Execution#

Execution Interface

Open a test run to begin execution:

Desktop View

• Expand/collapse test case rows
• Record result: Pass, Fail, Blocked, Skipped, Retest
• Add notes with rich text formatting
• Attach screenshots or files

Mobile View

Card-based interface optimized for touch:

• Swipe between test cases
• Large touch targets for result buttons
• Progress bar showing overall status
• Spring animations with haptic feedback

Recording Results

1. Select Result: Click the appropriate result button
2. Add Notes: Document findings, especially for failures
3. Attachments: Upload screenshots, logs, or videos
   • Camera capture (mobile)
   • Clipboard paste (Ctrl+V)
   • File upload
4. Auto-advance: Automatically moves to next untested case

Result Meanings

• Pass: Test completed successfully
• Fail: Test did not meet expected results
• Blocked: Cannot test due to dependencies/issues
• Skipped: Intentionally not tested
• Retest: Requires re-verification

Notes & Attachments

• Notes are locked to results (clear result to edit notes)
• Attachments support images, PDFs, text files
• Maximum 5 files, 10MB each
• Files upload directly to Jira when pushing bugs (zero local storage)

---

Coverage Tags#

Coverage tags categorize test cases and builds by feature area, test type, risk level, or custom categories.

Managing Tags

In Project Settings → Coverage Tags:

Create Tags

1. Click "Add Tag"
2. Enter:
   • Name: Tag identifier
   • Category: Feature Area, Test Type, Risk Level, or Custom
   • Color: Visual identifier (18 color options)
3. Click Add

Using Tags

On Test Cases:

• Assign tags in the test case form
• Filter test runs by tag when creating/editing runs (AND logic)

On Builds:

• Assign tags when creating builds
• View tags on build detail page

On Sections:

• Assign tags to sections
• All test cases in the section inherit those tags

---

Jira Integration#

Connecting Jira

1. Go to Project Settings → Jira
2. Click "Connect Jira"
3. Authorize with your Atlassian account
4. Configure:
   • Jira Project Key: Where bugs will be created
   • Default Issue Type: Bug, Task, etc.
   • Field Mappings: Choose which PT fields to include

Pushing Bugs

When test cases fail:

Single Push

1. In a test run, find the failed test case
2. Click "Push to Jira"
3. Review/modify bug details:
   • Title (auto-populated from test case)
   • Description (includes steps, notes, environment)
   • Attachments (screenshots, logs)
4. Click Push

Batch Push

1. In a submitted/completed run, click "Submit Bugs" in the header
2. Select all failures or specific ones
3. Review batch in the modal
4. Click Push All

Bug Content

Automatically included:

• Test case title and display code (e.g., TC-MOB-0042)
• Priority
• Test steps (formatted)
• Tester notes
• Run/build/environment info
• Attachments

Field Mappings

In Project Settings → Jira → Field Mappings:

Toggle which fields to include in Jira issues:

• Test Case Title
• Priority
• Test Steps
• Tester Notes
• Run Name
• Build Name
• Environment

Sync Status

Track push status:

• Pending: Queued for push
• Success: Created in Jira
• Failed: Error occurred (retry available)
• Retrying: Automatic retry in progress

---

Reporting#

Dashboard

The main dashboard provides:

• Recent Activity: Latest test runs and results
• Sparklines: Trend visualization for active runs (refreshed every 30 seconds)
• Weekly Calendar: Visual schedule of runs and releases
• Coverage Overview: Pass/fail statistics

Build Coverage

On any build detail page:

• Filter by effective status
• View inheritance details
• Recompute coverage (admin)

Global Views

• All Releases: Cross-project release tracking
• All Test Runs: Global test execution view
• All Test Cases: Central test library

---

User Management#

Organization Settings

Access via Settings → Organization:

Details Tab

• View/edit organization name
• See org ID and slug

Users Tab

• Invite new members to the organization
• Manage organization-level roles (org:owner, org:admin, org:member)
• View pending invitations
• Remove members

Organization admins and owners can also assign default project roles during invitation, so new members are automatically added to the right projects when they accept.

Roles Tab (Enterprise)

Create and manage custom roles for your organization:

• System roles (Viewer, Tester, Admin, Owner) are seeded automatically and cannot be deleted
• Custom roles can mix any non-restricted permissions to fit your team's workflow
• Restricted permissions — project:delete, member:transfer_ownership, and organization:billing — are reserved for the organization owner only

Groups Tab

Create user groups to manage access at scale:

• Create groups like "QA Team" or "Contractors"
• Add members to a group once, then assign the group to any number of projects
• Group members inherit the group's role on each project

API Keys Tab

• Create and manage API keys (Pro/Enterprise)
• Set scopes and rate limits
• Revoke keys

Slack Tab

• Connect a Slack incoming webhook
• Configure notification triggers (run submitted, run completed, build readiness)

Billing Tab

• View current plan and tier (Basic/Pro/Enterprise)
• Update payment method
• Manage subscription

Project Members

In Project Settings → Users:

• Add organization members to the project
• Assign a role (system or custom)
• Remove members from the project

If a user is a member of a group that has been assigned to this project, they will appear here with their group-derived role.

---

Roles & Permissions#

Lathe Studio uses a granular permission system. Instead of hardcoded roles, every action in the app is gated by a specific permission. System roles are simply pre-built bundles of these permissions.

Permission Levels

Permissions are organized into three levels:

• Page permissions — Control which sections of the app a user can navigate to (e.g., page:test_cases)
• Operation permissions — Control what actions a user can perform (e.g., test_case:create, build:delete)
• Data permissions — Ownership-aware permissions that let users edit or delete resources they created, even if they don't have the unrestricted operation permission (e.g., test_case:update_own)

System Roles

Custom Roles (Enterprise)

On Enterprise plans, organization admins can create custom roles:

1. Go to Settings → Organization → Roles
2. Click "New Role"
3. Name the role and select permissions
4. Save and assign it to project members

Common custom role examples:

• Read-Only Tester: Can view everything and submit test runs, but cannot create or edit test cases
• Integration Manager: Can configure Jira and Slack, but cannot manage members or delete projects
• Content Editor: Can create and edit test cases and sections, but cannot execute tests or manage builds

Restricted Permissions

The following permissions are restricted to the organization owner only and cannot be granted through custom roles:

• Delete projects (project:delete)
• Transfer project ownership (member:transfer_ownership)
• Manage billing (organization:billing)

---

User Groups#

User groups let you assign the same role to many users across multiple projects without managing each member individually.

Creating a Group

1. Go to Settings → Organization → Groups
2. Click "New Group"
3. Enter a name and description
4. Add members from your organization

Assigning a Group to Projects

1. Open a group's detail page
2. Click "Add Project Access"
3. Select the project and choose a role for the group
4. Every group member immediately gets that role on the project

How Group Access Works

• A user can have both direct membership and group-derived access on the same project
• If both exist, the user receives the union of permissions from both roles
• Removing a user from a group removes their group-derived access from all projects
• Removing a group's project access removes that access for all group members

Example: The "Contractors" group is assigned the Viewer role on Project A and the Tester role on Project B. Every contractor can view Project A and create/submit tests on Project B. When a new contractor joins the group, they automatically get access to both projects.

---

Tips & Best Practices#

Test Case Organization

• Use sections to group related tests
• Keep test cases focused (one concept per case)
• Use clear, descriptive titles
• Tag consistently for better filtering

Test Run Planning

• Create runs for specific purposes (smoke, regression, feature)
• Use environments consistently
• Link to builds for traceability

Execution Efficiency

• Use auto-advance to move quickly through tests
• Add detailed notes for failures
• Attach screenshots immediately
• Submit runs promptly when complete

Jira Integration

• Connect Jira early in project setup
• Configure field mappings to match your workflow
• Use batch push for multiple failures
• Review pushed issues in Jira for additional context

---

Keyboard Shortcuts#

---

Getting Help#

• In-app: Tooltips and hints throughout the interface
• Documentation: This guide and inline help
• Support: Contact your organization admin or support team

---

Last Updated: May 2026