Skip to content

keithy/okay-php

Repository files navigation

Software License Tests Status GitHub issues Awesome Latest Version Minimum PHP Version Tested on PHP 5.3 to 8.2

OKAY 1.0 - Keeping It Simple Specifications for PHP

Totally the simplest BDD/TDD framework,... in the world!

Design based on the original SUnit by Kent Beck

A result of another Cunningham-Beck innovation: http://wiki.c2.com/?DoTheSimplestThingThatCouldPossiblyWork

Example Test/Spec/Okays

  • Tests - TDD
  • Specs - BDD vocabulary
  • Okays - Our name for platform tests
namespace ok {

    EXPECT("assertions ini configuration");

    _("to be enabled");
    
    assert(1 == ini_get('zend.assertions'));
    assert(0 == ini_get('assert.exception'));

}

Documentation:

  1. _okay.php is all of the code (<320 lines), both a command line and web test-runner

  2. Adding _ok.php to a directory of *.inc scripts/directories turns them into a spec/test suite. (edit it to have the correct path to invoke _okay.php)

    Each _ok.php can be modified to provide any one-time run_setup code for specs defined in that directory.

  3. BDD style "english" output.

    EXPECT("it to be good");
    
  4. Uses PHP built in assert

    _("it's going to be good");
    assert( $it == "good" , "'$it' wasn't good" );
    
  5. Use throughout your codebase, deployment optional

    Great for adding specs/tests to a file-based "legacy" PHP system. (adjust your deployment to ignore/delete _* files, and it's gone.)

  6. Zero dependencies

    Does not need a functioning composer/autoload, will not clutter a cool, lean code-base. Great for testing smaller bits and pieces (see .travis.yml for the non-trivial self-test example)

  7. Excellent basis for "Platform Tests", "healthz" style checks, and White Screen of Death debugging

    Platform-tests run to verify that the deployment platform, PHP runtime, and Databases and other bits and pieces are configured and working as expected.

    When faced with the PHP - W.S.O.D. and no clues, a platform test/spec suite can check for common miss-configuration scenarios and tell you what is working.

  8. Compare Runs - see only the differences

    # generate expected output
    php _okay.php | tee  .out
    # change something
    php _okay.php | diff -U5 .out -
    
  9. Go Continuous - genius!

    watch -n3  'php _okay.php | diff -U5 .out -' 
    
  10. Works great with github actions

jobs:
 build:
   runs-on: ubuntu-latest
   - name: Run okay test suite
     run: php _okay.php
  1. Works great with travis.ci
language: php
php: [5.6,7.1]
script: php okay/_okay.php -I

Usage Composer

composer require --dev okay/okay 

Usage Standalone

  1. Copy the _okay.php file to somewhere within your project, or to the root of your specs/tests/okay folder.

  2. Copy the _ok.php file to the root of any other specs/tests folder within your project. (edit it to have the correct path to invoke _okay.php)

Web Runner

Copy public/okay.phpto somewhere on your site, and copy config/gateway_okay.inc (edit it to have the correct path to invoke _okay.php)

Example Output

Nothing fancy

OKAY(VERSION 1.0.2):/home/travis/build/keithy/okay-php

Given okay spec file returns true or false
 1) Expect returning true to be a pass and to look like this

Given okay_specs function copy_all_matching can prepare fixtures
 2) Expect fixture directory to be empty
 3) Expect copy_all files from snapshot to populate fixture directory
 4) Expect delete files matching *.inc
      should leave a *.php file 
 5) Expect delete files matching *.php
      should leave directory empty

Given okay_specs function lookup_and_include is looking for needle
 6) Expect to find needle in same directory
 7) Expect to find needle via parent directory

Given okay_specs function lookup_and_include is looking for non existent file
 8) Expect it to return false

Given okay_specs example failure assertion fail, spec returns true
 9) Expect assertion failure
      to look like this
FAILED(14): assert failed AS EXPECTED
10) Expect specification return value
      should be ignored

Given okay_specs example failure assertion fail; spec returns false
11) Expect assertion failure
      to look like this
FAILED(14): assert failed AS EXPECTED
12) Expect specification return value
      should be ignored
Ran 6 files (12 expectations) failed 2 assertions