Add configuration to define the entry point of the app

[timrid]

What is the problem or limitation you are having?

If you want to use tests via the --test option, according to the docs you currently need to have a module such as tests.myapp to startup the tests.

The module name myapp is derived from the app name, but the package tests in which the module must be located is fixed. test_sources allows you to include any folder, but currently there must be at least one folder called tests that contains the main test module.

In Python, it is often common for the tests to be located in a tests folder, but this folder can also have a different name. Therefore, it would be good to have a configuration option for the main test package.

Describe the solution you'd like

There should be a configuration option test_main_package that allows you to configure the name of the main test package.

Describe alternatives you've considered

Leave everything as it is. The main package must always be called tests. However, the documentation for test_sources should make it clearer that it must contain a folder called tests.

Additional context

My current problem is that I want to run the integration tests of the BLE library Bleak on Android and iOS. Currently, these run on macOS/Linux/Window normally via pytest in a venv. However, in order to test these platforms on Android and iOS, I need a sample app in which the tests are integrated. For this purpose, I want to create a briefcase application, which should be located under /examples/briefcase. My desired project structure is as follows:

- bleak (already existing library source code)
  - __init__.py
  - ... 
- tests (already existing library tests)
  - integration
    - test_scanner.py
    - test_client.py
    - ...
  - ... 
- examples
  - briefcase
    - src
    - tests_startup
      - bleak_example.py
    - pyproject.toml

My examples/briefcase/pyproject.toml should look like this:

[tool.briefcase.app.bleak_example]
...
test_main_package = "tests_startup"
test_sources = [
	"tests_startup",
	"../../tests"
]

I could, of course, simply move the file examples/briefcase/tests_startup/bleak_example.py to tests/bleak_example.py and remove the tests_startup folder entirely, but I don't want to modify the existing tests folder at all.

[freakboy3742]

Agreed that this is a configuration issue that needs a fix. What you've proposed definitely makes sense as the "obvious" fix.

The only thing that gives me pause is two other related areas where I'm aware that we could/should do work.

Entry points

The first is PEP 621 compliance with Entry Scripts. Python now has a formal mechanism for describing how to start an app as a GUI script and as a console script; we should be using these, rather than hard-coding anything or inventing our own settings.

The PEP 621 specification doesn't say anything about testing specifically. However, as your proposal highlights, in the context of Briefcase's current style of "GUI packaged test", that's effectively a different entry point, so we can lean on that. We can also use the intersection of app names and entry points for configuration purposes.

So - a definition might look something like:

[project]
...

[project.gui-scripts]
my-gui-app = "myapp.app:main"
weird-entry = "myapp.other:weird"
test-my-gui-app = "tests.myapp:main"
my-wierd-test = "myapp.other:weird"

[project.scripts]
my-console-app = "myapp.app:main"

[tool.briefcase.app.my-gui-app]
# defaults to an entry point of `my-gui-app`, and a GUI test entry point of `test-my-gui-app`
...

[tool.briefcase.app.my-console-app]
# defaults to an entry point of `my-console-app`, and a console test entry point of `test-my-console-app`
...

[tool.briefcase.app.my-other-app]
# Customized entry points
entry_point = "weird-entry"
test_entry_point = "my-weird-test"

That is - the existence of an entry point describes exactly how an app will be started; with an entry point matching an app name being the default entry point for an app, and an entry point prefixed with test- and an app name being the entry point for a test suite. However, an app can explicitly override the entry point it should use.

This solves:

• your reported problem of being able to customise the entry point of the test suite,
• adds the ability to customise the entry point of the app as well
• allows for much more flexibility in how an app module is defined
• If we follow the full specification and include extras handling, we can replace requires and test-requires as well (by using dependencies and optional-dependencies)
• Removes the need for the console_app setting entirely
• Provides a future option for a single console "app" to define and bundle multiple entry points by making entry_point a list.

There is a little friction in the documented behavior of how to handle the content after the : in an entry point; we're currently hard-coding that as part of the app, and assuming a module is the entry point; entry points assume it's the packaging tool's responsibility to generate the entry module. However, if we do some light refactoring of the generated app's mainline, we should be able to make the two compatible.

There's also the question of migrating existing projects - existing projects won't have the refactoring that would make entry points work - so do we assume if you don't define an entry point, you want old-style module-based startup (and presumably raise a warning)? We could even stretch the definition a little and say that if you don't have a colon in an entry point, we'll interpret that as Briefcase's "start module" behavior. That would be helpful for backwards compatibility, but I don't know if we want to start pushing on the boundaries of the formal specification like that.

Test suite types

The other area where I'm aware we need to do work is around supporting different "types" of test suite. Briefcase's current test suite is currently an "in app" test - the test suite is loaded into the app code itself, and runs inside the context of the app.

That clearly works for Toga's testbed (and I suspect would be what you need for Bleak), but there's another type of test suite that we need to accomodate: a test suite that runs on the test machine locally, and controlling the app by remote control. Selenium or Playwright test suites for a web app are the immediate analog here - a "normal" pytest suite running on the development machine that needs to start an app, connect to it, and then programmatically "poke" the app.

Testing Toga's web backend is the reason we've identified this problem - it's not possible to run a Toga-style pytest suite in the browser because we need threads. But, more generally, "remote control" testing allows for more reliable testing because we have direct access to the pytest process.

I'm not entirely sure how to incorporate this distinction though. We could add an entirely different "test mode" - so something where we need a new command line option that is mutually exclusive with --test (or an option to put on --test to control which test mode is used, such as --test=remote); or we could add a new setting that overrides how a test entry point is interpreted. Looking at examples like cibuildwheel could be instructive here; we need to be able to define a test entry point that is effectively "a testing command line", rather than a test module (and do so in a way that provides a backwards compatible path for existing users).

This might seem completely tangential to the problem you describe - and you're not wrong. The only reason I raise it is that if we're changing how we discover test configurations, we want to make sure we don't lock ourselves out of introducing other test invocation mechanisms.

[timrid]

Wow, that was a much more detailed answer than I expected. I can understand the points you raised, but it sounds like much more complex changes than I had imagined. However, my current focus is on getting BLE up and running on Android and iOS with briefcase.

This might seem completely tangential to the problem you describe - and you're not wrong. The only reason I raise it is that if we're changing how we discover test configurations, we want to make sure we don't lock ourselves out of introducing other test invocation mechanisms.

That means if I work out a PR for the configuration option of test_main_package as an intermediate step, that would also be an acceptable solution, as long as it does not complicate the significantly more extensive redesign you described?

[mhsmith]

So - a definition might look something like:

That looks reasonable to me, except I'd rename entry_point to script to match the wording used elsewhere in the file.

I've also made some minor edits to your comment to match my understanding of the spec: please check you agree.

existing projects won't have the refactoring that would make entry points work - so do we assume if you don't define an entry point, you want old-style module-based startup (and presumably raise a warning)?

I think that's fine, and maybe there's not even any need for a warning.

We could even stretch the definition a little and say that if you don't have a colon in an entry point, we'll interpret that as Briefcase's "start module" behavior. That would be helpful for backwards compatibility, but I don't know if we want to start pushing on the boundaries of the formal specification like that.

I agree. There's no need for the developer of a pre-existing app to use this setting unless they want to customize the entry point, and if they do then they can just use the standard syntax.

I could, of course, simply move the file examples/briefcase/tests_startup/bleak_example.py to tests/bleak_example.py and remove the tests_startup folder entirely, but I don't want to modify the existing tests folder at all.

What if you rename tests_startup to tests? Will Briefcase merge the two tests directories together? If so, there would be no need to modify the existing folder, nor to add a new configuration option.

[timrid]

I could, of course, simply move the file examples/briefcase/tests_startup/bleak_example.py to tests/bleak_example.py and remove the tests_startup folder entirely, but I don't want to modify the existing tests folder at all.

What if you rename tests_startup to tests? Will Briefcase merge the two tests directories together? If so, there would be no need need to modify the existing folder, nor to add a new configuration option.

No, unfortunately the folders are not merged.

This exception is thrown:

[bleak_example] Updating application code...
Installing src/bleak_example... done
Installing ../../bleak... done
Installing tests... done
Installing ../../tests... errored

Log saved to /Users/timrid/Documents/bleak/examples/briefcase/logs/briefcase.2026_01_20-21_21_20.run.log

Traceback (most recent call last):
  File "/Users/timrid/Documents/bleak/.venv/bin/briefcase", line 7, in <module>
    sys.exit(main())
             ~~~~^^
  File "/Users/timrid/Documents/briefcase/src/briefcase/__main__.py", line 27, in main
    command(**options)
    ~~~~~~~^^^^^^^^^^^
  File "/Users/timrid/Documents/briefcase/src/briefcase/commands/run.py", line 388, in __call__
    state = self.build_command(
        app,
    ...<6 lines>...
        **options,
    )
  File "/Users/timrid/Documents/briefcase/src/briefcase/commands/build.py", line 159, in __call__
    state = self._build_app(
        app_obj,
    ...<6 lines>...
        **full_options(state, options),
    )
  File "/Users/timrid/Documents/briefcase/src/briefcase/commands/build.py", line 79, in _build_app
    state = self.update_command(
        app,
    ...<4 lines>...
        **options,
    )
  File "/Users/timrid/Documents/briefcase/src/briefcase/commands/update.py", line 127, in __call__
    state = self.update_app(
        app_obj,
    ...<4 lines>...
        **full_options(state, options),
    )
  File "/Users/timrid/Documents/briefcase/src/briefcase/commands/update.py", line 64, in update_app
    self.install_app_code(app=app)
    ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/Users/timrid/Documents/briefcase/src/briefcase/commands/create.py", line 751, in install_app_code
    self.tools.shutil.copytree(original, target)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/shutil.py", line 593, in copytree
    return _copytree(entries=entries, src=src, dst=dst, symlinks=symlinks,
                     ignore=ignore, copy_function=copy_function,
                     ignore_dangling_symlinks=ignore_dangling_symlinks,
                     dirs_exist_ok=dirs_exist_ok)
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/shutil.py", line 491, in _copytree
    os.makedirs(dst, exist_ok=dirs_exist_ok)
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen os>", line 228, in makedirs
FileExistsError: [Errno 17] File exists: '/Users/timrid/Documents/bleak/examples/briefcase/build/bleak_example/android/gradle/app/src/main/python/tests'
```
</details>

[freakboy3742]

So - a definition might look something like:

That looks reasonable to me, except I'd rename entry_point to script to match the wording used elsewhere in the file.

I guess that's fair. They're collectively referred to as "Entry Points" in documentation, but there is a [project.entry-points] table that is more

My only real hesitation is that you don't really think of "the icon on your desktop" as a "script"... but I guess it's not wrong as a term, and it's a setting that most won't need to use (or customise).

I've also made some minor edits to your comment to match my understanding of the spec: please check you agree.

Those all looks like typos on my part - thanks for the fixes.

existing projects won't have the refactoring that would make entry points work - so do we assume if you don't define an entry point, you want old-style module-based startup (and presumably raise a warning)?

I think that's fine, and maybe there's not even any need for a warning.

The reason I think a warning is that we won't ever be able to deprecate "old style" module execution if we don't warn people - so we'll have to continue to maintain "start module" and "start method" as two branches of app startup. I guess that's not too much of a problem; I'd just prefer to not have to maintain legacy interfaces until the end of time.

[freakboy3742]

That means if I work out a PR for the configuration option of test_main_package as an intermediate step, that would also be an acceptable solution, as long as it does not complicate the significantly more extensive redesign you described?

If it can be done in a minimal change without introducing complications for future support, then sure.

What if you rename tests_startup to tests? Will Briefcase merge the two tests directories together? If so, there would be no need need to modify the existing folder, nor to add a new configuration option.

No, unfortunately the folders are not merged.

Honestly, I'd be a lot more comfortable with treating this as the underlying bug. I can think of plenty of cases where "provide platform-specific logic as an overlay to existing code" would be useful behavior. It should be a relatively straightforward fix, too - shutil.copytree has a dirs_exist_ok option. If I'm understanding this correctly, that would solve your use case, and let you use a more intuitive "tests" folder name for the project test folder.

[timrid]

What if you rename tests_startup to tests? Will Briefcase merge the two tests directories together? If so, there would be no need need to modify the existing folder, nor to add a new configuration option.

No, unfortunately the folders are not merged.

Honestly, I'd be a lot more comfortable with treating this as the underlying bug. I can think of plenty of cases where "provide platform-specific logic as an overlay to existing code" would be useful behavior. It should be a relatively straightforward fix, too - shutil.copytree has a dirs_exist_ok option. If I'm understanding this correctly, that would solve your use case, and let you use a more intuitive "tests" folder name for the project test folder.

Yes, that actually solves my problem too. I created #2636 for this purpose.