README

Laravel Testerra

A Laravel package for managing beta testing programs with test assignments, bug reporting, and tester invitations.

Features

Test Management: Create and organize tests into groups
Tester Invitations: Invite testers via email with token-based secure links (powered by laravel-invite-only)
Test Assignments: Assign tests to users individually or by group
Bug Reporting: Track bugs with severity levels and screenshot attachments
Issue Tracker Integration: Automatically create Jira or GitHub issues when bugs are reported
Waitlist Integration: Optional integration with laravel-waitlist
Event-Driven: Events fired for key actions (invitations, assignments, completions, bug reports)

Requirements

PHP 8.4+
Laravel 11.0 or 12.0

Installation

composer require offload-project/laravel-testerra

Publish the configuration and migrations:

php artisan vendor:publish --tag="testerra-config"
php artisan vendor:publish --tag="testerra-migrations"
php artisan migrate

Since this package uses laravel-invite-only for invitations, you should also publish its config:

php artisan vendor:publish --tag="invite-only-config"
php artisan vendor:publish --tag="invite-only-migrations"
php artisan migrate

Configuration

After publishing, configure the package in config/testerra.php:

return [
    'table_prefix' => 'testerra_',
    'user_model' => App\Models\User::class,
    'screenshots' => [
        'disk' => env('TESTERRA_SCREENSHOT_DISK', 'local'),
        'path' => 'testerra/screenshots',
    ],
    'waitlist' => [
        'enabled' => false,
        'name' => 'testers',
    ],
];

Usage

Using the Facade

use OffloadProject\Testerra\Facades\Testerra;

Managing Test Groups

// Create a group
$group = Testerra::createGroup('Mobile App Tests', 'Tests for the mobile application');

// Get all groups
$groups = Testerra::getGroups();

// Update a group
Testerra::updateGroup($group, 'Updated Name', 'Updated description');

// Delete a group
Testerra::deleteGroup($group);

Managing Tests

// Create a test
$test = Testerra::createTest(
    'Login Flow',
    'Test the login process with valid and invalid credentials',
    [$group->id] // Optional: assign to groups
);

// Get all tests
$tests = Testerra::getTests();

// Add test to groups
Testerra::addTestToGroups($test, [$group1->id, $group2->id]);

// Get tests by group
$testsInGroup = Testerra::getTestsByGroup($group);

Inviting Testers

Invitations are handled via the laravel-invite-only package:

// Invite a tester to a test group
$invitation = Testerra::inviteTester('tester@example.com', $group, [
    'role' => 'beta-tester',
    'metadata' => ['source' => 'website'],
]);

// Accept an invitation
$invitation = Testerra::acceptInvitation($token, $user);

// Decline an invitation
$invitation = Testerra::declineInvitation($token);

// Cancel an invitation
$invitation = Testerra::cancelInvitation($invitation);

// Get pending invitations for a group
$pending = Testerra::getPendingInvitations($group);

// Check if email has pending invitation
$hasPending = Testerra::hasPendingInvitation('tester@example.com', $group);

// Resend an invitation
Testerra::resendInvitation($invitation);

Assigning Tests

// Assign a single test to a user
$assignment = Testerra::assignTest($user, $test);

// Assign all tests in a group to a user
$assignments = Testerra::assignTestsByGroup($user, $group);

// Get assignments for a user
$assignments = Testerra::getAssignmentsForUser($user);

// Get pending assignments
$pending = Testerra::getPendingAssignments($user);

// Update assignment status
Testerra::markInProgress($assignment);
Testerra::markComplete($assignment);

Reporting Bugs

// Report a bug
$bug = Testerra::reportBug(
    $assignment,
    'Login button not working',
    'When clicking the login button, nothing happens',
    'high' // Severity: low, medium, high, critical
);

// Add screenshots
$screenshot = Testerra::addScreenshot($bug, $uploadedFile);

// Get bugs
$bugsForTest = Testerra::getBugsForTest($test);
$bugsForAssignment = Testerra::getBugsForAssignment($assignment);
$allBugs = Testerra::getAllBugs();

User Trait

Add the HasTestAssignments trait to your User model:

use OffloadProject\Testerra\Traits\HasTestAssignments;

class User extends Authenticatable
{
    use HasTestAssignments;
}

This provides convenient methods:

$user->testAssignments;
$user->pendingAssignments();
$user->completedAssignments();
$user->bugs;
$user->getAssignmentStats();

Events

The package dispatches the following events:

TesterInvited - When a tester is invited
TestAssigned - When a test is assigned to a user
TestCompleted - When a test assignment is marked complete
BugReported - When a bug is reported

Issue Tracker Integration

Automatically create issues in external trackers (Jira or GitHub) when bugs are reported.

Jira Configuration

TESTERRA_ISSUE_TRACKER_ENABLED=true
TESTERRA_ISSUE_TRACKER_DRIVER=jira
TESTERRA_JIRA_HOST=https://your-domain.atlassian.net
TESTERRA_JIRA_EMAIL=your-email@example.com
TESTERRA_JIRA_API_TOKEN=your-api-token
TESTERRA_JIRA_PROJECT_KEY=PROJ
TESTERRA_JIRA_ISSUE_TYPE=Bug

Bug severity is mapped to Jira priority. Customize in config/testerra.php:

'priority_mapping' => [
    'critical' => 'Highest',
    'high' => 'High',
    'medium' => 'Medium',
    'low' => 'Low',
],

GitHub Configuration

TESTERRA_ISSUE_TRACKER_ENABLED=true
TESTERRA_ISSUE_TRACKER_DRIVER=github
TESTERRA_GITHUB_TOKEN=ghp_your_token
TESTERRA_GITHUB_OWNER=your-username
TESTERRA_GITHUB_REPO=your-repo

Bug severity is mapped to GitHub labels. Customize in config/testerra.php:

'github' => [
    'labels' => ['bug'],  // Default labels for all issues
    'severity_labels' => [
        'critical' => 'priority: critical',
        'high' => 'priority: high',
        'medium' => 'priority: medium',
        'low' => 'priority: low',
    ],
],

Async Issue Creation

For production, create issues asynchronously via queue:

TESTERRA_ISSUE_TRACKER_QUEUE=true
TESTERRA_ISSUE_TRACKER_QUEUE_NAME=testerra

Checking External Issue Status

$bug = Testerra::reportBug($assignment, 'Button broken');

// Check if synced to external tracker
if ($bug->hasExternalIssue()) {
    $url = $bug->getExternalUrl(); // https://github.com/owner/repo/issues/42
    $key = $bug->external_key;      // 42 (issue number)
}

Adding Custom Providers

Implement the IssueTrackerInterface:

use OffloadProject\Testerra\Contracts\IssueTrackerInterface;

class LinearIssueTracker implements IssueTrackerInterface
{
    public function createIssue(Bug $bug): ExternalIssue { /* ... */ }
    public function getIssue(string $externalId): ?ExternalIssue { /* ... */ }
    public function isConfigured(): bool { /* ... */ }
}

Waitlist Integration

To use the waitlist integration, install the laravel-waitlist package and enable it in your config:

'waitlist' => [
    'enabled' => true,
    'name' => 'testers',
],

Then you can:

// Add someone to the waitlist
Testerra::addToWaitlist('user@example.com', 'John Doe', ['source' => 'landing-page']);

// Invite from waitlist
Testerra::inviteFromWaitlist($waitlistEntry, $group);

Testing

composer test

Code Style

composer pint

Static Analysis

composer analyse

License

The MIT License (MIT). Please see License File for more information.

offload-project / laravel-testerra

Maintainers

Details