9711864001

Committed 28 Jun 2024 11:11AM UTC coverage: 66.312% (-0.1%) from 66.445%

Build # 9711864001

Build Type

push

github

Committed by

web-flow

Commit Message

Ignore throws in function mocks (#245)

# Summary <!-- Required -->

I have noticed that in some circumstances the mocks contained in
`API/function-mocks.php` could trigger false positives in static
analyzers like PhpStan or just the IDE if using WP_Mock within a
project. I think by removing the `@throws` solves this, although PhpStan
will complain about it _in this_ project. I suppose since these are just
internal mocks we can safely ignore.

I did try using `@noinspection` tags but PhpStorm wasn't happy (whether
specific to unhandled exceptions or not).

As for the strict type notations, same reason, externally it will
reflect WP behavior (the alternative was to leave non-strict and rely
only on phpdoc -- like WP does -- but then PhpStan would complain
again... could swap that for a phpstan-ignore again, up to you)

## Closes #248 

## Contributor checklist <!-- Required -->

<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->
<!--- If you are unsure about any of these, please ask for
clarification. We are here to help! -->

- [x] I agree to follow this project's [**Code of
Conduct**](https://github.com/10up/.github/blob/trunk/CODE_OF_CONDUCT.md).
- [x] I have updated the documentation accordingly 
- [x] I have added tests to cover changes introduced by this pull
request
- [x] All new and existing tests pass

## Testing <!-- Required -->

<!-- If applicable, add specific steps for the reviewer to perform as
part of their testing process prior to approving this pull request. -->

<!-- List any configuration requirements for testing. -->

### Reviewer checklist <!-- Required -->

<!-- The following checklist is for the reviewer: add any steps that may
be relevant while reviewing this pull request -->

- [x] Code changes review
- [ ] Documentation changes review
- [x] Unit tests pass
- [x] Static analysis passes

Run Details

2 of 2 new or added lines in 1 file covered. (100.0%)

4 existing lines in 3 files now uncovered.

498 of 751 relevant lines covered (66.31%)

2.61 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

79.17

/php/WP_Mock/Functions/Handler.php

<?php

namespace WP_Mock\Functions;

use Exception;
use Mockery\Mock;
use PHPUnit\Framework\ExpectationFailedException;
use WP_Mock;

/**
 * Functions handler.
 *
 * This internal handler is meant to handle predefined function calls.
 *
 * @see WP_Mock\Functions
 */
class Handler
{
    /**
     * Mocked method handlers registered by the test class.
     *
     * @var array<string, callable|callable-string|array<mixed>>
     */
    private static array $handlers = [];

    /**
     * Overrides any existing handlers to set a new callback.
     *
     * @param string|callable-string $function function name
     * @param callable|callable-string|array<mixed> $callback
     * @return void
     */
    public static function registerHandler(string $function, $callback): void
    {
        self::$handlers[$function] = $callback;
    }

    /**
     * Handles a mocked function call.
     *
     * @param string|callable-string $functionName function name
     * @param array<mixed> $args function arguments
     * @return mixed|null
     * @throws ExpectationFailedException
     */
    public static function handleFunction(string $functionName, array $args = [])
    {
        if (self::handlerExists($functionName)) {
            /** @var callable $callback */
            $callback = self::$handlers[$functionName];

            return call_user_func_array($callback, $args);
        } elseif (WP_Mock::strictMode()) {
            throw new ExpectationFailedException(sprintf('No handler found for function %s', $functionName));
        }

        return null;
    }

    /**
     * Checks if a handler exists.
     *
     * @param string|callable-string $functionName
     * @return bool
     */
    public static function handlerExists(string $functionName): bool
    {
        return isset(self::$handlers[$functionName]);
    }

    /**
     * Clears all registered handlers.
     *
     * @return void
     */
    public static function cleanup(): void
    {
        self::$handlers = [];
    }

    /**
     * Helper function for common passthru return functions.
     *
     * @param string $functionName function name
     * @param array<mixed> $args function args
     * @return scalar
     * @throws ExpectationFailedException
     */
    public static function handlePredefinedReturnFunction(string $functionName, array $args = [])
    {
        $result = self::handleFunction($functionName, $args);

        if (! self::handlerExists($functionName)) {
            $result = $args[0] ?? $result;
        }

        /** @var scalar $result */
        return $result;
    }

    /**
     * Helper function for common echo functions.
     *
     * @param string $functionName function name
     * @param array<mixed> $args function arguments
     * @return void
     * @throws ExpectationFailedException
     */
    public static function handlePredefinedEchoFunction(string $functionName, array $args = []): void
    {
        ob_start();

        try {
            self::handleFunction($functionName, $args);
        } catch (Exception $exception) {
            ob_end_clean();

            /** @var ExpectationFailedException $exception */
            throw $exception;
        }

        $result = ob_get_clean();

        if (! is_string($result)) {
            throw new ExpectationFailedException(sprintf('Function %s did not echo a valid string', $functionName));
        }

        if (! self::handlerExists($functionName)) {
            /** @var scalar $result */
            $result = $args[0] ?? $result;
        }

        echo $result;
    }
}

1	<?php
2
3	namespace WP_Mock\Functions;
4
5	use Exception;
6	use Mockery\Mock;
7	use PHPUnit\Framework\ExpectationFailedException;
8	use WP_Mock;
9
10	/**
11	* Functions handler.
12	*
13	* This internal handler is meant to handle predefined function calls.
14	*
15	* @see WP_Mock\Functions
16	*/
17	class Handler
18	{
19	/**
20	* Mocked method handlers registered by the test class.
21	*
22	* @var array<string, callable\|callable-string\|array<mixed>>
23	*/
24	private static array $handlers = [];
25
26	/**
27	* Overrides any existing handlers to set a new callback.
28	*
29	* @param string\|callable-string $function function name
30	* @param callable\|callable-string\|array<mixed> $callback
31	* @return void
32	*/
33	public static function registerHandler(string $function, $callback): void
34	{
35	self::$handlers[$function] = $callback;	11✔
36	}
37
38	/**
39	* Handles a mocked function call.
40	*
41	* @param string\|callable-string $functionName function name
42	* @param array<mixed> $args function arguments
43	* @return mixed\|null
44	* @throws ExpectationFailedException
45	*/
46	public static function handleFunction(string $functionName, array $args = [])
47	{
48	if (self::handlerExists($functionName)) {	5✔
49	/** @var callable $callback */
50	$callback = self::$handlers[$functionName];	3✔
51
52	return call_user_func_array($callback, $args);	3✔
53	} elseif (WP_Mock::strictMode()) {	3✔
54	throw new ExpectationFailedException(sprintf('No handler found for function %s', $functionName));	×
55	}
56
57	return null;	3✔
58	}
59
60	/**
61	* Checks if a handler exists.
62	*
63	* @param string\|callable-string $functionName
64	* @return bool
65	*/
66	public static function handlerExists(string $functionName): bool
67	{
68	return isset(self::$handlers[$functionName]);	6✔
69	}
70
71	/**
72	* Clears all registered handlers.
73	*
74	* @return void
75	*/
76	public static function cleanup(): void
77	{
78	self::$handlers = [];	6✔
79	}
80
81	/**
82	* Helper function for common passthru return functions.
83	*
84	* @param string $functionName function name
85	* @param array<mixed> $args function args
86	* @return scalar
87	* @throws ExpectationFailedException
88	*/
89	public static function handlePredefinedReturnFunction(string $functionName, array $args = [])
90	{
91	$result = self::handleFunction($functionName, $args);	1✔
92
93	if (! self::handlerExists($functionName)) {	1✔
94	$result = $args[0] ?? $result;	1✔
95	}
96
97	/** @var scalar $result */
98	return $result;	1✔
99	}
100
101	/**
102	* Helper function for common echo functions.
103	*
104	* @param string $functionName function name
105	* @param array<mixed> $args function arguments
106	* @return void
107	* @throws ExpectationFailedException
108	*/
109	public static function handlePredefinedEchoFunction(string $functionName, array $args = []): void
110	{
111	ob_start();	1✔
112
113	try {
114	self::handleFunction($functionName, $args);	1✔
115	} catch (Exception $exception) {	×
116	ob_end_clean();	×
117
118	/** @var ExpectationFailedException $exception */
UNCOV 119	throw $exception;	×
120	}
121
122	$result = ob_get_clean();	1✔
123
124	if (! is_string($result)) {	1✔
125	throw new ExpectationFailedException(sprintf('Function %s did not echo a valid string', $functionName));	×
126	}
127
128	if (! self::handlerExists($functionName)) {	1✔
129	/** @var scalar $result */
130	$result = $args[0] ?? $result;	1✔
131	}
132
133	echo $result;	1✔
134	}
135	}

10up / wp_mock / 9711864001

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous