diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f4bbdc..61c393f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ # Changelog -- Will be maintained after alpha releases are out of the way. :) +## Next version [???] + +## v1.0.0 [06-02-2016] + +- First version released. +- 100% test coverage. +- Full documentation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75458fd..d0b73ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,66 +1,37 @@ # Contribution Guide -This guide will be updated with more thorough content, but for now, the best thing you could do to help the project is to create `Journal` packages. - -Journals are used to export the information from experiments to data stores for later inspection. They implement the `Scientist\Journals\Journal` interface: - -```php -getName(); // Get the experiment name. (string) -$report->getControl(); // Get the Scientist\Result instance for the control. (Scientist\Result) -$report->getTrial('name'); // Get the result instance for a trial by name. (Scientist\Result) -$report->getTrials(); // Get an assoc array of trial result instances (array) -``` - -And on the result instance: - -```php -$result->getValue(); // Get the resulting value of the trial/control callback. (mixed) -$result->isMatch(); // Did the result match the control? Use on trial results. (boolean) -$result->getStartTime(); // Float callable start microtime. (float) -$result->getEndTime(); // Float callable end microtime. (float) -$result->getTime(); // Get the execution microtime. (float) -$result->getStartMemory(); // Get memory usage before calling. (integer) -$result->getEndMemory(); // Get memory usage after calling. (integer) -$result->getMemory(); // Get different in memory usage. (integer) -``` - -If you create a new journal (and a composer package, format scientist-xxx-journal) then please be sure to raise an issue and let me know! I'll update the docs to mentions it. - -Thanks for all your support! - -- Dayle. +The best thing a contributor can do for the project right now, is to submit supporting resources. Here's some great ideas for you. + +## Create Bridge Packages + +Bridges allow Scientist to be used seamlessly with other frameworks and libraries. Learn more about Bridges [in the documentation](https://scientist.readme.io/docs/bridges). + +Please name your package `vendorname/scientist--bridge`. + +## Create Journals + +Journals allow the Scientist to export his experiment data to data storage platforms for latest inspection. + +Please name your package `vendorname/scientist--journal`. + +See more information [in the documentation](https://scientist.readme.io/docs/journals-1). + +## Create Matchers + +Matchers allow for complex data types to be matched using Scientist. + +Please name your package `vendorname/scientist--matcher`. + +See more information [in the documentation](https://scientist.readme.io/docs/matchers-1). + +## Create Interfaces + +Interfaces allow for unique ways to view your experiment data. + +Please name your package `vendorname/scientist--interface`. + +See more information [in the documentation](https://scientist.readme.io/docs/interfaces). + +--- + +Thanks for supporting the project! diff --git a/src/Experiment.php b/src/Experiment.php index 4bb8f0d..77a4dff 100644 --- a/src/Experiment.php +++ b/src/Experiment.php @@ -257,14 +257,14 @@ public function run() } /** - * Execute the experiment and return a result. + * Execute the experiment and return a report. * * @return \Scientist\Report */ - public function result() + public function report() { $this->params = func_get_args(); - return $this->laboratory->getResult($this); + return $this->laboratory->getReport($this); } } diff --git a/src/Intern.php b/src/Intern.php index c7c18f3..ef49d6a 100644 --- a/src/Intern.php +++ b/src/Intern.php @@ -74,7 +74,7 @@ protected function runTrials(Experiment $experiment) */ protected function determineMatches(Matcher $matcher, Result $control, array $trials = []) { - foreach ($trials as $name => $trial) { + foreach ($trials as $trial) { if ($matcher->match($control->getValue(), $trial->getValue())) { $trial->setMatch(true); } diff --git a/src/Laboratory.php b/src/Laboratory.php index c550e2f..dc900ef 100644 --- a/src/Laboratory.php +++ b/src/Laboratory.php @@ -81,8 +81,8 @@ public function experiment($name) public function runExperiment(Experiment $experiment) { if ($experiment->shouldRun()) { - $result = $this->getResult($experiment); - return $result->getControl()->getValue(); + $report = $this->getReport($experiment); + return $report->getControl()->getValue(); } return call_user_func_array( @@ -98,26 +98,26 @@ public function runExperiment(Experiment $experiment) * * @return \Scientist\Report */ - public function getResult(Experiment $experiment) + public function getReport(Experiment $experiment) { - $result = (new Intern)->run($experiment); - $this->reportToJournals($experiment, $result); + $report = (new Intern)->run($experiment); + $this->reportToJournals($experiment, $report); - return $result; + return $report; } /** * Report experiment result to registered journals. * * @param \Scientist\Experiment $experiment - * @param \Scientist\Report $result + * @param \Scientist\Report $report * * @return void */ - protected function reportToJournals(Experiment $experiment, Report $result) + protected function reportToJournals(Experiment $experiment, Report $report) { foreach ($this->journals as $journal) { - $journal->report($experiment, $result); + $journal->report($experiment, $report); } } } diff --git a/tests/ExampleTest.php b/tests/ExampleTest.php deleted file mode 100644 index 4811877..0000000 --- a/tests/ExampleTest.php +++ /dev/null @@ -1,54 +0,0 @@ -experiment('Replace name in a string.') - ->control($stringReplacement) - ->trial('Use preg_replace().', $regexReplacement) - ->run(); - - $this->assertEquals('My name is Dayle.', $value); - } - - public function test_to_run_a_simple_experiment_with_no_journals_and_check_result() - { - $string = 'My name is _NAME_.'; - - $stringReplacement = function () use ($string) { - return str_replace('_NAME_', 'Dayle', $string); - }; - - $regexReplacement = function () use ($string) { - return preg_replace('/\_NAME\_/', 'Dayle', $string); - }; - - $result = (new Laboratory) - ->experiment('Replace name in a string.') - ->control($stringReplacement) - ->trial('Use preg_replace().', $regexReplacement) - ->result(); - - $this->assertInternalType('float', $result->getControl()->getTime()); - $this->assertEquals('My name is Dayle.', $result->getControl()->getValue()); - - $trial = current($result->getTrials()); - $this->assertInternalType('float', $trial->getTime()); - $this->assertEquals('My name is Dayle.', $trial->getValue()); - $this->assertTrue($trial->isMatch()); - } -} diff --git a/tests/InternTest.php b/tests/InternTest.php new file mode 100644 index 0000000..d5464f0 --- /dev/null +++ b/tests/InternTest.php @@ -0,0 +1,59 @@ +assertInstanceOf(Intern::class, $i); + } + + public function test_that_intern_can_run_an_experiment() + { + $i = new Intern; + $e = new Experiment('test experiment'); + $e->control(function () { return 'foo'; }); + $v = $i->run($e); + $this->assertInstanceOf(Report::class, $v); + $this->assertEquals('foo', $v->getControl()->getValue()); + } + + public function test_that_intern_can_match_control_and_trial() + { + $i = new Intern; + $e = new Experiment('test experiment'); + $e->control(function () { return 'foo'; }); + $e->trial('bar', function () { return 'foo'; }); + $v = $i->run($e); + $this->assertInstanceOf(Report::class, $v); + $this->assertTrue($v->getTrial('bar')->isMatch()); + } + + public function test_that_intern_can_mismatch_control_and_trial() + { + $i = new Intern; + $e = new Experiment('test experiment'); + $e->control(function () { return 'foo'; }); + $e->trial('bar', function () { return 'bar'; }); + $v = $i->run($e); + $this->assertInstanceOf(Report::class, $v); + $this->assertFalse($v->getTrial('bar')->isMatch()); + } + + public function test_that_intern_can_match_and_mismatch_control_and_trial() + { + $i = new Intern; + $e = new Experiment('test experiment'); + $e->control(function () { return 'foo'; }); + $e->trial('bar', function () { return 'foo'; }); + $e->trial('baz', function () { return 'baz'; }); + $v = $i->run($e); + $this->assertInstanceOf(Report::class, $v); + $this->assertTrue($v->getTrial('bar')->isMatch()); + $this->assertFalse($v->getTrial('baz')->isMatch()); + } +} diff --git a/tests/Journals/JournalTest.php b/tests/Journals/JournalTest.php index 7520218..8880cf9 100644 --- a/tests/Journals/JournalTest.php +++ b/tests/Journals/JournalTest.php @@ -10,6 +10,7 @@ class JournalTest extends PHPUnit_Framework_TestCase public function test_that_journals_can_be_created() { $s = new StandardJournal; + $this->assertInstanceOf(StandardJournal::class, $s); } public function test_that_a_journal_can_be_added_to_a_laboratory() diff --git a/tests/LaboratoryTest.php b/tests/LaboratoryTest.php new file mode 100644 index 0000000..3b0d6b1 --- /dev/null +++ b/tests/LaboratoryTest.php @@ -0,0 +1,89 @@ +assertInstanceOf(Laboratory::class, $l); + } + + public function test_laboratory_can_run_experiment_with_no_journals() + { + $v = (new Laboratory) + ->experiment('test experiment') + ->control(function () { return 'foo'; }) + ->trial('trial name', function () { return 'foo'; }) + ->run(); + + $this->assertEquals('foo', $v); + } + + public function test_laboratory_can_fetch_report_for_experiment_with_no_journals() + { + $r = (new Laboratory) + ->experiment('test experiment') + ->control(function () { return 'foo'; }) + ->trial('trial', function () { return 'bar'; }) + ->report(); + + $this->assertInstanceOf(Report::class, $r); + $this->assertEquals('foo', $r->getControl()->getValue()); + $this->assertEquals('bar', $r->getTrial('trial')->getValue()); + $this->assertInternalType('float', $r->getControl()->getStartTime()); + $this->assertInternalType('float', $r->getControl()->getEndTime()); + $this->assertInternalType('float', $r->getControl()->getTime()); + $this->assertInternalType('float', $r->getTrial('trial')->getStartTime()); + $this->assertInternalType('float', $r->getTrial('trial')->getEndTime()); + $this->assertInternalType('float', $r->getTrial('trial')->getTime()); + $this->assertInternalType('integer', $r->getControl()->getStartMemory()); + $this->assertInternalType('integer', $r->getControl()->getEndMemory()); + $this->assertInternalType('integer', $r->getControl()->getMemory()); + $this->assertInternalType('integer', $r->getTrial('trial')->getStartMemory()); + $this->assertInternalType('integer', $r->getTrial('trial')->getEndMemory()); + $this->assertInternalType('integer', $r->getTrial('trial')->getMemory()); + $this->assertInternalType('null', $r->getControl()->getException()); + $this->assertInternalType('null', $r->getTrial('trial')->getException()); + $this->assertFalse($r->getTrial('trial')->isMatch()); + } + + public function test_that_exceptions_are_thrown_within_control() + { + $this->setExpectedException(Exception::class); + + $v = (new Laboratory) + ->experiment('test experiment') + ->control(function () { throw new Exception; }) + ->trial('trial', function () { return 'foo'; }) + ->run(); + } + + public function test_that_exceptions_are_swallowed_within_the_trial() + { + $r = (new Laboratory) + ->experiment('test experiment') + ->control(function () { return 'foo'; }) + ->trial('trial', function () { throw new Exception; }) + ->report(); + + $this->assertInstanceOf(Report::class, $r); + $this->assertInternalType('null', $r->getControl()->getException()); + $this->assertInstanceOf(Exception::class, $r->getTrial('trial')->getException()); + } + + public function test_that_control_and_trials_receive_parameters() + { + $r = (new Laboratory) + ->experiment('test experiment') + ->control(function ($one, $two) { return $one; }) + ->trial('trial', function ($one, $two) { return $two; }) + ->report('Panda', 'Giraffe'); + + $this->assertInstanceOf(Report::class, $r); + $this->assertEquals('Panda', $r->getControl()->getValue()); + $this->assertEquals('Giraffe', $r->getTrial('trial')->getValue()); + } +}