経緯と概要

CakePHP3において、複数DBにまたがってデータ参照をする場合の設定方法を記します。
特に、テストのときに狙ったtest用DBを向かなくてはまりました。
2016/11/8現在, わかりやすい位置に本エントリに該当する説明がなかったので何かの助けになればと思います。

configの設定

例えばdefaultでとあるDB「hoge」, 別でDB「fuga」を参照したい場合
http://book.cakephp.org/3.0/ja/development/testing.html#id13
公式のこの辺りを参照してconfigに記述します。

config/app.php

(中略)
'Datasources' => [
    /* デフォルト設定 */
    'default' => [
        'className' => 'Cake\Database\Connection'
        'driver' => 'Cake\Database\Driver\Mysql',
        'persistent' => false,
        'host' => XXX.XXX.XXX.XXX,
        //'port' => 'non_standard_port_number',
        'username' => 'username',
        'password' => 'passwd',
        'database' => 'hoge',
        'encoding' => 'utf8mb4',
        'timezone' => 'Asia/Tokyo',
        'flags' => [],
        'cacheMetadata' => true,
        'log' => false,
　　　　　　　　　　　　　　　　'url' => env('DATABASE_TEST_URL', null),
　　　　　　　],
    /* fuga */
   'fuga' => [
       'className' => 'Cake\Database\Connection',
       'driver' => 'Cake\Database\Driver\Mysql',
       'persistent' => false,
       'host' => XXX.XXX.XXX.XXX,
       'username' => 'username',
       'password' => 'passwd',
       'database' => 'fuga',
       'encoding' => 'utf8mb4',
       'timezone' => 'Asia/Tokyo',
       'cacheMetadata' => true,
       'quoteIdentifiers' => false,
       'log' => false,
       'url' => env('DATABASE_TEST_URL', null),
   ],
   /* defaultのテスト */
   'test' => [
        'className' => 'Cake\Database\Connection'
        'driver' => 'Cake\Database\Driver\Mysql',
        'persistent' => false,
        'host' => XXX.XXX.XXX.XXX,
        //'port' => 'non_standard_port_number',
        'username' => 'username',
        'password' => 'passwd',
        'database' => 'test',
        'encoding' => 'utf8mb4',
        'timezone' => 'Asia/Tokyo',
        'flags' => [],
        'cacheMetadata' => true,
        'log' => false,
　　　　　　　　　　　　　　　　'url' => env('DATABASE_TEST_URL', null),
　　　　　　　],
    /* fugaのテスト */
   'test_fuga' => [
       'className' => 'Cake\Database\Connection',
       'driver' => 'Cake\Database\Driver\Mysql',
       'persistent' => false,
       'host' => XXX.XXX.XXX.XXX,
       'username' => 'username',
       'password' => 'passwd',
       'database' => 'test',
       'encoding' => 'utf8mb4',
       'timezone' => 'Asia/Tokyo',
       'cacheMetadata' => true,
       'quoteIdentifiers' => false,
       'log' => false,
       'url' => env('DATABASE_TEST_URL', null),
   ],

テスト時に必要な設定

今回のハマリポイント。fixtureにも向き先を指定してやる必要がありました。
https://github.com/cakephp/cakephp/blob/master/src/TestSuite/Fixture/TestFixture.php#L39
冒頭の公式Doc3回位見つめたけど発見できず...

tests/Fixture/PiyosFixture.php

<?php
namespace App\Test\Fixture;

use Cake\TestSuite\Fixture\TestFixture;

class PiyosFixture extends TestFixture
{

    public $table = 'piyo';
    public $connection = 'test_fuga';

    (略)
}

最後に

ぐぐっていたときにCakePHP2には$useDbConfigがあり、fixtureで明示的に指定してあげるという記述を見かけました。
3系では上記の操作に値したようです。
やっぱりDocumentに頼ってばかりじゃなくてちゃんとソースコード読まないとだめですね。