Add module-specific assertions (Doctrine, Environment, Security, Session)

[TavoNiievez]

What

Adds high-level, actor-style assertions that rely on Symfony kernel/container integration and have no pure-Symfony equivalent. These belong to the see* / dontSee* family of the naming convention documented in CONTRIBUTING.md (also extended here).

Methods

• DoctrineAssertionsTrait: seeDoctrineDatabaseIsUp, seeDoctrineSchemaIsValid, seeDoctrineProxyDirIsWritable
• EnvironmentAssertionsTrait (new trait): seeKernelEnvironmentIs, seeDebugModeEnabled, dontSeeDebugModeEnabled, seeSymfonyVersion, seeAppEnvAndDebugMatchKernel, seeAppCacheIsWritable, seeAppLogIsWritable, seeProjectStructureIsSane, seeEnvFileIsSynchronized, seeBundleIsEnabled, seeAssetManifestExists, seeKernelCharsetIs
• SecurityAssertionsTrait: seeFirewallIsConfigured, seeRoleInHierarchy, seeSecretCanBeResolved
• SessionAssertionsTrait: seeSessionSavePathIsWritable

Registers EnvironmentAssertionsTrait on the Symfony module facade and documents the see* / assert* naming convention in CONTRIBUTING.md.

Tests

Unit tests added for the methods exercisable against the test app (tests/_app): Doctrine checks, the firewall check, Symfony-version/env-debug/project-dir environment checks.

The remaining checks require a full real Symfony project layout that the mini unit-test app does not provide (seeProjectStructureIsSane, seeAssetManifestExists, seeEnvFileIsSynchronized, seeSecretCanBeResolved); per the two-test-layer setup these are best covered in the companion Codeception/symfony-module-tests functional suite.

Notes

Companion to #240, which contains the Symfony-mirroring assert* / get* assertions. The two PRs touch disjoint files and can be reviewed/merged independently.

[TavoNiievez]

Hi @ThomasLandauer @xEdelweiss ,
I'm proposing adding some new assertions to the module.

Can you take a look at the PR and give me your opinion on the new methods, please?

[ThomasLandauer]

Do you mean the name of the entity manager (in case you have multiple)?

[TavoNiievez]

Good point — in Doctrine these are two separate registries. The method now resolves the argument as a connection name first and, if none matches, falls back to treating it as an entity manager name and uses that manager's connection (see resolveDoctrineConnection()). I've updated the @param to spell this out, so both forms work.

[ThomasLandauer]

Are you aware that Doctrine is moving away from their own proxy system, in favor of the new native PHP lazy objects? So (as far as I understand it), the proxy dir soon won't be needed anymore.

[TavoNiievez]

Yes — with native PHP lazy objects there's no proxy dir, so the method now markTestSkipped()s when none is configured (the docblock notes this). It stays useful for apps still on the legacy proxy system, which is common on the Symfony 5.4 / 6.4 versions this module still supports. Happy to drop it entirely once those leave the support matrix.

[ThomasLandauer]

Does this also work with one and three digit versions?

[TavoNiievez]

Yes — it delegates to PHP's version_compare, which accepts one-, two- and three-segment versions (7, 7.4, 7.4.8). That's now stated in the docblock and covered by a unit test (testSeeSymfonyVersionAcceptsOneTwoAndThreeSegments) exercising all three forms.

[ThomasLandauer]

1. How is it possible that they don't mach?
2. Are you only looking at real environment variables or also at resolved .env variables?

[TavoNiievez]

1. They can diverge when the runtime env var and the booted Kernel disagree — e.g. a shell or CI job exporting APP_ENV=dev while the test Kernel boots in test. This assertion is a guard against that drift (and only checks a variable when it's actually present). I've added this rationale to the docblock.
2. Both. Values are now resolved $_SERVER → $_ENV → getenv(), so it covers real OS variables and the values Symfony's Dotenv writes from .env* files.

[ThomasLandauer]

I usually do it like this:

$kernel = $I->grabService('kernel');
$kernel->getContainer()->getParameter('foobar');

Is this just a shortcut? I'm asking cause if there's a shortcut for this one parameter, I always ask myself: What about all the others?

[TavoNiievez]

Agreed — a bespoke shortcut per parameter wouldn't scale. There's a generic grabParameter('any.parameter.name') in ParameterAssertionsTrait for exactly that. getProjectDir() here is only a protected internal helper shared by the other assertions in this trait, not a public per-parameter accessor.

[ThomasLandauer]

"Active" in the sense that it was actually used for the current request? Or just generally up and running?

[TavoNiievez]

The latter — "configured", not "matched the current request". I renamed it seeFirewallIsActive → seeFirewallIsConfigured, and the docblock now states it only checks that the firewall definition (or its context service) exists, not whether it matched the request.

[ThomasLandauer]

Well, these are many... :-)

1. Do you have a clear picture when Codeception usually uses see vs. assert? Or at least clearer than me? ;-)
2. Is there a reason why you're putting those Doctrine assertions in the Symfony and not in the Doctrine module?
3. For some assertions I don't get the idea, since the outcome usually differs between TEST and PROD environment, e.g. seeDoctrineDatabaseIsUp(), seeDebugModeEnabled(). What's your reasoning here?

[xEdelweiss]

Hi @TavoNiievez
Thanks for looping me in! Sadly, I'm not really working with Codeception/Symfony at the moment, so I don't think I can give this PR the proper attention it deserves.

[TavoNiievez]

Thanks for the thorough review, @ThomasLandauer! Answers to your three higher-level questions:

1. see vs assert — fair point. The module is uniformly see* / dontSee* / grab*, so I aligned the two outliers I'd introduced: assertSymfonyVersion → seeSymfonyVersion and assertEnvFileIsSynchronized → seeEnvFileIsSynchronized. Everything new now follows the see* convention.

2. Doctrine assertions in the Symfony module — this module already ships a DoctrineAssertionsTrait (grabRepository, seeNumRecords, grabNumRecords, …), since Symfony + Doctrine is the default stack and there's no hard dependency forcing module-doctrine. The new assertions just extend that existing trait rather than create a new home for them.

3. Outcome differs between TEST and PROD — these assert the expected state for whatever environment the suite targets, instead of a fixed value. That's why both polarities exist (seeDebugModeEnabled / dontSeeDebugModeEnabled): you call the one that matches the environment under test. seeDoctrineDatabaseIsUp() is a connectivity smoke-check that's meaningful in any environment where the DB is expected to be reachable.

I've pushed a commit addressing the inline comments (naming + docblock clarifications) and replied in each thread.