Quick Start Guide

This guide provides a minimal working example of creating and running your first test using Hypervel Testbench. It demonstrates the essential patterns for extending TestCase, configuring your test environment, and executing basic tests.

For detailed information about installation and environment setup, see Installation and Setup. For comprehensive architecture details, see Architecture Overview.

---

Creating Your First Test Class

The simplest test class extends Hypervel\Testbench\TestCase and requires no additional configuration. Create a test file in your tests/ directory:

Example: tests/BasicTest.php

This minimal test demonstrates that the testbench environment initializes correctly. The TestCase base class handles all bootstrapping, application creation, and lifecycle management automatically.

Test Class Structure and Extension Points

Sources: src/TestCase.php28-110 src/Concerns/CreatesApplication.php1-59

---

Running Your Tests

Execute tests using PHPUnit from your package root directory:

Or run all tests:

The first test execution triggers one-time bootstrapping via Bootstrapper::bootstrap() src/TestCase.php40-43 This loads configuration from testbench.yaml, generates the .env file, and sets up the base path. Subsequent tests reuse this bootstrapped environment.

Test Execution Flow

Sources: src/TestCase.php38-58 src/TestCase.php69-78 src/TestCase.php63-67

---

Basic Testing Patterns

Registering Service Providers

Override getPackageProviders() to register your package's service providers:

The getPackageProviders() method returns an array of provider class names src/Concerns/CreatesApplication.php19-22 These providers are automatically registered during defineEnvironment() src/TestCase.php65 via registerPackageProviders() src/Concerns/CreatesApplication.php37-42

Registering Class Aliases

Override getPackageAliases() to register facades or class aliases:

Aliases are merged with existing app.aliases configuration src/Concerns/CreatesApplication.php47-58

Defining Routes for Testing

Override defineRoutes() for general routes or defineWebRoutes() for routes that should use web middleware:

Routes defined in defineWebRoutes() are automatically wrapped in the web middleware group. For routes without middleware, use defineRoutes() instead.

Sources: src/TestCase.php30 src/TestCase.php32

Working with Database Migrations

Override defineDatabaseMigrations() to specify migration paths:

Migrations run automatically before each test and are rolled back during teardown src/TestCase.php31

Sources: src/TestCase.php31 src/Concerns/HandlesDatabases.php

---

Common Testing Patterns Summary

The following table summarizes the override methods available in TestCase and their purposes:

Override Method	Purpose	Returns	Called During
getPackageProviders($app)	Register service providers	array<class-string>	defineEnvironment()
getPackageAliases($app)	Register class aliases	array<string, class-string>	defineEnvironment()
defineRoutes($router)	Define routes without middleware	void	After application boot
defineWebRoutes($router)	Define routes with web middleware	void	After application boot
defineDatabaseMigrations()	Load migration paths	void	Before each test
defineEnvironment($app)	Custom environment configuration	void	During application creation

Sources: src/TestCase.php63-67 src/Concerns/CreatesApplication.php19-32

---

TestCase Lifecycle Overview

Understanding the test lifecycle helps you determine where to place initialization and cleanup logic:

Per-Test Lifecycle

Sources: src/TestCase.php38-58 src/TestCase.php80-88

Key Lifecycle Points:

1. First Test Only: Bootstrapper::bootstrap() executes once via static flag $hasBootstrappedTestbench src/TestCase.php36 src/TestCase.php40-43

2. Every Test:

   • New application instance created via createApplication() src/TestCase.php69-78
   • Environment configured via defineEnvironment() src/TestCase.php63-67
   • Routes registered via setUpApplicationRoutes() src/TestCase.php50
   • All setup/teardown occurs within coroutine context src/TestCase.php57 src/TestCase.php83

3. Test Isolation: Each test receives a fresh application instance, ensuring no state leakage between tests

This lifecycle ensures efficient bootstrapping (once per run) while maintaining test isolation (fresh app per test).

---

Next Steps

Now that you have created and run your first test, explore:

• Architecture Overview: Understand how TestCase, ConfigProviderRegister, and traits interact
• TestCase: Core Testing Foundation: Deep dive into test lifecycle management and application setup
• Testing Traits and Concerns: Learn about HandlesRoutes, CreatesApplication, and HandlesDatabases traits
• Database Testing: Comprehensive patterns for testing with migrations and factories
• Configuration Management: Customize testbench.yaml and application configuration

Sources: src/TestCase.php1-110 src/Concerns/CreatesApplication.php1-59 testbench.yaml1-20