Lens

Welcome

Lens is a unit-testing framework for PHP. You get a command-line tool that you can run after you’ve refactored your code, so you can see right away if anything is broken or untested.

Lens is unlike any other unit-testing framework—and its users absolutely love it!

Why use Lens?

Lens makes you more productive

Lens is so simple that it gets out of your way and lets you focus on your project. Here’s an example of a unit test:

// Test
$x = 1 + 1;

// Output
$x = 2;

Lens is an invisible framework: you’ll never see it appear anywhere in your tests. That means there is there is almost no learning curve and nothing to stand in your way. Lens lets you focus on your project: What could be nicer than that?

Lens makes you more confident

Lens catches anything that differs from your expected output. Lens catches notices and warnings, a stray echo statement, a surprise global variable, and anything else that could possibly go wrong. Other unit-testing frameworks check only those things that are made explicit in your assertions. Lens widens the net and catches everything.

How do I use Lens?

You can download Lens by running a single command:

Download Lens
sudo php -r '$file = "/usr/local/bin/lens"; copy("http://lens.guide/lens.phar", $file); chmod($file, 0755);'

And now you can use Lens in your projects!

Verify Lens
lens --version

Getting started

All you really need to get started is a test file like this one:

Math.php
<?php

// Test
$x = 1 + 1;

// Output
$x = 2;

Now run Lens to see the results:

Run Lens
lens Math.php
# Passed tests: 1
Download this example

Now let’s move this code into a class, so we can run some more realistic tests. Let’s create a “src” directory with the following file:

src/Math.php
<?php

class Math
{
    public function add($m, $n)
    {
        return $m + $n;
    }
}

And a “tests” directory with the new tests file:

tests/Math.php
<?php

$math = new Math();

// Test
$x = $math->add(1, 1);

// Output
$x = 2;

You can see that we’re using our new class in the test now. We’ll need to load that new class somehow, so let’s add an autoload file. We’ll use a stub for now:

autoload.php
<?php

require __DIR__ . '/src/Math.php';

Now let’s run Lens again:

Run Lens
lens
# Passed tests: 1

The test still passes… and now a “coverage” directory has appeared! Take a look inside that “coverage” directory: You’ll see a line-by-line view of the unit-test coverage for the project. Right now, we’re at 100% coverage:

Code coverage: directory view
Code coverage: file view
Download this example

But now let’s introduce a bug in the source code:

src/Math.php
<?php

class Math
{
    public function add($m, $n)
    {
        echo "m: $m\n";
        return $m + $n;
    }
}

The unit test will fail:

Run Lens
lens
#    Math.php:
#
#    // Test
#    $x = $math->add(1, 1);
# 
#    // Output
#    $x = 2;
# 
#    // Issues
#  + echo "m: 1\n";
#
#
# Failed tests: 1

Lens is a detector for unexpected behavior. That “echo” statement wasn’t listed under our expected “Output” section, so Lens alerted us to the discrepancy.

Download this example

Now, let’s fix the issue and add another method:

src/Math.php
<?php

class Math
{
    public function add($m, $n)
    {
        return $m + $n;
    }

    public function multiply($m, $n)
    {
        return $m * $n;
    }
}

And let’s write some more unit tests:

tests/Math.php
<?php

$math = new Math();


// Test
$x = $math->add(1, 1);

// Output
$x = 2;


// Test
$x = $math->multiply($a, $b);

// Input
$a = 1;
$b = 1;

// Output
$x = 1;

// Input
$a = 0;
$b = 1;

// Output
$x = 0;

As you can see, you can include more than one test in your tests file. It’s common to write one file per class.

And, as you might have guessed, you can specify an “Input” section for each test: With both the “Input” and “Output” specified, your test is fully parameterized. You can reuse the same test many times with different input and output.

Download this example

All right, I think that’s enough to get you started. I hope you enjoy discovering everything you can do with this unit testing framework. After all, I built it for you :)

And be sure to check out the documentation if you’d like more detailed information on any specific topic.