1
0
mirror of https://github.com/danog/psalm.git synced 2024-12-11 16:59:45 +01:00
psalm/tests/DocumentationTest.php

475 lines
16 KiB
PHP
Raw Normal View History

<?php
namespace Psalm\Tests;
use DOMAttr;
use DOMDocument;
use DOMXPath;
use PHPUnit\Framework\Constraint\Constraint;
use Psalm\Config;
2021-12-03 20:11:20 +01:00
use Psalm\Config\IssueHandler;
use Psalm\Context;
use Psalm\DocComment;
2021-12-03 20:29:06 +01:00
use Psalm\Exception\CodeException;
2021-12-03 20:11:20 +01:00
use Psalm\Internal\Analyzer\ProjectAnalyzer;
use Psalm\Internal\Provider\FakeFileProvider;
2021-12-03 20:11:20 +01:00
use Psalm\Internal\Provider\Providers;
use Psalm\Internal\RuntimeCaches;
2023-01-18 01:30:43 +01:00
use Psalm\Issue\UnusedBaselineEntry;
2021-12-04 21:55:53 +01:00
use Psalm\Tests\Internal\Provider\FakeParserCacheProvider;
2021-12-03 21:40:18 +01:00
use UnexpectedValueException;
use function array_diff;
use function array_filter;
2019-07-05 22:24:00 +02:00
use function array_keys;
use function array_map;
use function array_shift;
2019-07-05 22:24:00 +02:00
use function count;
use function dirname;
use function explode;
use function file;
2019-07-05 22:24:00 +02:00
use function file_exists;
use function file_get_contents;
use function glob;
2019-07-05 22:24:00 +02:00
use function implode;
use function in_array;
use function preg_match;
2019-07-05 22:24:00 +02:00
use function preg_quote;
use function scandir;
use function sort;
use function str_replace;
use function strlen;
2021-06-08 04:55:21 +02:00
use function strpos;
2019-07-05 22:24:00 +02:00
use function substr;
use function trim;
use function usort;
use function var_export;
use const DIRECTORY_SEPARATOR;
use const FILE_IGNORE_NEW_LINES;
use const FILE_SKIP_EMPTY_LINES;
use const LIBXML_NONET;
class DocumentationTest extends TestCase
{
/**
* a list of all files containing annotation documentation
*/
private const ANNOTATION_DOCS = [
'docs/annotating_code/supported_annotations.md',
'docs/annotating_code/templated_annotations.md',
'docs/annotating_code/adding_assertions.md',
'docs/security_analysis/annotations.md',
];
/**
* annotations that we dont want documented
*/
private const INTENTIONALLY_UNDOCUMENTED_ANNOTATIONS = [
'@psalm-self-out', // Not documented as it's a legacy alias of @psalm-this-out
'@psalm-variadic',
];
/**
* These should be documented
*/
private const WALL_OF_SHAME = [
'@psalm-assert-untainted',
'@psalm-flow',
2022-04-27 07:46:13 +02:00
'@psalm-generator-return',
'@psalm-override-method-visibility',
'@psalm-override-property-visibility',
'@psalm-scope-this',
'@psalm-seal-methods',
'@psalm-stub-override',
];
2022-12-16 19:58:47 +01:00
protected ProjectAnalyzer $project_analyzer;
2022-12-16 19:58:47 +01:00
private static string $docContents = '';
/**
* @return array<string, array<int, string>>
*/
private static function getCodeBlocksFromDocs(): array
{
2022-01-12 22:22:21 +01:00
$issues_dir = dirname(__DIR__) . DIRECTORY_SEPARATOR . 'docs' . DIRECTORY_SEPARATOR . 'running_psalm' . DIRECTORY_SEPARATOR . 'issues';
2020-03-19 17:32:49 +01:00
if (!file_exists($issues_dir)) {
2021-12-03 21:40:18 +01:00
throw new UnexpectedValueException('docs not found');
}
$issue_code = [];
2020-03-19 17:32:49 +01:00
foreach (glob($issues_dir . '/*.md') as $file_path) {
$file_contents = file_get_contents($file_path);
2020-03-19 17:32:49 +01:00
$file_lines = explode("\n", $file_contents);
2020-03-19 17:32:49 +01:00
$current_issue = str_replace('# ', '', array_shift($file_lines));
2020-03-19 17:32:49 +01:00
for ($i = 0, $j = count($file_lines); $i < $j; ++$i) {
$current_line = $file_lines[$i];
2020-03-19 17:32:49 +01:00
if (substr($current_line, 0, 6) === '```php' && $current_issue) {
$current_block = '';
++$i;
2020-03-19 17:32:49 +01:00
do {
$current_block .= $file_lines[$i] . "\n";
++$i;
} while (substr($file_lines[$i], 0, 3) !== '```' && $i < $j);
$issue_code[$current_issue][] = trim($current_block);
continue 2;
}
}
}
return $issue_code;
}
public function setUp(): void
{
Test parallelization (#4045) * Run tests in random order Being able to run tests in any order is a pre-requisite for being able to run them in parallel. * Reset type coverage between tests, fix affected tests * Reset parser and lexer between test runs and on php version change Previously lexer was reset, but parser kept the reference to the old one, and reference to the parser was kept by StatementsProvider. This resulted in order-dependent tests - if the parser was first initialized with phpVersion set to 7.4 then arrow functions worked fine, but were failing when the parser was initially constructed with settings for 7.3 This can be demonstrated on current master by upgrading to nikic/php-parser:4.9 and running: ``` vendor/bin/phpunit --no-coverage --filter="inferredArgArrowFunction" tests/ClosureTest.php ``` Now all tests using PHP 7.4 features must set the PHP version accordingly. * Marked more tests using 7.4 syntax * Reset newline-between-annotation flag between tests * Resolve real paths before passing them to checkPaths When checkPaths is called from psalm.php the paths are resolved, so we just mimicking SUT behaviour here. * Restore newline-between-annotations in DocCommentTest * Tweak Appveyor caches * Tweak TravisCI caches * Tweak CircleCI caches * Run tests in parallel Use `vendor/bin/paratest` instead of `vendor/bin/phpunit` * Use default paratest runner on Windows WrapperRunner is not supported on Windows. * TRAVIS_TAG could be empty * Restore appveyor conditional caching
2020-08-23 16:32:07 +02:00
RuntimeCaches::clearAll();
$this->file_provider = new FakeFileProvider();
2021-12-03 20:11:20 +01:00
$this->project_analyzer = new ProjectAnalyzer(
new TestConfig(),
2021-12-03 20:11:20 +01:00
new Providers(
$this->file_provider,
2022-12-18 17:15:15 +01:00
new FakeParserCacheProvider(),
),
);
2019-02-07 21:27:43 +01:00
$this->project_analyzer->setPhpVersion('8.0', 'tests');
}
public function testAllIssuesCoveredInConfigSchema(): void
{
2021-12-03 20:11:20 +01:00
$all_issues = IssueHandler::getAllIssueTypes();
$all_issues[] = 'PluginIssue'; // not an ordinary issue
sort($all_issues);
$schema = new DOMDocument();
$schema->load(__DIR__ . '/../config.xsd', LIBXML_NONET);
$xpath = new DOMXPath($schema);
$xpath->registerNamespace('xs', 'http://www.w3.org/2001/XMLSchema');
/** @var iterable<mixed, DOMAttr> $handlers */
$handlers = $xpath->query('//xs:complexType[@name="IssueHandlersType"]/xs:choice/xs:element/@name');
$handler_types = [];
foreach ($handlers as $handler) {
$handler_types[] = $handler->value;
}
sort($handler_types);
$this->assertSame(implode("\n", $all_issues), implode("\n", $handler_types));
}
public function testAllIssuesCovered(): void
{
2021-12-03 20:11:20 +01:00
$all_issues = IssueHandler::getAllIssueTypes();
2019-05-03 21:29:44 +02:00
$all_issues[] = 'ParseError';
$all_issues[] = 'PluginIssue';
sort($all_issues);
$code_blocks = self::getCodeBlocksFromDocs();
// these cannot have code
$code_blocks['UnrecognizedExpression'] = true;
$code_blocks['UnrecognizedStatement'] = true;
$code_blocks['PluginIssue'] = true;
$code_blocks['TaintedInput'] = true;
$code_blocks['TaintedCustom'] = true;
2020-11-27 23:02:37 +01:00
$code_blocks['ComplexFunction'] = true;
$code_blocks['ComplexMethod'] = true;
$code_blocks['ConfigIssue'] = true;
$documented_issues = array_keys($code_blocks);
sort($documented_issues);
$this->assertSame(implode("\n", $all_issues), implode("\n", $documented_issues));
}
/**
2018-11-06 03:57:36 +01:00
* @dataProvider providerInvalidCodeParse
* @small
Add support for strict arrays, fix type alias intersection, fix array_is_list assertion on non-lists (#8395) * Immutable CodeLocation * Remove excess clones * Remove external clones * Remove leftover clones * Fix final clone issue * Immutable storages * Refactoring * Fixes * Fixes * Fix * Fix * Fixes * Simplify * Fixes * Fix * Fixes * Update * Fix * Cache global types * Fix * Update * Update * Fixes * Fixes * Refactor * Fixes * Fix * Fix * More caching * Fix * Fix * Update * Update * Fix * Fixes * Update * Refactor * Update * Fixes * Break one more test * Fix * FIx * Fix * Fix * Fix * Fix * Improve performance and readability * Equivalent logic * Fixes * Revert * Revert "Revert" This reverts commit f9175100c8452c80559234200663fd4c4f4dd889. * Fix * Fix reference bug * Make default TypeVisitor immutable * Bugfix * Remove clones * Partial refactoring * Refactoring * Fixes * Fix * Fixes * Fixes * cs-fix * Fix final bugs * Add test * Misc fixes * Update * Fixes * Experiment with removing different property * revert "Experiment with removing different property" This reverts commit ac1156e077fc4ea633530d51096d27b6e88bfdf9. * Uniform naming * Uniform naming * Hack hotfix * Clean up $_FILES ref #8621 * Undo hack, try fixing properly * Helper method * Remove redundant call * Partially fix bugs * Cleanup * Change defaults * Fix bug * Fix (?, hope this doesn't break anything else) * cs-fix * Review fixes * Bugfix * Bugfix * Improve logic * Add support for list{} and callable-list{} types, properly implement array_is_list assertions (fixes #8389) * Default to sealed arrays * Fix array_merge bug * Fixes * Fix * Sealed type checks * Properly infer properties-of and get_object_vars on final classes * Fix array_map zipping * Fix tests * Fixes * Fixes * Fix more stuff * Recursively resolve type aliases * Fix typo * Fixes * Fix array_is_list assertion on keyed array * Add BC docs * Fixes * fix * Update * Update * Update * Update * Seal arrays with count assertions * Fix #8528 * Fix * Update * Improve sealed array foreach logic * get_object_vars on template properties * Fix sealed array assertion reconciler logic * Improved reconciler * Add tests * Single source of truth for test types * Fix tests * Fixup tests * Fixup tests * Fixup tests * Update * Fix tests * Fix tests * Final fixes * Fixes * Use list syntax only when needed * Fix tests * Cs-fix * Update docs * Update docs * Update docs * Update docs * Update docs * Document missing types * Update docs * Improve class-string-map docs * Update * Update * I love working on psalm :) * Keep arrays unsealed by default * Fixup tests * Fix syntax mistake * cs-fix * Fix typo * Re-import missing types * Keep strict types only in return types * argc/argv fixes * argc/argv fixes * Fix test * Comment-out valinor code, pinging @romm pls merge https://github.com/CuyZ/Valinor/pull/246 so we can add valinor to the psalm docs :)
2022-11-05 22:34:42 +01:00
* @param array<string> $ignored_issues
*/
public function testInvalidCode(string $code, string $error_message, array $ignored_issues = [], bool $check_references = false, string $php_version = '8.0'): void
{
if (strpos($this->getTestName(), 'SKIPPED-') !== false) {
$this->markTestSkipped();
}
$this->project_analyzer->setPhpVersion($php_version, 'tests');
2018-02-04 00:52:35 +01:00
if ($check_references) {
2018-11-11 18:01:14 +01:00
$this->project_analyzer->getCodebase()->reportUnusedCode();
2019-08-18 20:27:50 +02:00
$this->project_analyzer->trackUnusedSuppressions();
2018-02-04 00:52:35 +01:00
}
$is_taint_test = strpos($error_message, 'Tainted') !== false;
$is_array_offset_test = strpos($error_message, 'ArrayOffset') && strpos($error_message, 'PossiblyUndefined') !== false;
$this->project_analyzer->getConfig()->ensure_array_string_offsets_exist = $is_array_offset_test;
$this->project_analyzer->getConfig()->ensure_array_int_offsets_exist = $is_array_offset_test;
Add support for strict arrays, fix type alias intersection, fix array_is_list assertion on non-lists (#8395) * Immutable CodeLocation * Remove excess clones * Remove external clones * Remove leftover clones * Fix final clone issue * Immutable storages * Refactoring * Fixes * Fixes * Fix * Fix * Fixes * Simplify * Fixes * Fix * Fixes * Update * Fix * Cache global types * Fix * Update * Update * Fixes * Fixes * Refactor * Fixes * Fix * Fix * More caching * Fix * Fix * Update * Update * Fix * Fixes * Update * Refactor * Update * Fixes * Break one more test * Fix * FIx * Fix * Fix * Fix * Fix * Improve performance and readability * Equivalent logic * Fixes * Revert * Revert "Revert" This reverts commit f9175100c8452c80559234200663fd4c4f4dd889. * Fix * Fix reference bug * Make default TypeVisitor immutable * Bugfix * Remove clones * Partial refactoring * Refactoring * Fixes * Fix * Fixes * Fixes * cs-fix * Fix final bugs * Add test * Misc fixes * Update * Fixes * Experiment with removing different property * revert "Experiment with removing different property" This reverts commit ac1156e077fc4ea633530d51096d27b6e88bfdf9. * Uniform naming * Uniform naming * Hack hotfix * Clean up $_FILES ref #8621 * Undo hack, try fixing properly * Helper method * Remove redundant call * Partially fix bugs * Cleanup * Change defaults * Fix bug * Fix (?, hope this doesn't break anything else) * cs-fix * Review fixes * Bugfix * Bugfix * Improve logic * Add support for list{} and callable-list{} types, properly implement array_is_list assertions (fixes #8389) * Default to sealed arrays * Fix array_merge bug * Fixes * Fix * Sealed type checks * Properly infer properties-of and get_object_vars on final classes * Fix array_map zipping * Fix tests * Fixes * Fixes * Fix more stuff * Recursively resolve type aliases * Fix typo * Fixes * Fix array_is_list assertion on keyed array * Add BC docs * Fixes * fix * Update * Update * Update * Update * Seal arrays with count assertions * Fix #8528 * Fix * Update * Improve sealed array foreach logic * get_object_vars on template properties * Fix sealed array assertion reconciler logic * Improved reconciler * Add tests * Single source of truth for test types * Fix tests * Fixup tests * Fixup tests * Fixup tests * Update * Fix tests * Fix tests * Final fixes * Fixes * Use list syntax only when needed * Fix tests * Cs-fix * Update docs * Update docs * Update docs * Update docs * Update docs * Document missing types * Update docs * Improve class-string-map docs * Update * Update * I love working on psalm :) * Keep arrays unsealed by default * Fixup tests * Fix syntax mistake * cs-fix * Fix typo * Re-import missing types * Keep strict types only in return types * argc/argv fixes * argc/argv fixes * Fix test * Comment-out valinor code, pinging @romm pls merge https://github.com/CuyZ/Valinor/pull/246 so we can add valinor to the psalm docs :)
2022-11-05 22:34:42 +01:00
foreach ($ignored_issues as $error_level) {
2018-11-11 18:01:14 +01:00
$this->project_analyzer->getCodebase()->config->setCustomErrorLevel($error_level, Config::REPORT_SUPPRESS);
}
2021-12-03 20:29:06 +01:00
$this->expectException(CodeException::class);
2022-01-19 19:29:16 +01:00
$this->expectExceptionMessageMatches('/\b' . preg_quote($error_message, '/') . '\b/');
$codebase = $this->project_analyzer->getCodebase();
$codebase->config->visitPreloadedStubFiles($codebase);
$file_path = self::$src_dir_path . 'somefile.php';
$this->addFile($file_path, $code);
if ($is_taint_test) {
$this->project_analyzer->trackTaintedInputs();
}
$this->analyzeFile($file_path, new Context());
if ($check_references) {
$this->project_analyzer->consolidateAnalyzedData();
}
}
/**
* @return array<string,array{string,string,string[],bool,string}>
*/
public function providerInvalidCodeParse(): array
{
$invalid_code_data = [];
foreach (self::getCodeBlocksFromDocs() as $issue_name => $blocks) {
$php_version = '8.0';
$ignored_issues = [];
switch ($issue_name) {
case 'InvalidStringClass':
case 'MissingThrowsDocblock':
case 'PluginClass':
case 'RedundantIdentityWithTrue':
2020-10-04 05:22:26 +02:00
case 'TraitMethodSignatureMismatch':
case 'UncaughtThrowInGlobalScope':
2023-01-18 01:30:43 +01:00
case UnusedBaselineEntry::getIssueType():
2020-10-04 05:22:26 +02:00
continue 2;
/** @todo reinstate this test when the issue is restored */
case 'MethodSignatureMustProvideReturnType':
continue 2;
case 'InvalidFalsableReturnType':
$ignored_issues = ['FalsableReturnStatement'];
break;
case 'InvalidNullableReturnType':
$ignored_issues = ['NullableReturnStatement'];
break;
case 'InvalidReturnType':
$ignored_issues = ['InvalidReturnStatement'];
break;
case 'MixedInferredReturnType':
$ignored_issues = ['MixedReturnStatement'];
break;
case 'MixedStringOffsetAssignment':
$ignored_issues = ['MixedAssignment'];
break;
2018-05-08 22:34:08 +02:00
case 'ParadoxicalCondition':
$ignored_issues = ['MissingParamType'];
break;
case 'UnusedClass':
case 'UnusedMethod':
$ignored_issues = ['UnusedVariable'];
break;
case 'AmbiguousConstantInheritance':
case 'DeprecatedConstant':
case 'DuplicateEnumCase':
case 'DuplicateEnumCaseValue':
case 'InvalidEnumBackingType':
case 'InvalidEnumCaseValue':
2022-12-12 08:12:55 +01:00
case 'InvalidEnumMethod':
case 'NoEnumProperties':
case 'OverriddenFinalConstant':
case 'InvalidInterfaceImplementation':
$php_version = '8.1';
break;
}
$invalid_code_data[$issue_name] = [
2020-03-21 00:15:06 +01:00
$blocks[0],
$issue_name,
$ignored_issues,
strpos($issue_name, 'Unused') !== false
|| strpos($issue_name, 'Unevaluated') !== false
|| strpos($issue_name, 'Unnecessary') !== false,
2022-12-18 17:15:15 +01:00
$php_version,
];
}
return $invalid_code_data;
}
public function testShortcodesAreUnique(): void
{
2021-12-03 20:11:20 +01:00
$all_issues = IssueHandler::getAllIssueTypes();
$all_shortcodes = [];
foreach ($all_issues as $issue_type) {
2023-02-15 08:02:34 +01:00
/** @var class-string $issue_class */
$issue_class = '\\Psalm\\Issue\\' . $issue_type;
/** @var int $shortcode */
$shortcode = $issue_class::SHORTCODE;
$all_shortcodes[$shortcode][] = $issue_type;
}
$duplicate_shortcodes = array_filter(
$all_shortcodes,
2023-10-21 20:45:09 +02:00
static fn($issues): bool => count($issues) > 1
);
$this->assertEquals(
[],
$duplicate_shortcodes,
2022-12-18 17:15:15 +01:00
"Duplicate shortcodes found: \n" . var_export($duplicate_shortcodes, true),
);
}
/** @dataProvider knownAnnotations */
public function testAllAnnotationsAreDocumented(string $annotation): void
{
if ('' === self::$docContents) {
foreach (self::ANNOTATION_DOCS as $file) {
self::$docContents .= file_get_contents(__DIR__ . '/../' . $file);
}
}
$this->assertThat(
self::$docContents,
$this->conciseExpected($this->stringContains('@psalm-' . $annotation)),
2022-12-18 17:15:15 +01:00
"'@psalm-$annotation' is not present in the docs",
);
}
/** @return iterable<string, array{string}> */
public function knownAnnotations(): iterable
{
foreach (DocComment::PSALM_ANNOTATIONS as $annotation) {
if (in_array('@psalm-' . $annotation, self::INTENTIONALLY_UNDOCUMENTED_ANNOTATIONS, true)) {
continue;
}
if (in_array('@psalm-' . $annotation, self::WALL_OF_SHAME, true)) {
continue;
}
yield $annotation => [$annotation];
}
}
/**
* Creates a constraint wrapper that displays the expected value in a concise form
*/
public function conciseExpected(Constraint $inner): Constraint
{
return new class ($inner) extends Constraint
{
2022-12-16 19:58:47 +01:00
private Constraint $inner;
public function __construct(Constraint $inner)
{
$this->inner = $inner;
}
public function toString(): string
{
return $this->inner->toString();
}
/**
* @param mixed $other
*/
protected function matches($other): bool
{
return $this->inner->matches($other);
}
/**
* @param mixed $other
*/
protected function failureDescription($other): string
{
return $this->exporter()->shortenedExport($other) . ' ' . $this->toString();
}
};
}
2022-01-12 22:22:21 +01:00
/**
* Tests that issues.md contains the expected links to issue documentation.
* issues.md can be generated automatically with bin/generate_documentation_issues_list.php.
*/
public function testIssuesIndex(): void
{
2022-01-12 22:22:21 +01:00
$docs_dir = dirname(__DIR__) . DIRECTORY_SEPARATOR . "docs" . DIRECTORY_SEPARATOR . "running_psalm" . DIRECTORY_SEPARATOR;
$issues_index = "{$docs_dir}issues.md";
$issues_dir = "{$docs_dir}issues";
if (!file_exists($issues_dir)) {
throw new UnexpectedValueException("Issues documentation not found");
}
if (!file_exists($issues_index)) {
throw new UnexpectedValueException("Issues index not found");
}
2022-12-12 08:12:55 +01:00
$issues_index_contents = file($issues_index, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
2022-10-03 15:13:47 +02:00
if ($issues_index_contents === false) {
throw new UnexpectedValueException("Issues index returned false");
}
array_shift($issues_index_contents); // Remove title
$issues_index_list = array_map(function (string $issues_line) {
preg_match('/^ - \[([^\]]*)\]\(issues\/\1\.md\)$/', $issues_line, $matches);
$this->assertCount(2, $matches, "Invalid format in issues index: $issues_line");
return $matches[1];
}, $issues_index_contents);
$issue_files = array_filter(array_map(function (string $issue_file) {
if ($issue_file === "." || $issue_file === "..") {
return false;
}
$this->assertStringEndsWith(".md", $issue_file, "Invalid file in issues documentation: $issue_file");
return substr($issue_file, 0, strlen($issue_file) - 3);
2022-01-12 22:22:21 +01:00
}, scandir($issues_dir)));
$unlisted_issues = array_diff($issue_files, $issues_index_list);
$this->assertEmpty($unlisted_issues, "Issue documentation missing from issues.md: " . implode(", ", $unlisted_issues));
$missing_documentation = array_diff($issues_index_list, $issue_files);
$this->assertEmpty($missing_documentation, "issues.md has link to non-existent documentation for: " . implode(", ", $missing_documentation));
$sorted = $issues_index_list;
usort($sorted, "strcasecmp");
for ($i = 0; $i < count($sorted); ++$i) {
$this->assertEquals($sorted[$i], $issues_index_list[$i], "issues.md out of order, expected {$sorted[$i]} before {$issues_index_list[$i]}");
}
}
}