fix: support extra_lua_path in test framework

[grapestore]

Description

This PR adds support for setting custom Lua paths (extra_lua_path and extra_lua_cpath) in test files, aligning the test framework behavior with APISIX runtime configuration.

Previously, while APISIX runtime supported apisix.extra_lua_path in config.yaml to load custom plugins from specified directories, the test framework (t/APISIX.pm) did not respect this configuration. This made it impossible to write tests for custom plugins located in custom directories.

This PR implements two complementary methods for setting custom Lua paths in tests:

Method 1: Block definitions (preferred)
--- extra_lua_path: /custom/path/?.lua
--- extra_lua_cpath: /custom/path/?.soMethod 2: Automatic parsing from extra_yaml_config
--- extra_yaml_config
apisix:
extra_lua_path: "/custom/path/?.lua"
extra_lua_cpath: "/custom/path/?.so"The implementation:

• Prepends custom paths to lua_package_path and lua_package_cpath (matching runtime behavior)
• Block definitions take precedence when both methods are used
• Enables testing custom plugins without modifying core APISIX paths

Which issue(s) this PR fixes:

Fixes #12389

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added to this PR
• I have added tests corresponding to this change
• I have updated the documentation to reflect this change
• I have verified that this change is backward compatible (If not, please discuss on the APISIX mailing list first)

Test Coverage:
Added comprehensive test suite in t/admin/extra-lua-path.t covering:

• Path addition via block definitions
• YAML configuration parsing
• Simultaneous lua_path and lua_cpath configuration
• Correct path prepending behavior
• Precedence rules between configuration methods

Backward Compatibility:
This change is fully backward compatible. It only adds new optional block definitions (extra_lua_path, extra_lua_cpath) and parsing logic for existing extra_yaml_config. All existing tests continue to work without modification.

[Baoyuantop]

Codes LGTM, please fix the failed CI

[Baoyuantop]

Hi @grapestore, you can merge the latest main branch to make CI pass.

[grapestore]

I’ve updated my branch to follow the latest master branch

[grapestore]

Could you please take a look?

[membphis]

we need a real case to cover this case

[grapestore]

@membphis

Here is a real scenario:

We use the official APISIX Docker image while developing custom plugins.
The custom plugin directory is mounted into the container, and in tests we add that directory to extra_lua_path so the plugin can be loaded.

Example:

Mount local custom plugins to /usr/local/apisix/custom/plugins
In the test:
apisix.extra_lua_path: "/usr/local/apisix/custom/plugins/?.lua"
The issue is that the test framework does not prepend this extra_lua_path to lua_package_path.
As a result, during tests the custom plugin path is not included in package.path, and require fails to load the plugin.
This works correctly in a real APISIX runtime, but the test environment cannot see the plugin, causing inconsistent behavior.

This scenario clearly shows the problem where extra_lua_path is not applied in the test framework.

[membphis]

I mean:

you should add a test case to cove the case you show me right now

[Baoyuantop]

Hi @grapestore, following up on the previous review comments. Please let us know if you have any updates. Thank you.

[grapestore]

I added it @Baoyuantop @membphis

[grapestore]

update rebase

[Baoyuantop]

Hi @grapestore, the newly added test execution failed.

[grapestore]

check plz

[Copilot]

Pull request overview

This PR adds support for custom Lua paths in the APISIX test framework, addressing a gap where the test framework didn't respect extra_lua_path and extra_lua_cpath configurations that are available in APISIX runtime. This enables developers to write tests for custom plugins located in custom directories.

Changes:

• Extended the test framework preprocessor in t/APISIX.pm to extract and prepend custom Lua paths from block definitions or YAML configuration
• Added comprehensive test coverage in t/admin/extra-lua-path.t to verify all configuration methods and edge cases
• Created a test plugin test-extra-path to demonstrate real-world usage

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
t/APISIX.pm	Core implementation that extracts extra_lua_path and extra_lua_cpath from block definitions or extra_yaml_config and prepends them to lua_package_path and lua_package_cpath
t/admin/extra-lua-path.t	Comprehensive test suite covering block definitions, YAML config parsing, precedence rules, path prepending, and real plugin loading
t/plugin/custom-plugins/apisix/plugins/test-extra-path.lua	Simple test plugin that sets custom headers to verify custom plugin loading works correctly
docs/en/latest/internal/testing-framework.md	Documentation update explaining both configuration methods and precedence rules

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The code unconditionally appends a semicolon to the extra_lua_path value. If a user provides a path that already ends with a semicolon (e.g., /custom/path/?.lua;), this will result in a double semicolon (/custom/path/?.lua;;). While this is not harmful in practice (double semicolons in Lua package paths just add the default path), it's inconsistent with the runtime behavior in apisix/cli/ops.lua which checks if the path already ends with a semicolon before appending one.

Consider checking if the path already ends with a semicolon before appending, similar to the runtime implementation. The same applies to extra_lua_cpath on line 282.

[Baoyuantop]

Hi @grapestore, following up on the previous review comments. Please let us know if you have any updates. Thank you.

[moonming]

Hi @grapestore, thank you for adding extra_lua_path support to the test framework!

This improves the developer experience for plugin developers who need custom Lua paths in their tests.

Please:

1. Rebase on the latest master
2. Add a brief description of how to use this feature in the test framework (a comment in t/APISIX.pm or the PR description)

Thank you!