kahlan / docs Goto Github PK

As reported in kahlan/kahlan#290, the documentation on how to use a Filter does not work for kahlan 4.0.5.

Using [email protected] and given the following snippet from https://kahlan.github.io/docs/config-file.html:

// Use the `Coveralls` class to write the JSON coverage into a file
Coveralls::write([
    'coverage' => $coverage,
    'file' => $this->commandLine()->get('coverage-coveralls'),
    'service_name' => 'travis-ci',
    'service_job_id' => getenv('TRAVIS_JOB_ID') ?: null
]);

The following error is produced upon compiling:

PHP Fatal error:  Uncaught Error: Call to a member function export()

I traced the code through the specs and it seems the issue is due to a given Exporters write method wanting to take an instantiated Collector object as an input 'collector' option.

Many people are curious how the internals of Kahlan works including me. When I debug I can see the code is replace on the fly by some kind of patcher. It would be great to update the docs and give some details about it :)

kahlan/kahlan#51 introduced toMatchEcho with the following example for the documentation:

expect('Hello World!')->toMatchEcho(function($actual) {
    return $actual === 'Hello World!';
});

Which results in the following error when run:

`Error` Code(0) with message "Call to undefined function Hello World!()"

Whereas the following toMatch matcher runs without issue:

expect('Hello World!')->toMatch('/^H(.*?)!$/');

I left a comment in the PR introducing the feature. It's not clear if it's a core bug or a documentation issue. But as it stands the example in the docs is not correct.

Given the following snippet:

it('errors if handle is not registered', function () {
  $dependencies = $this->dependencies;
  $dependencies->registered = ['foo' => 'bar'];
  $closure = function () {
    get_dep_for_handle($dependencies, 'baz');
  };
  expect($closure)->toThrow();
});

Applied against the following code:

function get_dep_for_handle( $instance, $handle ) {
	return $instance->registered[ $handle ];
}

The test passes. But not because of the logical assertion being made. It throws in this case because $dependencies is not defined within the scope of the closure. As a result, please consider adding some examples of use to the docs to help prevent this kind of false positive from occurring in test implementations.

Under Kahlan 3.x and given the following code snippet:

namespace hyperdrive\spec;
use function hyperdrive\calibrate_thrusters;
use function hyperdrive\get_enqueued_scripts;

describe('calibrate_thrusters()', function () {
  it('expects get_enqueued_scripts() to be called', function () {
    allow('get_enqueued_scripts')
      ->toBeCalled()
      ->andRun(function () { return []; } );
    expect('get_enqueued_scripts')->toBeCalled();
    calibrate_thrusters();
  });
});

Where composer.json uses what I understand to be faux autoloading for files in order to achieve namespaced function imports in Kahlan:

"autoload": {
  "files": [
    "src/hyperdrive.php"
  ]
}

And with consideration to the following document:
https://kahlan.github.io/docs/allow.html

Which states:

Use allow() to stub almost all functions like so:

I believe the part of the blockquote which says almost all functions seems misleading given Kahlan, by way of Composer if I'm not mistaken, cannot autoload files. As a result, and with consideration to some of the related issues surfacing it seems the above line should be updated a caveat of some sort added to clarify what is meant by almost all functions.

Thoughts?

Aside: Barring current design, what might it take either in Composer or Kalhan to make something like the above possible otherwise (hoping this isn't a loaded question)?

Currently the first page is always highlighted (selected)

The documentation is a bit unclear what exactly the "magicMethods" option in Double::instance does.
From the Docs:

Note: If the 'extends' option is used, magic methods won't be included, so as to avoid any conflict between your tested classes and the magic methods.

It is unclear, which magic methods aren't included, the ones from the extended class or the default ones kahlan adds.
It should also be mentioned that if an interface defines a magic method the option 'magicMethods => false' has to be added, otherwise there is a conflict.