pytest-invenio 4.0.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,500 @@
1
+ # SPDX-FileCopyrightText: 2017-2025 CERN.
2
+ # SPDX-FileCopyrightText: 2024-2026 Graz University of Technology.
3
+ # SPDX-FileCopyrightText: 2026 TU Wien.
4
+ # SPDX-License-Identifier: MIT
5
+
6
+ """Pytest fixtures for Invenio.
7
+
8
+ .. _quick-start:
9
+
10
+ Quick start
11
+ -----------
12
+ 1. Define a module-scoped fixture named ``create_app`` that returns an
13
+ application factory for your Invenio installation. If you are using
14
+ Invenio-App, it's as simple as:
15
+
16
+ .. code-block:: python
17
+
18
+ # conftest.py
19
+ from invenio_app.factory import create_ui
20
+
21
+ @pytest.fixture(scope='module')
22
+ def create_app():
23
+ return create_ui
24
+
25
+
26
+ 2. Write tests:
27
+
28
+ .. code-block:: python
29
+
30
+ # test_something.py
31
+
32
+ def test_e2e(live_server, browser):
33
+ browser.get(url_for('index', _external=True))
34
+
35
+ def test_testclient(client):
36
+ res = client.get('/api/')
37
+ res.json == {'test-client': 'with-json-decoder'}
38
+
39
+ def test_db(base_app, db):
40
+ # Database with rollback
41
+
42
+ def test_cli(cli_runner):
43
+ result = cli_runner(mycmd)
44
+ assert result.exit_code == 0
45
+
46
+ def test_mailbox(appctx, mailbox):
47
+ # ...
48
+ assert len(mailbox) == 1
49
+
50
+ Running tests
51
+ -------------
52
+ Running tests with py.test is pretty simple. Your package might support the
53
+ standard way of running tests:
54
+
55
+ .. code-block:: console
56
+
57
+ $ python setup.py test
58
+
59
+ Alternatively you can use the ``pytest`` command to run all or specific test
60
+ cases:
61
+
62
+ .. code-block:: console
63
+
64
+ $ pytest
65
+ $ pytest tests/test_something.py
66
+ $ pytest tests/test_something.py::test_acase
67
+
68
+ Fixtures
69
+ --------
70
+ All available fixtures are documented in the API documentation
71
+ (see :ref:`fixtures`).
72
+
73
+ In addition to the ones provided by pytest-invenio, there are further fixtures
74
+ defined pytest-flask (see
75
+ `documentation <http://pytest-flask.readthedocs.io/en/latest/>`_ for details).
76
+
77
+ Structuring tests
78
+ -----------------
79
+ The pytest fixtures in pytest-invenio all work on *one* Flask application,
80
+ however most Invenio instances usually consits of *two* Flask applications:
81
+ UI and API. Thus, to use the pytest-invenio fixtures it's important to
82
+ understand how to structure your tests, and know exactly which application you
83
+ are dealing with.
84
+
85
+ Scope
86
+ ~~~~~
87
+ Most of pytest-invenio fixtures are either *module* scoped or *function*
88
+ scoped.
89
+
90
+ * *Module* scoped fixtures are created/destroyed once per Python test file.
91
+ * *Function* scoped fixtures are created/destroyed per test.
92
+
93
+ The fixtures which creates the database and applications are module scoped,
94
+ hence, all tests in a Python file run against either the UI or the API
95
+ application, but not both.
96
+
97
+ .. note::
98
+
99
+ All tests in a single file, run against the one and only one application
100
+ (e.g. UI or REST).
101
+
102
+ Thus, in a single test file you cannot mix both UI and API tests, which is
103
+ normally not an issue.
104
+
105
+ Overriding fixtures
106
+ ~~~~~~~~~~~~~~~~~~~
107
+ Pytest provides rich support for overriding fixtures at various level and
108
+ combined with module/function-scoped we can easily override fixtures. Also,
109
+ you can use ``conftest.py`` to define per-directory fixtures.
110
+
111
+ Following is an example of how fixtures overriding works:
112
+
113
+ .. code-block:: python
114
+
115
+ # conftest.py:
116
+ @pytest.fixture()
117
+ def myfix():
118
+ return 'root'
119
+
120
+ # test_root.py
121
+ def test_a(myfix):
122
+ print(myfix)
123
+ # will output "root"
124
+
125
+ # a/conftest.py
126
+ @pytest.fixture()
127
+ def myfix(myfix):
128
+ return myfix + '-a'
129
+
130
+ # a/test_subdir.py
131
+ def test_a(myfix):
132
+ print(myfix)
133
+ # will output "root-a"
134
+
135
+ Notice that:
136
+
137
+ * **Overriding:** In ``a/test_subdir.py`` the fixture ``myfix`` is coming from
138
+ ``a/conftest.py`` which is overriding the fixture from ``conftest.py``. In
139
+ ``test_root.py`` it's however the ``myfix`` fixture from ``conftest.py``
140
+ being used.
141
+ * **Parent fixture:** In ``a/conftest.py``, the fixture ``myfix`` has access to
142
+ the parent fixture from ``conftest.py``.
143
+
144
+ Recommend layout
145
+ ~~~~~~~~~~~~~~~~
146
+ If you are using Invenio-App (recommended), then the following layout is
147
+ recommended:
148
+
149
+ .. code-block:: python
150
+
151
+ # ### tests/conftest.py ###
152
+ # Common application configuration goes here
153
+ @pytest.fixture(scope='module')
154
+ def app_config(app_config):
155
+ app_config['MYCONF'] = True
156
+ return app_config
157
+
158
+ # ### tests/ui/conftest.py ###
159
+ # UI tests goes in tests/ui/ folder.
160
+ from invenio_app.factory import create_ui
161
+
162
+ @pytest.fixture(scope='module')
163
+ def create_app():
164
+ return create_ui
165
+
166
+ # ### tests/api/confest.py ###
167
+ # API tests goes in tests/api/ folder.
168
+ from invenio_app.factory import create_api
169
+
170
+ @pytest.fixture(scope='module')
171
+ def create_app():
172
+ return create_api
173
+
174
+ # ### tests/e2e/conftest.py ###
175
+ # E2E tests (requring both UI/API) goes in tests/e2e/ folder.
176
+ from invenio_app.factory import create_app as create_ui_api
177
+
178
+ @pytest.fixture(scope='module')
179
+ def create_app():
180
+ return create_ui_api
181
+
182
+ Using above layout you essentially split your tests into three folders::
183
+
184
+ tests/ui/
185
+ tests/api/
186
+ tests/e2e/
187
+
188
+ Each subfolder holds tests related to a specific application (UI or API).
189
+ The ``e2e`` folder holds tests that need both UI and API application (which
190
+ is typically the case for end-to-end tests). The E2E tests works by creating
191
+ both the UI and API applications and using a special WSGI middleware to
192
+ dispatch requests between both applications. Having two applications at the
193
+ same time, can however cause quite a lot of confusion so it is only recommended
194
+ for E2E tests.
195
+
196
+ Note, also in above example how all three applications are sharing the same
197
+ :py:data:`~fixtures.app_config` fixture.
198
+
199
+ .. note::
200
+
201
+ You shouldn't feel bound to above structure. If you site grows large,
202
+ you'll likely split tests into further subfolders. The important message
203
+ from the recommended layout, is that you need **one folder per
204
+ application**.
205
+
206
+ Application fixtures
207
+ --------------------
208
+ The package provides three different application fixtures:
209
+
210
+ * :py:data:`~fixtures.base_app`: Basic application fixture which creates the
211
+ Flask application.
212
+ * :py:data:`~fixtures.appctx`: Same as the basic application fixture, but
213
+ pushes an application context onto the stack (i.e. makes ``current_app``
214
+ work).
215
+ * :py:data:`~fixtures.app`: Same as the basic application, but in addition it
216
+ initializes the database and search indices.
217
+
218
+ All three fixtures depend on the same user-provided (i.e. you must define it)
219
+ fixture named ``create_app`` which must return an application factory (see
220
+ :ref:`quick-start`).
221
+
222
+ Customizing configuration
223
+ ~~~~~~~~~~~~~~~~~~~~~~~~~
224
+ The application fixtures rely on fixtures such as
225
+ :py:data:`~fixtures.instance_path`, :py:data:`~fixtures.app_config`,
226
+ :py:data:`~fixtures.celery_config_ext`, :py:data:`~fixtures.db_uri`,
227
+ :py:data:`~fixtures.broker_uri` to inject configuration into the
228
+ application.
229
+
230
+ You can overwrite each of these fixtures at many different levels:
231
+
232
+ * **Global**: Override one or more of these fixtures in your global
233
+ ``conftest.py`` to inject the same configuration in all applications.
234
+ * **Per-directory**: Override fixtures for a specific subdirectory by putting a
235
+ ``conftest.py`` in the directory.
236
+ * **Per-file**: Fixtures can also be overwritten in specific modules. For
237
+ instance you may want to customize the celery configuration only for a
238
+ specific Python test file.
239
+
240
+ Injecting entry points
241
+ ~~~~~~~~~~~~~~~~~~~~~~
242
+ Invenio relies heavily upon entry points for constructing a Flask application,
243
+ and it can be rather cumbersome to try to manually register database models,
244
+ mappings and other features afterwards.
245
+
246
+ You can therefore inject extra entry points if needed during testing via the
247
+ :py:data:`~fixtures.extra_entry_points` fixture and use it in your custom
248
+ ``create_app()`` fixture:
249
+
250
+ .. code-block:: python
251
+
252
+ @pytest.fixture(scope="module")
253
+ def extra_entry_points():
254
+ return {
255
+ 'invenio_db.models': [
256
+ 'mock_module = mock_module.models',
257
+ ]
258
+ }
259
+
260
+ @pytest.fixture(scope="module")
261
+ def create_app(entry_points):
262
+ return _create_api
263
+
264
+ Note that ``create_app()`` depends on the :py:data:`~fixtures.entry_points`
265
+ fixture not the ``extra_entry_points()``.
266
+
267
+ .. _views-testing:
268
+
269
+ Views testing
270
+ -------------
271
+ Views can easily be testing using the Flask test clients. Two test clients are
272
+ provided for convenience: ``base_client`` and ``client``. The only difference
273
+ is which application fixture they depend on:
274
+
275
+ .. code-block:: python
276
+
277
+ def test_view1(base_client):
278
+ # Depends on 'base_app' fixture
279
+ base_client.get(url_for(..))
280
+
281
+ def test_view2(client):
282
+ # Depends on 'app' fixture
283
+ client.get(url_for(..))
284
+
285
+ JSON responses
286
+ ~~~~~~~~~~~~~~
287
+ The default Flask test client does not have built-in support for decoding JSON
288
+ responses, which can make API testing a bit cumbersome. The test clients
289
+ are therefore patched to add a JSON property:
290
+
291
+ .. code-block:: python
292
+
293
+ def test_api(base_client):
294
+ res = base_client.get(...)
295
+ assert res.json == { ... }
296
+
297
+ Database re-use
298
+ ---------------
299
+ The default database is an SQLite database located in the application's
300
+ instance folder. This can easily be overwritten by setting the environment
301
+ variable ``SQLALCHEMY_DATABASE_URI`` (useful e.g. in CI systems to test
302
+ multiple databases).
303
+
304
+ Tests that make changes to the database should explicitly use the function
305
+ scoped :py:data:`~fixtures.db` fixture. This fixture wraps the changes in
306
+ a transaction and rollback any changes by the end of the test. For instance:
307
+
308
+ .. code-block:: python
309
+
310
+ def test_db1(db):
311
+ db.session.add(User(username='alice'))
312
+ db.session.commit()
313
+ assert User.query.count() == 1 # i.e. independent of test_db2
314
+
315
+ def test_db2(db):
316
+ db.session.add(User(username='bob'))
317
+ db.session.commit()
318
+ assert User.query.count() == 1 # i.e. independent of test_db1
319
+
320
+
321
+ .. note::
322
+
323
+ Take care! The :py:data:`~fixtures.db` fixture does not rollback other
324
+ changes. If data, in addition to being added to the database, is also
325
+ indexed in the search cluster then you should clear the index explicitly using
326
+ e.g. :py:data:`~fixtures.search_clear`.
327
+
328
+ Performance considerations
329
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
330
+ The database is recreated (all tables dropped and recreated) for each test
331
+ file, because the database is a module scoped fixture. This adds a performance
332
+ overhead, thus be careful not to indirectly depend on the database fixtures in
333
+ a file unless it is really necessary (e.g. via the :py:data:`~fixtures.app`
334
+ fixture).
335
+
336
+ Search testing
337
+ ---------------------
338
+ Pytest-Invenio depends on Invenio-Search and any mappings registered on
339
+ Invenio-Search will be created if you depend on the :py:data:`~fixtures.search`
340
+ fixture. The fixture is module scoped, meaning that any fixture you write to
341
+ e.g. load test data should likely also be module scoped.
342
+
343
+ Clearing changes
344
+ ~~~~~~~~~~~~~~~~
345
+ Unlike the database fixture, which automatically rollback changes, you must
346
+ explicitly depend on the :py:data:`~fixtures.search_clear` fixture if you makes
347
+ changes to the indexes. This ensures that you leave the indexes in a clean
348
+ state for the next test. The :py:data:`~fixtures.search_clear` fixture will however
349
+ delete and recreate the indexes, and thus comes with a performance penalty if
350
+ used.
351
+
352
+ .. code-block:: python
353
+
354
+ def test_search1(search_clear):
355
+ # ...
356
+
357
+ Performance considerations
358
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
359
+ As for the database fixtures, search indices are deleted and recreated
360
+ for each test file (due to module scoped fixture). Thus be careful not to
361
+ indirectly depend on the database fixtures in a file unless it is really
362
+ necessary (e.g. via the :py:data:`~fixtures.app` fixture).
363
+
364
+ CLI testing
365
+ -----------
366
+ Pytest-Invenio provides two quick short cuts for easier testing Click-based
367
+ commands that require an application context (i.e. most commands).
368
+
369
+ The shortest version is to use the :py:data:`~fixtures.cli_runner` fixture:
370
+
371
+ .. code-block:: python
372
+
373
+ def test_cmd(cli_runner):
374
+ result = cli_runner(mycmd)
375
+ assert result.exit_code == 0
376
+
377
+ The downside is that the Click CLIRunner is recreated for each call. This is
378
+ not necessary, so an alternative is to use the :py:data:`~fixtures.script_info`
379
+ fixture, which however is more verbose:
380
+
381
+ .. code-block:: python
382
+
383
+ def test_cmd(script_info):
384
+ runner = CliRunner()
385
+ result = runner.invoke(mycmd, obj=script_info)
386
+ assert result.exit_code == 0
387
+
388
+ Mail testing
389
+ ------------
390
+ If you have Invenio-Mail installed on your application, you can use the
391
+ :py:data:`~fixtures.mailbox` fixture to test email sending. Any message sent
392
+ by the application during the test will be captured and is inspectable in via
393
+ the fixture:
394
+
395
+ .. code-block:: python
396
+
397
+ def test_mailbox(appctx, mailbox):
398
+ assert len(mailbox) == 0
399
+ appctx.extensions['mail'].send_message(
400
+ sender='no-reply@localhost',
401
+ subject='testing',
402
+ body='test',
403
+ recipients=['no-reply@localhost'],)
404
+ assert len(mailbox) == 1
405
+
406
+
407
+ End-to-end testing
408
+ ------------------
409
+ In addition to using the Flask test client for testing views (see
410
+ :ref:`views-testing`), you can use a real browser via the Selenium integration
411
+ for fully end-to-end testing. The tests works by starting the Flask application
412
+ in a separate process, and using Selenium to drive your favorite browser.
413
+ Writing the tests are very easy, simply depend on the ``live_server`` fixture
414
+ (defined by pytest-flask) and the :py:data:`~fixtures.browser` fixture:
415
+
416
+ .. code-block:: python
417
+
418
+ def test_browser(live_server, browser):
419
+ # Note the use of '_external=True'
420
+ browser.get(url_for('index', _external=True))
421
+
422
+ Running E2E tests
423
+ ~~~~~~~~~~~~~~~~~
424
+ By default, tests using the :py:data:`~fixtures.browser` fixture are skipped.
425
+ In order to run these tests, you must set an environment variable:
426
+
427
+ .. code-block:: console
428
+
429
+ $ export E2E=yes
430
+
431
+ Also, by default Chrome is used. If you'd like to use Firefox, Safari or
432
+ another browser you must set another environment variable:
433
+
434
+ .. code-block:: console
435
+
436
+ $ export E2E_WEBDRIVER_BROWSERS="Firefox"
437
+
438
+ .. note::
439
+
440
+ You must have Selenium Client and the Chrome Webdriver installed on your
441
+ system in order to run the E2E tests.
442
+
443
+
444
+ Screenshots
445
+ ~~~~~~~~~~~
446
+ The :py:data:`~fixtures.browser` fixture will take a screenshot of in case of
447
+ test failures and store it in a folder ``.e2e_screenshots``. On CI systems you
448
+ can also have screenshot printed to the console by setting an environment
449
+ variable:
450
+
451
+ .. code-block:: console
452
+
453
+ $ export E2E_OUTPUT=base64
454
+
455
+ TravisCI integration
456
+ ~~~~~~~~~~~~~~~~~~~~
457
+ Following is an example of the needed changes (at time of writing) to your
458
+ ``.travis.yml`` in case want to run E2E tests on Travis. Travis is likely
459
+ to evolve, so please refer to the Travis CI documentation for the latest
460
+ information.
461
+
462
+ .. code-block:: yaml
463
+
464
+ # Install Chrome
465
+ # - see https://docs.travis-ci.com/user/chrome
466
+ addons:
467
+ chrome: stable
468
+
469
+ # Chrome driver fails if not trusty dist
470
+ dist: trusty
471
+
472
+ # Selenium webdriver for Chrome fails if not on sudo
473
+ # - see https://github.com/travis-ci/travis-ci/issues/8836
474
+ sudo: true
475
+
476
+ # Define environment variables to enable E2E tests and outputing
477
+ # screenshots to the console.
478
+ env:
479
+ global:
480
+ # Print screenshots to console output
481
+ - E2E_OUTPUT=base64
482
+ # Enable end-to-end tests
483
+ - E2E=yes
484
+
485
+ # Install Chrome webdriver for Selenium
486
+ before_install:
487
+ - "PATH=$PATH:$HOME/webdrivers"
488
+ - "if [ ! -f $HOME/webdrivers/chromedriver ]; then wget https://chromedriver.storage.googleapis.com/2.31/chromedriver_linux64.zip -P $HOME/webdrivers; unzip -d $HOME/webdrivers $HOME/webdrivers/chromedriver_linux64.zip; fi" # noqa
489
+
490
+ # Start a virtual display
491
+ # - https://docs.travis-ci.com/user/gui-and-headless-browsers/
492
+ before_script:
493
+ - "export DISPLAY=:99.0"
494
+ - "sh -e /etc/init.d/xvfb start"
495
+ - sleep 3 # give xvfb some time to start
496
+ """
497
+
498
+ __version__ = "4.0.2"
499
+
500
+ __all__ = ("__version__",)