Add acceptance tests using behat

.github/workflows/ci-lsp.yml

@@ -41,6 +41,35 @@ jobs:
       - name: Run PHPUnit (LSP)
         run: make test/unit
 
+  behat-lsp:
+    name: Behat (LSP acceptance)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: none
+          tools: composer:v2
+
+      # Root deps first -- the isolated Behat install autoloads the root
+      # vendor/autoload at runtime (see tools/behat/composer.json).
+      - name: Install LSP dependencies
+        uses: ramsey/composer-install@v3
+
+      # Behat lives in its own composer.json (tools/behat) because Behat 3.x
+      # caps symfony/console at ^7 while the root pins ^8 via xphp-lang/xphp.
+      - name: Install Behat tooling dependencies
+        run: composer install --working-dir=tools/behat --no-interaction
+
+      # Drives the real LSP dispatcher end-to-end, fully in-memory; @todo
+      # scenarios are skipped via the gherkin tag filter in behat.dist.yml.
+      - name: Run Behat acceptance suite
+        run: make test/behat
+
   infection-lsp:
     name: Mutation testing (LSP)
     # Gate: only run when explicitly requested via the Actions tab.  The

.gitignore

@@ -1,5 +1,6 @@
 /vendor/
 /var/
+/tools/behat/vendor/
 .phpunit.result.cache
 .infection.json5.tmp.log
 /docker-compose.override.yml

Makefile

@@ -87,3 +87,38 @@ build/phar: $(BOX_PHAR)
 	php -d phar.readonly=0 var/box.phar compile --no-interaction
 	composer install --quiet --no-interaction
 	@echo "==> Built $$(ls -lh var/xphp-lsp.phar | awk '{print $$5, $$9}')"
+
+# Behat lives in an isolated tooling install (tools/behat) because Behat 3.x
+# caps symfony/console at ^7 while the root project pins ^8 via xphp-lang/xphp.
+# Its files-autoload pulls in the root autoloader so the harness resolves
+# XPHP\Lsp\* classes. Scenarios drive the REAL language server end-to-end via
+# phpactor's LanguageServerTester (the production LspDispatcherFactory + full
+# middleware stack); deferred behavior is tagged @todo and skipped. This target
+# is deliberately NOT part of the `test/unit` gate.
+# The warmer's stderr chatter is silenced from tools/behat/bootstrap.php
+# (putenv XPHP_LSP_QUIET=1), since shell env-prefixes don't propagate through
+# this project's containerized `php` proxy.
+# memory_limit=-1: the first scenario builds the worse-reflection stub map
+# (peaks ~512M, same as the PHPUnit handler tests), which OOMs under the default
+# CLI limit on a cold cache (e.g. in CI).
+BEHAT_BIN := tools/behat/vendor/bin/behat
+BEHAT := php -d error_reporting='E_ALL & ~E_DEPRECATED' -d memory_limit=-1 $(BEHAT_BIN)
+BEHAT_FLAGS := -c behat.dist.yml --colors
+
+$(BEHAT_BIN):
+	composer install --working-dir=tools/behat --quiet
+
+.PHONY: test/behat
+test/behat: $(BEHAT_BIN)
+	$(BEHAT) $(BEHAT_FLAGS)
+
+# Each feature file runs in its own process. Safe because every scenario builds
+# its own in-memory workspace -- no shared files/DB/ports. The one shared
+# resource is the read-only PHP-stubs cache; the pre-warm run below populates it
+# once (sequentially) so the parallel fan-out only ever reads it.
+.PHONY: test/behat/parallel
+test/behat/parallel: $(BEHAT_BIN)
+	@echo "==> warming shared stub cache"
+	@$(BEHAT) $(BEHAT_FLAGS) features/navigate/definition.feature >/dev/null 2>&1 || true
+	find features -name '*.feature' | xargs -P 4 -I{} \
+	  php -d error_reporting='E_ALL & ~E_DEPRECATED' -d memory_limit=-1 $(BEHAT_BIN) $(BEHAT_FLAGS) {}

behat.dist.yml

@@ -0,0 +1,25 @@
+default:
+    # Deferred behavior is written as @todo scenarios that document the desired
+    # outcome but are skipped, so the suite stays green on what's expected to work.
+    gherkin:
+        filters:
+            tags: '~@todo'
+    # Registers WorldArgumentResolver so the per-scenario World is
+    # constructor-injected into every context (and reset before each scenario).
+    extensions:
+        XPHP\Lsp\Test\Behat\WorldExtension: ~
+    suites:
+        default:
+            paths:
+                - '%paths.base%/features'
+            # Contexts live under test/ and are resolved by the root project's
+            # PSR-4 autoload-dev (XPHP\Lsp\Test\ -> test/), which the isolated
+            # Behat install pulls in via its files-autoload. ServerContext holds
+            # the cross-theme Givens + generic dispatchers; the rest are per-theme.
+            contexts:
+                - 'XPHP\Lsp\Test\Behat\ServerContext'
+                - 'XPHP\Lsp\Test\Behat\NavigateContext'
+                - 'XPHP\Lsp\Test\Behat\EditContext'
+                - 'XPHP\Lsp\Test\Behat\UnderstandContext'
+                - 'XPHP\Lsp\Test\Behat\ValidateContext'
+                - 'XPHP\Lsp\Test\Behat\FindContext'

features/README.md

@@ -0,0 +1,64 @@
+# Behavior specifications (Gherkin)
+
+Executable acceptance specs for the xphp language server, organized by theme.
+Each scenario drives the **real language server end-to-end** — phpactor's
+`LanguageServerTester` builds the production `LspDispatcherFactory`, runs the
+initialize/ServerCapabilities handshake, and routes real JSON-RPC requests
+through the full middleware stack to the handlers. Everything is **in-memory**
+(fixtures are opened via `textDocument/didOpen`; the transmitter is an array
+buffer — no stdio, sockets, or files), so the suite is isolated and
+parallel-safe.
+
+```
+features/
+├── navigate/   definition, type-definition, references, implementation,
+│               document & workspace symbols, document highlight,
+│               call hierarchy, type hierarchy
+├── edit/       rename, code actions, code lens, willRenameFiles
+├── understand/ hover, signature help, inlay hints, folding ranges, semantic tokens
+├── validate/   diagnostics (parse, undefined-name, bound, ctor-arg, duplicate)
+└── find/       completion, completion-item resolve
+```
+
+Each scenario is arranged **Given** (fixture file contents + warmed FQN index) /
+**When** (one LSP request) / **Then** (assert the response). Fixtures use
+leading-slash URIs (`/Foo.xphp`) for handlers that go through worse-reflection.
+
+## Step definitions
+
+The step definitions live in `test/Behat/` as plain context classes:
+
+- `World` — the shared per-scenario state + helpers: the `LanguageServerTester`
+  (real dispatcher), the request dispatch, and the fixture/position/assertion
+  helpers. It is **constructor-injected** into every context and a fresh one is
+  used per scenario/example.
+- `WorldArgumentResolver` + `WorldExtension` — the Behat extension that performs
+  that injection (tagged `context.argument_resolver`) and resets the `World`
+  before each scenario/example (tagged `event_dispatcher.subscriber`).
+- `ServerContext` — the cross-theme fixture Givens and the generic request
+  dispatchers.
+- `NavigateContext`, `EditContext`, `UnderstandContext`, `ValidateContext`,
+  `FindContext` — the When/Then steps for each theme, delegating to the injected
+  `World`.
+
+## Running
+
+```sh
+make test/behat            # sequential
+make test/behat/parallel   # one process per feature file
+```
+
+Behat is installed in an isolated tooling dir (`tools/behat/`) because Behat 3.x
+caps `symfony/console` at `^7` while the project pins `^8` via `xphp-lang/xphp`.
+`make test/behat` bootstraps it on first run.
+
+## @todo scenarios
+
+Deferred behavior is written as `@todo` scenarios that document the desired
+outcome but are skipped (via the gherkin tag filter in `behat.dist.yml`), so the
+suite stays green on what's expected to work. Current `@todo`s:
+
+- go-to-definition through a generic **method** call (navigate/definition)
+- **duplicate-template** diagnostic on the edited file — the per-file pull
+  provider canonicalizes the edited file, so it surfaces on the other file;
+  needs the roadmap's cross-file diagnostic broadcast (validate/diagnostics)

features/edit/code_action.feature

@@ -0,0 +1,48 @@
+Feature: Code actions
+  As a developer editing xphp
+  I want lightbulb quick-fixes for imports and diagnostics
+
+  Background:
+    Given the file at "/Models/User.xphp" contains the following lines:
+      """
+      <?php
+      namespace App\Models;
+      class User {}
+      """
+    And the file at "/Demos/Make.xphp" contains the following lines:
+      """
+      <?php
+      namespace App\Demos;
+      function make(): void { new User(); }
+      """
+    And the file at "/Unused.xphp" contains the following lines:
+      """
+      <?php
+      namespace App;
+      use App\Other\Unused;
+      $x = 1;
+      """
+    And the file at "/Typo.xphp" contains the following lines:
+      """
+      <?php
+      $x = nul;
+      """
+    And the FQN index has been warmed on initialize
+
+  Scenario: Offer to import an unresolved class
+    When I request code actions on "User" at line 2 of "/Demos/Make.xphp"
+    Then a code action titled "Import App\Models\User" is offered
+    And the "Import App\Models\User" action has kind "refactor.rewrite"
+    And the "Import App\Models\User" action inserts "use App\Models\User;"
+
+  Scenario: Offer to remove an unused import
+    When I request code actions on "Unused" at line 2 of "/Unused.xphp"
+    Then a code action titled "Optimize imports" is offered
+    And the "Optimize imports" action has kind "source.organizeImports"
+    And the "Optimize imports" action removes the "use App\Other\Unused;" line
+
+  Scenario: Offer to fix an undefined-name typo
+    When I request code actions for an undefined-name diagnostic on "nul" at line 1 of "/Typo.xphp"
+    Then a code action titled 'Change to "null"' is offered
+    And the 'Change to "null"' action has kind "quickfix"
+    And the 'Change to "null"' action replaces "nul" with "null"

features/edit/code_lens.feature

@@ -0,0 +1,31 @@
+Feature: Code lens
+  As a developer editing xphp
+  I want a "Show references" lens above declarations, resolved lazily
+
+  Background:
+    Given the file at "/Foo.xphp" contains the following lines:
+      """
+      <?php
+      namespace App;
+      class Foo {
+          public function bar(): void {}
+      }
+      """
+    And the file at "/use.xphp" contains the following lines:
+      """
+      <?php
+      use App\Foo;
+      $f = new Foo();
+      $f->bar();
+      """
+    And the FQN index has been warmed on initialize
+
+  Scenario: Emit a "Show references" lens for a declaration
+    When I request code lenses for "/Foo.xphp"
+    Then a code lens titled "Show references" is offered
+
+  Scenario: Resolve a lens to a usage count
+    When I request code lenses for "/Foo.xphp"
+    And I resolve the first code lens
+    Then the resolved lens reads "2 usages"
+    And the resolved lens carries the reference locations

features/edit/negative.feature

@@ -0,0 +1,25 @@
+Feature: Editing when there is nothing to change
+  As a developer editing xphp
+  I want no quick-fix or rename produced when there is nothing to act on
+
+  Scenario: No code actions on a clean position
+    Given the file at "/Clean.xphp" contains the following lines:
+      """
+      <?php
+      namespace App;
+      $x = 1;
+      """
+    And the FQN index has been warmed on initialize
+    When I request code actions on "1" at line 2 of "/Clean.xphp"
+    Then no code actions are offered
+
+  Scenario: Renaming a non-symbol position yields no edit
+    Given the file at "/R.xphp" contains the following lines:
+      """
+      <?php
+      namespace App;
+      $x = 1;
+      """
+    And the FQN index has been warmed on initialize
+    When I rename "1" at line 2 of "/R.xphp" to "Foo"
+    Then the response is null

features/edit/rename.feature

@@ -0,0 +1,26 @@
+Feature: Rename symbol
+  As a developer editing xphp
+  I want renaming a class to rewrite its declaration and every reference
+
+  Background:
+    Given the file at "/User.xphp" contains the following lines:
+      """
+      <?php
+      namespace App;
+      class User {}
+      """
+    And the file at "/Use.xphp" contains the following lines:
+      """
+      <?php
+      namespace X;
+      use App\User;
+      $u = new User();
+      """
+    And the FQN index has been warmed on initialize
+
+  Scenario: Rename a class and all of its references
+    When I rename "User" at line 2 of "/User.xphp" to "Customer"
+    Then the rename touches 2 files
+    And the rename applies 3 edits
+    And every rename edit inserts "Customer"
+    And every rename edit covers "User"

features/edit/will_rename_files.feature

@@ -0,0 +1,24 @@
+Feature: Rename class on file rename
+  As a developer editing xphp
+  I want renaming a file to rename its single class and update references
+
+  Background:
+    Given the file at "file:///Collection.xphp" contains the following lines:
+      """
+      <?php
+      namespace App;
+      class Collection {}
+      """
+    And the file at "file:///Consumer.xphp" contains the following lines:
+      """
+      <?php
+      namespace App\X;
+      use App\Collection;
+      $c = new Collection();
+      """
+    And the FQN index has been warmed on initialize
+
+  Scenario: Renaming the file renames the class and updates the importer
+    When I rename the file "file:///Collection.xphp" to "file:///Zollection.xphp"
+    Then the rename touches 2 files
+    And a willRename edit inserts "Zollection"