gitlab-org--gitlab-foss/spec/migrations
Dmitriy Zaporozhets 1439115183 Merge branch 'gitaly-find-commit' into 'master'
Incorporate Gitaly's CommitService.FindCommit RPC

Closes gitaly#402

See merge request !13094
2017-08-08 14:27:22 +00:00
..
active_record Enable RSpec/FilePath cop 2017-04-26 12:50:32 +01:00
add_foreign_key_to_merge_requests_spec.rb Use batching to clear orphans in head_pipeline migration 2017-07-18 12:07:12 +02:00
add_head_pipeline_for_each_merge_request_spec.rb Change all :empty_project to :project 2017-08-02 17:47:31 -04:00
calculate_conv_dev_index_percentages_spec.rb Store & use ConvDev percentages returned by Version app 2017-08-07 20:52:08 +02:00
clean_appearance_symlinks_spec.rb Merge branch 'bvl-remove-appearance-symlink' into 'security-9-3' 2017-07-19 22:28:17 -05:00
clean_stage_id_reference_migration_spec.rb Fix background migration cleanup specs 2017-07-20 10:53:52 +02:00
clean_upload_symlinks_spec.rb Bring in security changes from the 9.2.5 release 2017-06-08 16:17:13 +02:00
cleanup_move_system_upload_folder_symlink_spec.rb Move the uploads/system folder to uploads/-/system 2017-07-18 15:38:54 +02:00
cleanup_namespaceless_pending_delete_projects_spec.rb Change all :empty_project to :project 2017-08-02 17:47:31 -04:00
convert_custom_notification_settings_to_columns_spec.rb Deserialise existing custom notification settings 2017-06-15 15:15:13 +01:00
fix_wrongly_renamed_routes_spec.rb Change all :empty_project to :project 2017-08-02 17:47:31 -04:00
migrate_build_stage_reference_again_spec.rb Rename stage ref migration specs to match a class name 2017-06-21 15:51:00 +02:00
migrate_old_artifacts_spec.rb Change all :empty_project to :project 2017-08-02 17:47:31 -04:00
migrate_pipeline_stages_spec.rb Migrate stages only with correct foreign references 2017-06-06 14:32:24 +02:00
migrate_process_commit_worker_jobs_spec.rb Incorporate Gitaly's CommitService.FindCommit RPC 2017-08-07 23:33:43 -04:00
migrate_stage_id_reference_in_background_spec.rb Do not schedule bg migration when it is not needed 2017-07-07 15:50:33 +02:00
migrate_user_activities_to_users_last_activity_on_spec.rb Support multiple Redis instances based on queue type 2017-07-11 03:35:47 +00:00
migrate_user_project_view_spec.rb Disable transaction in specs for some migrations 2017-06-22 12:35:47 +02:00
move_personal_snippets_files_spec.rb Merge branch '33359-pers-snippet-files-location' into 'security-9-3' 2017-07-19 22:28:27 -05:00
move_system_upload_folder_spec.rb Move the uploads/system folder to uploads/-/system 2017-07-18 15:38:54 +02:00
move_uploads_to_system_dir_spec.rb Bring in security changes from the 9.2.5 release 2017-06-08 16:17:13 +02:00
README.md Document a new migrations testing technique 2017-06-15 13:05:56 +02:00
remove_dot_git_from_usernames_spec.rb fix typo, added relevant spec 2017-01-16 16:11:50 +01:00
rename_duplicated_variable_key_spec.rb Rename the migration test to match the migration path 2017-06-27 18:29:23 +08:00
rename_more_reserved_project_names_spec.rb Change all :empty_project to :project 2017-08-02 17:47:31 -04:00
rename_reserved_project_names_spec.rb Change all :empty_project to :project 2017-08-02 17:47:31 -04:00
rename_system_namespaces_spec.rb Ensure all project factories use :repository trait or :empty_project 2017-08-01 14:51:52 -04:00
rename_users_with_renamed_namespace_spec.rb Simpler way of renaming users 2017-05-19 17:27:18 +02:00
schedule_merge_request_diff_migrations_spec.rb Migrate MR commits and diffs to new tables 2017-08-03 13:20:26 +01:00
turn_nested_groups_into_regular_groups_for_mysql_spec.rb Rename many path_with_namespace -> full_path 2017-08-01 07:26:58 +02:00
update_retried_for_ci_build_spec.rb Disable Migration/UpdateColumnInBatches for old migrations 2017-05-29 11:28:23 +02:00
update_upload_paths_to_system_spec.rb Change all :empty_project to :project 2017-08-02 17:47:31 -04:00

Testing migrations

In order to reliably test a migration, we need to test it against a database schema that this migration has been written for. In order to achieve that we have some migration helpers and RSpec test tag, called :migration.

If you want to write a test for a migration consider adding :migration tag to the test signature, like describe SomeMigrationClass, :migration.

How does it work?

Adding a :migration tag to a test signature injects a few before / after hooks to the test.

The most important change is that adding a :migration tag adds a before hook that will revert all migrations to the point that a migration under test is not yet migrated.

In other words, our custom RSpec hooks will find a previous migration, and migrate the database down to the previous migration version.

With this approach you can test a migration against a database schema that this migration has been written for.

Use migrate! helper to run the migration that is under test.

The after hook will migrate the database up and reinstitutes the latest schema version, so that the process does not affect subsequent specs and ensures proper isolation.

Available helpers

Use table helper to create a temporary ActiveRecord::Base derived model for a table.

Use migrate! helper to run the migration that is under test. It will not only run migration, but will also bump the schema version in the schema_migrations table. It is necessary because in the after hook we trigger the rest of the migrations, and we need to know where to start.

See spec/support/migrations_helpers.rb for all the available helpers.

An example

require 'spec_helper'

# Load a migration class.

require Rails.root.join('db', 'post_migrate', '20170526185842_migrate_pipeline_stages.rb')

describe MigratePipelineStages, :migration do

  # Create test data - pipeline and CI/CD jobs.

  let(:jobs) { table(:ci_builds) }
  let(:stages) { table(:ci_stages) }
  let(:pipelines) { table(:ci_pipelines) }
  let(:projects) { table(:projects) }

  before do
    projects.create!(id: 123, name: 'gitlab1', path: 'gitlab1')
    pipelines.create!(id: 1, project_id: 123, ref: 'master', sha: 'adf43c3a')
    jobs.create!(id: 1, commit_id: 1, project_id: 123, stage_idx: 2, stage: 'build')
    jobs.create!(id: 2, commit_id: 1, project_id: 123, stage_idx: 1, stage: 'test')
  end

  # Test the migration.

  it 'correctly migrates pipeline stages' do
    expect(stages.count).to be_zero

    migrate!

    expect(stages.count).to eq 2
    expect(stages.all.pluck(:name)).to match_array %w[test build]
  end
end

Best practices

  1. Use only one test example per migration unless there is a good reason to use more.
  2. Note that this type of tests do not run within the transaction, we use a truncation database cleanup strategy. Do not depend on transaction being present.