Repository files navigation

A testing framework, with a focus on integration testing, that treats Amp's Loop as a first-class citizen!

• ExtendCspray\Labrador\AsyncUnit\TestCase and annotate your tests with#[Test] to get started
• Setup and teardown your tests using a variety of hooks by annotating methods with attributes like#[BeforeEach] and#[AfterEach]
• Embrace a test suite as a first-class citizen withCspray\Labrador\AsyncUnit\TestSuite and bring a layer of extra functionality to integration tests
• Assertion API with first-class async support and a clear
• Disable tests,TestCase, or aTestSuite with the#[Disabled] Attribute
• Utilize#[DataProvider] to reduce test duplication
• Expect exceptions with, or without, specific messages to be thrown by your tests
• Includes a bundled CLI application for running your tests

AsyncUnit is under active development! The project has adefined Roadmap and is currently implementing features forversion0.5.0.

composer require --dev cspray/labrador-async-unit

Although AsyncUnit can satisfy the needs of most unit and integration tests it was really designed for a specific type oftest which can be challenging to run properly even in synchronous contexts. The "canonical" AsyncUnit test exampleis below and demonstrates the core functionality of the framework.

<?phpnamespaceAcme\MyApp;useCspray\Labrador\AsyncUnit\Attribute\AfterAll;useCspray\Labrador\AsyncUnit\Attribute\BeforeAll;useCspray\Labrador\AsyncUnit\Attribute\BeforeEachTest;useCspray\Labrador\AsyncUnit\Attribute\AfterEachTest;useCspray\Labrador\AsyncUnit\Attribute\BeforeEach;useCspray\Labrador\AsyncUnit\Attribute\Test;useCspray\Labrador\AsyncUnit\Attribute\AttachToTestSuiteasUseTestSuite;useCspray\Labrador\AsyncUnit\TestCase;useCspray\Labrador\AsyncUnit\TestSuite;useAmp\Success;useAmp\Delayed;usefunctionAmp\Postgres\pool;class DatabaseTestSuiteextends TestSuite {    #[BeforeAll]publicfunctionconnectToDatabase() {// In test situations we want to make sure we're dealing with the same connection so we can properly clean up data$pool =pool(connectionConfig(), maxConnections:1, resetConnections:false);$this->set('pool',$pool);    }        #[BeforeEachTest]publicfunctionstartTransaction() {yield$this->get('pool')->query('START TRANSACTION');    }        #[AfterEachTest]publicfunctionrollback() {yield$this->get('pool')->query('ROLLBACK');    }        #[AfterAll]publicfunctioncloseDatabase() {$this->get('pool')->close();    }    }// The name of this class doesn't matter... you only need to ensure you extend TestCase#[UseTestSuite(DatabaseTestSuite::class)]class MyDatabaseTestCaseextends TestCase {// Again, none of the method names matter... just make sure you're annotating with the correct Attribute    #[BeforeEach]publicfunctionloadFixture() {yieldsomeMethodThatLoadsData($this->testSuite()->get('pool'));    }        #[Test]publicfunctionensureSomethingHappens() {yieldnewDelayed(100);// just to show you we're on the loop// These values could be retrieved from the database$this->assert()->stringEquals('foo','foo');    }        #[Test]publicfunctionensureSomethingAsyncHappens() {yieldnewDelayed(100);yield$this->asyncAssert()->stringEquals('foo',newSuccess('foo'));    }        #[Test]publicfunctionmakeSureYouAssertSomething() {// a failed test because you didn't assert anything!    }    }class MyNormalTestCaseextends TestCase {        #[Test]publicfunctionensurePoolNotAvailable() {$this->assert()->isNull($this->testSuite()->get('pool'));    }    }

I hope you were able to see as much neatness in the above testing example as I do! If you're interested in seeing moreexamples there are two places to find them; theexamples/ andacme_src/ directories. Otherwise, please check out therest of this README for how to get started with the project.

Whether you're a user learning how to write tests with the framework or you're a contributor wanting to make the librarybetter our documentation should have what you're looking for! We walk you through everything you need to do get started,teach you about all the important concepts to know, and list out the assertions available. For contributors we give youa thorough overview of how everything works.

Online documentation at https://docs.labrador-kennel.io/asyncunit.

Documentation for Labrador AsyncUnit is sponsored byGitBook. Should absolutelycheck them out if you have the ned for developer-friendly, managed documentation hosting!

Have an idea for the framework? Wondering how something works and have a question? Wanna interact with the maintainers?You're in the right place! This is the "social" part of AsyncUnit...go add to the Discussion!

AsyncUnit has a fairly well-defined roadmap leading to a stable API and a 1.0 release. Our Roadmap is not dated becausethe framework is currently maintained and implemented by 1 person in their free time. Instead, we have a series of 0.xreleases with functionality that should enable increasingly complex tests until our canonical example can be executed.Check outthe Roadmap to see what's in store for AsyncUnit! Thefeatures we're currently working on implemented can be tracked in ourActive Sprint.