Cmake package configuration script tests
------

How to run tests
================

Tests are located in the `testing/find_package` folder of the source tree.
First they need to be configured using `cmake`.

If testing OS-wide connector installation (from RPM, DEB or MSI package)
it is enough to run `cmake` in a build location pointing at the folder with
tests:

 > cmake ${SRC_DIR}/testing/find_package

If connector was installed from TGZ or ZIP package to a custom location then
this location needs to be given as `WITH_CONCPP` parameter (otherwise
configuration fails with error):

 > cmake -D WITH_CONCPP=${INSTALL_DIR} ...

This should configure various tests which can be run using `ctest` command
(`ctest -N` will list configured tests).

Note: No build step is required before running tests.

Note: When invoking `ctest` on Windows (using the default generator) one needs
to invoke it as `ctest -C Release` -- this is a technical limitation of cmake/
ctest.


Some packages distribute only shared connector libraries (generic Linux
for example). When testing such package the static library tests should
be disabled using `BUILD_STATIC` option:

 > cmake -D BUILD_STATIC=0 ...


If `WITH_SSL` configuration option is passed that points to location where
OpenSSL is installed additional test scenarios are configured which check
use of the connector with the external OpenSSL installation (*):

 > cmake -D WITH_SSL=${OPENSSL_DIR} ...

Note (*): Without this option either bundled or OS-wide OpenSSL is used
in tests depending on the type of the connector installation being tested.


Package version test scenarios must know which version of connector package
is being tested. They get this information from `INFO_SRC` file which
is included in the package. If the file is not found for some reason
the version test scenarios are not configured (with warning). They can
be still generated by providing package version as `VERSION`
parameter:

 > cmake -D VERSION=8.2.0 ...


By default both XDevAPI and JDBC variants of the connector are tested.
The JDBC tests can be excluded by disabling `WITH_JDBC` option when
configuring tests:

 > cmake -D WITH_JDBC=OFF ...


On Windows debug packages contain debug builds of connector libraries. To test
them enable `WITH_DEBUG` option:

 > cmake -D WITH_DEBUG=ON ...

This should be done only if debug packages are installed.


Test scenarios
==============

Main test scenarios are checked by tests with names:
```
  ${ACTION}_A${A}_B${B}_C${C}
```
where ${ACTION} is one of:

- config  -- configure project that builds test applications (*)
- build   -- build test application
- check   -- check resulting executable for unresolved dependencies

Note (*): The project lives at testapp/ folder in the source directory
and defines simple test applications that uses different variants of
the connector (XDevAPI, XAPI, JDBC). In the project connector package
is loaded using find_package() command.

Parameters ${A}, ${B} and ${C} describe the exact scenario being checked
as follows:

- A  -- type of connector library used: "dynamic" or "static"
- B  -- build configuration: "Release" or "Debug"
- C  -- how OpenSSL dependency is resolved: "default" or "custom"

In case of C="custom" scenarios the OpenSSL installed at location given
by `WITH_SSL` parameter is used. Otherwise the default behavior of using
either bundled or system-wide OpenSSL installation is tested.


Additional version tests verify correct behavior of the script that reports
available package version. They have names
```
  version_A${A}_B${B}
```
where ${A} and ${B} determine test scenario as follows:

- A  -- what version of the package is requested in find_package() invocation;
        one of: "exect", "older", "newer", "different"

- B  -- whether exact version is requested: "yes", "no".

The "older" and "newer" versions are versions that difer by mnior number.
The "different" version is a version with different major version number.

These tests also check that expected variables are set after successful
loading of the package.


The `debug_require` test checks situation when the "debug" component
is requested when loading package, as in:
```
  find_package(mysql-concpp REQUIRE debug)
```
This is expected to fail unless testing on Windows with debug package
installed and WITH_DEBUG option enabled during test configuration.


Copyright notice
----------------
Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2.0, as
published by the Free Software Foundation.

This program is also distributed with certain software (including
but not limited to OpenSSL) that is licensed under separate terms,
as designated in a particular file or component or in included license
documentation.  The authors of MySQL hereby grant you an
additional permission to link the program and your derivative works
with the separately licensed software that they have included with
MySQL.

Without limiting anything contained in the foregoing, this file,
which is part of MySQL Connector/C++, is also subject to the
Universal FOSS Exception, version 1.0, a copy of which can be found at
http://oss.oracle.com/licenses/universal-foss-exception.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License, version 2.0, for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA