gitlab-org--gitlab-foss/spec/migrations
Grzegorz Bizon 15ace6a910 Merge commit '2be34630623711fc20ef8c101b5cef688f207cc1' into backstage/gb/rename-ci-cd-processing-sidekiq-queues
* commit '2be34630623711fc20ef8c101b5cef688f207cc1':
  Common Docker Documentation Location in `gitlab-ce`
  fix deprecation warning present during webpack compiles
  Enable 5 lines of Sidekiq backtrace lines to aid in debugging
  Add support for copying permalink to notes via more actions dropdown
  Handle creating a nested group on MySQL correctly
  Decrease statuses batch size even more in a migration
  Fix repo editor scrollbar
  Replace 'source/search_code.feature' spinach test with an rspec analog
  Authorizations regarding OAuth - style confirmation
  Update README.md
  Refactor complicated API group finding rules into GroupsFinder
  Fix group and project search for anonymous users
  Document version Group Milestones API introduced
  Allow v4 API GET requests for groups to be unauthenticated
  Adjust a range and a size in stages statuses migration
  Update README.md
  Point to /developers on docs/administration/authentiq.md
  Indexes GFM markdown guide
  use inline links instead of referenced
  Add index on ci_runners.contacted_at
2017-08-26 10:55:20 +02:00
..
active_record
add_foreign_key_to_merge_requests_spec.rb
add_head_pipeline_for_each_merge_request_spec.rb
calculate_conv_dev_index_percentages_spec.rb
clean_appearance_symlinks_spec.rb
clean_stage_id_reference_migration_spec.rb
clean_upload_symlinks_spec.rb
cleanup_move_system_upload_folder_symlink_spec.rb
cleanup_namespaceless_pending_delete_projects_spec.rb
cleanup_nonexisting_namespace_pending_delete_projects_spec.rb
convert_custom_notification_settings_to_columns_spec.rb
fix_wrongly_renamed_routes_spec.rb
migrate_build_stage_reference_again_spec.rb
migrate_old_artifacts_spec.rb
migrate_pipeline_sidekiq_queues_spec.rb
migrate_pipeline_stages_spec.rb
migrate_process_commit_worker_jobs_spec.rb
migrate_stage_id_reference_in_background_spec.rb
migrate_stages_statuses_spec.rb
migrate_user_activities_to_users_last_activity_on_spec.rb
migrate_user_project_view_spec.rb
move_personal_snippets_files_spec.rb
move_system_upload_folder_spec.rb
move_uploads_to_system_dir_spec.rb
README.md
remove_dot_git_from_usernames_spec.rb
remove_duplicate_mr_events_spec.rb
rename_duplicated_variable_key_spec.rb
rename_more_reserved_project_names_spec.rb
rename_reserved_project_names_spec.rb
rename_users_with_renamed_namespace_spec.rb
schedule_merge_request_diff_migrations_spec.rb
turn_nested_groups_into_regular_groups_for_mysql_spec.rb
update_retried_for_ci_build_spec.rb
update_upload_paths_to_system_spec.rb

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.

Testing a class that is not an ActiveRecord::Migration

In order to test a class that is not a migration itself, you will need to manually provide a required schema version. Please add a schema tag to a context that you want to switch the database schema within.

Example: describe SomeClass, :migration, schema: 20170608152748.

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. 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.